unixdev.net


Switch to SpeakEasy.net DSL

The Modular Manual Browser

Home Page
Manual: (OSF1-V5.1-alpha)
Page:
Section:
Apropos / Subsearch:
optional field



admin(1)							     admin(1)



NAME

  admin	- Creates and initializes or changes (administers) Source Code Con-
  trol System (SCCS) files

SYNOPSIS

  The admin command creates and	initializes new	Source Code Control System
  (SCCS) files or changes specified parameters in existing SCCS	files.

  Creating and Initializing SCCS Files


  admin	[-a user] [-i[file]] | [-n] [-f	header_flag[value]] [-m	MRlist]	[-r
  number[.number]] [-t[file]] [-y[comment]] sccs_file |	-

  Changing Existing SCCS Files


  admin	[-a user] [-e user] [-d	header_flag] [-f header_flag[value]] [-h]
  [-t[file]] [-z] sccs_file | -

STANDARDS

  Interfaces documented	on this	reference page conform to industry standards
  as follows:

  admin:  XCU5.0

  Refer	to the standards(5) reference page for more information	about indus-
  try standards	and associated tags.

OPTIONS

  -a user
      Adds the specified user to the list of users who can make	sets of
      changes (deltas) to the SCCS file.  The user argument can	be either a
      user name, a group name, or a group ID. Specifying a group name or
      number is	the same as specifying the names of all	users in that group.
      You can specify more than	one -a option on a single admin	command	line.
      If an SCCS file contains an empty	user list, anyone can add deltas.

      If you precede user by an	! (exclamation point), the users specified
      are denied permission to make deltas.

      [Tru64 UNIX]  If a file has a user list, the creator of the file must
      be included in the list in order for the creator to make deltas to the
      file.

  -d header-flag
      Removes the specified header flag	from the SCCS file. You	can specify
      this option only with existing SCCS files.  You can also specify more
      than one -d option in a single admin command.

  -e user
      Removes the specified user from the list of users	allowed	to make	del-
      tas to the SCCS file.  Specifying	a group	ID is equivalent to specify-
      ing all user names common	to that	group.	You can	specify	several	-e
      options on a single admin	command	line. You can specify this option
      only with	existing SCCS files.  See also the -a option.

  -f header-flag[value]
      Places the specified header flag and value in the	SCCS file.  You	can
      specify more than	one header flag	in a single admin command.

  -h  Checks the structure of the SCCS file and	compares a newly computed
      checksum with the	checksum that is stored	in the first line of the SCCS
      file.  When the checksum value is	not correct, the file was improperly
      modified or damaged.  This option	helps you detect damage	caused by the
      improper use of non-SCCS commands	to modify SCCS files, as well as
      accidental damage.  The -h option	prevents writing to the	file, so it
      cancels the effect of any	other options supplied.	 If an error message
      is returned indicating the file is damaged, use the -z option to recom-
      pute the checksum.  Then test to see if the file has been	corrected by
      using the	-h option again.

  -i[file]
      Gets the text for	a new SCCS file	from file.  This text is the first
      delta of the file.  If you specify the -i	option but you omit the	file
      argument,	admin reads the	text from standard input until it reaches
      End-of-File(Ctrl-D).  If you do not specify the -i option, but you do
      specify the -n option, admin creates an empty SCCS file.	The admin
      command can create only one file containing text at a time.  If you are
      creating two or more SCCS	files with one call to admin, you must use
      the -n option, and the SCCS files	created	are empty.

  -m MRlist
      Specifies	a list of Modification Request (MR) numbers to be inserted
      into the SCCS file as the	reason for creating the	initial	delta.	The v
      flag must	be set.	 The MR	numbers	are validated if the v flag has	a
      value (the name of an MR number validation program).  The	admin command
      reports an error if the v	flag is	not set	or if the MR validation
      fails.

  -n  Creates a	new, empty SCCS	file.

      [Tru64 UNIX]  Do not specify this	option when you	use the	-i option.
      See the description of the -i option for details.

  -r number[.number]
      Inserts the initial delta	into number.number, the	release	and version,
      respectively.  You can specify -r	only if	you also specify the -i	or -n
      option.  If you do not specify this option, the initial delta becomes
      release 1, version 1.  Use this option only when creating	an SCCS	file.
      If the version number is omitted,	the version is set to 1	by default.

  -t[file]
      Takes descriptive	text for the SCCS file from file.  If you use -t when
      creating a new SCCS file,	you must supply	a file name.

	+  In the case of an existing SCCS file	without	a file name, -t
	   causes removal of the descriptive text (if any) currently in	the
	   SCCS	file.

	+  In the case of an existing SCCS file	with a file name, -t causes
	   text	in the named file to replace the descriptive text (if any)
	   currently in	the SCCS file.

  -y[comment]
      Inserts comment text into	the initial delta in a manner identical	to
      that of the delta	command.  Use the -y option only when you create an
      SCCS file.  If you do not	specify	a comment, admin inserts a line	of
      the following form:
	   date	and time created YY/MM/DD HH:MM:SS by login

      [Tru64 UNIX]  If YY is 69	to 99, the year	is interpreted as being	in
      the twentieth century, i.e. 19YY.	Otherwise, the year is interpreted as
      being in the twenty-first	century, i.e. 20YY.

  -z  Recomputes the SCCS file checksum	and stores it in the first line	of
      the SCCS file.  (See the -h option description.)

      Using admin with this option on a	damaged	file can prevent future
      detection	of the damage.	Use this option	only if	the SCCS file is
      changed using non-SCCS commands because of a previous serious error.

OPERANDS

  sccs_file
      The name of an SCCS file to be created or	modified.

      If the named file	exists,	admin modifies its parameters as specified by
      the flags.  If it	does not exist and you supply the -i option or the -n
      option, admin creates the	new file and provides default values for
      unspecified options.

      If you specify a directory name for file,	admin performs the requested
      actions on all SCCS files	in that	directory (all files with the s. pre-
      fix).

      If you specify a - (hyphen) as a file name, admin	reads standard input
      and interprets each line as the name of an SCCS file.  An	End-of-File
      character	ends input.

DESCRIPTION

  The parameters that can be modified by admin control how the get command
  builds the files that	you can	edit.  The parameters also provide informa-
  tion about who can access the	file, who can make changes, and	when changes
  were made.

  [Tru64 UNIX]	The admin command is most often	used to	create new SCCS	files
  without setting parameters.

  [Tru64 UNIX]	If you are not familiar	with the delta numbering system, see
  the get(1), sccs(1) reference	pages, and the Programming Support Tools
  book.

  Creating an SCCS File


  All SCCS file	names must have	the form s.file. New SCCS files	are created
  with read-only permission.  You must have write permission in	the directory
  to create a file.  (See the chmod(1) reference page for an explanation of
  file permissions). The admin command writes to a temporary x-file, which it
  calls	x.file.	 The x-file has	the same permissions as	the original SCCS
  file if it already exists, and it is read-only if admin creates a new	file.
  After	successful completion of admin,	the x-file is moved to the name	of
  the SCCS file. This action ensures that changes are made to the SCCS file
  only if admin	does not detect	any errors while it is running.

  You should create directories	containing SCCS	files with permission code
  755 (read, write, and	execute	permissions for	owner, read and	execute	per-
  missions for group members and others).  You should create SCCS files	them-
  selves as read-only files (444).  With these permissions, only the owner
  can use non-SCCS commands to modify SCCS files.  If a	group can access and
  modify the SCCS files, make sure the directories include group write per-
  mission.

  The admin command also uses a	temporary lock file (called z.file) to
  prevent simultaneous updates to the SCCS file	by different users.  See the
  get(1) reference page	for additional information on the z.file file.

  Header Flags


  The following	table contains the header flags	that can be set	with the -f
  option and unset with	the -d option.	The header flags control the format
  of the g-file	created	with the get command.  (See the	get(1) reference page
  for details on the g-file.)

  b   Lets you use the -b option of a get command to create branch deltas.

  cnumber
      Makes number the highest release number that a get -e command can	use.
      The value	of number must be less than or equal to	9999.  Its default
      value is 9999.

  dSID
      Makes SID	(SCCS ID) the default delta supplied to	a get command.

  fnumber
      Makes number the lowest release number that a get	-e command can
      retrieve.	 The number argument must be greater than 0 and	less than
      9999.  Its default value is 1.

  i[keyword]
      Treats the message "There	are no SCCS identification keywords in the
      file. (cm7)" (issued by the get or delta command)	as an error instead
      of a warning.

      You may use keyword to specify that a particular keyword,	or set of
      keywords,	separated by blanks and	tab characters,	must be	found in the
      file.

  j   Permits concurrent get commands for editing the same SID of an SCCS
      file.  This flag allows multiple concurrent updates to the same version
      of the SCCS file.	 This flag is sometimes	called the "joint edit"	flag.

  lnumber[,number ...]
      Locks the	releases specified by number...	 against editing, so that a
      get -e command against one of these releases fails.  If you specify
      number as	a, this	is equivalent to specifying all	releases in the	file.

      [Tru64 UNIX]  You	can lock all releases against editing by specifying
      -fla and unlock specific releases	with the -d option.

  mmodule
      Substitutes module for all occurrences of	the %M%	keyword	in an SCCS
      text file	retrieved by a get command. The	default	module is the name of
      the SCCS file without the	s. prefix.

  n   Causes delta to create a null delta in any releases that are skipped
      when a delta is made in a	new release.  For example, if you make delta
      5.1 after	delta 2.7, releases 3 and 4 will be null.  The resulting null
      deltas can serve as points from which to build branch deltas.  Without
      this flag, skipped releases do not appear	in the SCCS file.

  qtext
      Substitutes text for all occurrences of the %Q% keyword in an SCCS text
      file retrieved by	a get command.

  ttype
      Substitutes type for all occurrences of the %Y% keyword in a g-file
      retrieved	by get.

  v[program]
      Makes delta prompt for Modification Request (MR) numbers as the reason
      for creating a delta.  The program argument specifies the	name of	an MR
      number validity checking program.	 (See the delta(1) reference page.)
      If v is set in the SCCS file, the	admin -m option	must also be used,
      even if its value	is null.

EXIT STATUS

  The following	exit values are	returned:

  0   Successful completion.

  >>0  An error occurred.

EXAMPLES

   1.  To create an empty SCCS file named s.test.c, enter:
	    admin  -n  s.test.c

   2.  To convert an existing text file	into an	SCCS file, enter:
	    admin -itest.c s.test.c

       The admin command responds with the message:
	    There are no SCCS identification keywords in the file. (cm7)

       This message does not indicate an error.

   3.  To rename the original text file, enter:
	    mv oldname.c  newname.c

   4.  Identification keywords are variables that can be placed	in an SCCS
       file.  The values of these variables provide information, such as
       date, time, SID,	or file	name.  See the get(1) reference	page for an
       explanation of identification keywords.

       Whether creating	new files or converting	an existing file, you can
       name the	SCCS file anything you like, as	long as	it begins with the s.
       prefix.	In this	example, the original file and the SCCS	file have the
       same name, but that is not required.

       When you	do not specify a release number, as in both of the preceding
       examples, admin gives the SCCS file an SID of 1.1.  SCCS	does not use
       the number 0 to identify	deltas.	 Therefore, a file cannot have an SID
       of 1.0 or 2.1.1.0. All new releases start with level 1.	To start the
       s.test.c	file with a release number of 3, use the -r option with	the
       admin command, and enter:
	    admin -itest.c -r3 s.test.c

   5.  To restrict permission to change	SCCS files to a	specific set of	user
       IDs, list the user ID or	group ID numbers in the	user list of the SCCS
       file with the -a	option.	 These IDs then	appear in the SCCS file
       header.	Without	the -a option to restrict access, all user IDs can
       change the SCCS files. To restrict permissions to the user ID julie,
       enter:
	    admin -ajulie s.test.c

   6.  Although	SCCS provides some error protection, you might need to
       recover a file that was accidentally damaged.  This damage can result
       from a system malfunction, operator error, or changing an SCCS file
       without using SCCS commands.

       SCCS commands use the checksum to determine whether a file was changed
       since it	was last used.	The only SCCS command that processes a dam-
       aged file is the	admin command when used	with the -h or -z option.
       The -h option tells admin to compare the	checksum stored	in the SCCS
       file header against the computed	checksum.  The -z option tells admin
       to recompute the	checksum and store it in the file header.

       Check the SCCS files for	possible damage	on a regular basis. For	exam-
       ple, enter:
	    admin -h s.file1 s.file2 ...
	    admin -h directory1	directory2 ...

       If admin	finds a	file where the computed	checksum is not	equal to the
       checksum	listed in the SCCS file	header,	it displays the	message	of
       the form:
	    [s.file]: The file is damaged. (co6)

   7.  If a file is damaged, try to edit the file again, or read a backup
       copy.  After fixing the file, run the admin command with	the -z option
       and the repaired	file name by entering:
	    admin -z s.file

       This operation replaces the old checksum	in the SCCS file header	with
       a new checksum based on the repaired file contents.  Other SCCS com-
       mands can now process the file.

ENVIRONMENT VARIABLES

  The following	environment variables affect the execution of admin:

  LANG
      Provides a default value for the internationalization variables that
      are unset	or null. If LANG is unset or null, the corresponding value
      from the default locale is used.	If any of the internationalization
      variables	contain	an invalid setting, the	utility	behaves	as if none of
      the variables had	been defined.

  LC_ALL
      If set to	a non-empty string value, overrides the	values of all the
      other internationalization variables.

  LC_CTYPE
      Determines the locale for	the interpretation of sequences	of bytes of
      text data	as characters (for example, single-byte	as opposed to multi-
      byte characters in arguments and input files).

  LC_MESSAGES
      Determines the locale for	the format and contents	of diagnostic mes-
      sages written to standard	error.

  NLSPATH
      Determines the location of message catalogues for	the processing of
      LC_MESSAGES.

SEE ALSO

  Commands:  cdc(1), comb(1), delta(1),	ed(1), get(1), prs(1), rmdel(1),
  sact(1), sccs(1), sccsdiff(1), sccshelp(1), unget(1),	val(1),	what(1)

  Files:  sccsfile(4)

  Standards:  standards(5)

  Programming Support Tools