PROLOG | NAME | SYNOPSIS | DESCRIPTION | OPTIONS | OPERANDS | STDIN | INPUT FILES | ENVIRONMENT VARIABLES | ASYNCHRONOUS EVENTS | STDOUT | STDERR | OUTPUT FILES | EXTENDED DESCRIPTION | EXIT STATUS | CONSEQUENCES OF ERRORS | APPLICATION USAGE | EXAMPLES | RATIONALE | FUTURE DIRECTIONS | SEE ALSO | COPYRIGHT

ADMIN(1P)                 POSIX Programmer's Manual                ADMIN(1P)

PROLOG         top

       This manual page is part of the POSIX Programmer's Manual.  The Linux
       implementation of this interface may differ (consult the
       corresponding Linux manual page for details of Linux behavior), or
       the interface may not be implemented on Linux.

NAME         top

       admin — create and administer SCCS files (DEVELOPMENT)

SYNOPSIS         top

       admin −i[name] [−n] [−a login] [−d flag] [−e login] [−f flag]
           [−m mrlist] [−r rel] [−t[name] [−y[comment]] newfile

       admin −n [−a login] [−d flag] [−e login] [−f flag] [−m mrlist]
           [−t[name]] [−y[comment]] newfile...

       admin [−a login] [−d flag] [−m mrlist] [−r rel] [−t[name]] file...

       admin −h file...

       admin −z file...

DESCRIPTION         top

       The admin utility shall create new SCCS files or change parameters of
       existing ones. If a named file does not exist, it shall be created,
       and its parameters shall be initialized according to the specified
       options.  Parameters not initialized by an option shall be assigned a
       default value. If a named file does exist, parameters corresponding
       to specified options shall be changed, and other parameters shall be
       left as is.

       All SCCS filenames supplied by the application shall be of the form
       s.filename. New SCCS files shall be given read-only permission mode.
       Write permission in the parent directory is required to create a
       file. All writing done by admin shall be to a temporary x-file, named
       x.filename (see get(1p)) created with read-only mode if admin is
       creating a new SCCS file, or created with the same mode as that of
       the SCCS file if the file already exists. After successful execution
       of admin, the SCCS file shall be removed (if it exists), and the x-
       file shall be renamed with the name of the SCCS file. This ensures
       that changes are made to the SCCS file only if no errors occur.

       The admin utility shall also use a transient lock file (named
       z.filename), which is used to prevent simultaneous updates to the
       SCCS file; see get(1p).

OPTIONS         top

       The admin utility shall conform to the Base Definitions volume of
       POSIX.1‐2008, Section 12.2, Utility Syntax Guidelines, except that
       the −i, −t, and −y options have optional option-arguments. These
       optional option-arguments shall not be presented as separate
       arguments. The following options are supported:

       −n        Create a new SCCS file. When −n is used without −i, the
                 SCCS file shall be created with control information but
                 without any file data.

       −i[name]  Specify the name of a file from which the text for a new
                 SCCS file shall be taken. The text constitutes the first
                 delta of the file (see the −r option for the delta
                 numbering scheme). If the −i option is used, but the name
                 option-argument is omitted, the text shall be obtained by
                 reading the standard input. If this option is omitted, the
                 SCCS file shall be created with control information but
                 without any file data. The −i option implies the −n option.

       −r SID    Specify the SID of the initial delta to be inserted. This
                 SID shall be a trunk SID; that is, the branch and sequence
                 numbers shall be zero or missing. The level number is
                 optional, and defaults to 1.

       −t[name]  Specify the name of a file from which descriptive text for
                 the SCCS file shall be taken.  In the case of existing SCCS
                 files (neither −i nor −n is specified):

                  *  A −t option without a name option-argument shall cause
                     the removal of descriptive text (if any) currently in
                     the SCCS file.

                  *  A −t option with a name option-argument shall cause the
                     text (if any) in the named file to replace the
                     descriptive text (if any) currently in the SCCS file.

       −f flag   Specify a flag, and, possibly, a value for the flag, to be
                 placed in the SCCS file. Several −f options may be supplied
                 on a single admin command line. Implementations shall
                 recognize the following flags and associated values:

                 b       Allow use of the −b option on a get command to
                         create branch deltas.

                 cceil   Specify the highest release (that is, ceiling), a
                         number less than or equal to 9999, which may be
                         retrieved by a get command for editing. The default
                         value for an unspecified c flag shall be 9999.

                 ffloor  Specify the lowest release (that is, floor), a
                         number greater than 0 but less than 9999, which may
                         be retrieved by a get command for editing. The
                         default value for an unspecified f flag shall be 1.

                 dSID    Specify the default delta number (SID) to be used
                         by a get command.

                 istr    Treat the ``No ID keywords'' message issued by get
                         or delta as a fatal error. In the absence of this
                         flag, the message is only a warning. The message is
                         issued if no SCCS identification keywords (see
                         get(1p)) are found in the text retrieved or stored
                         in the SCCS file. If a value is supplied, the
                         application shall ensure that the keywords exactly
                         match the given string; however, the string shall
                         contain a keyword, and no embedded <newline>
                         characters.

                 j       Allow concurrent get commands for editing on the
                         same SID of an SCCS file. This allows multiple
                         concurrent updates to the same version of the SCCS
                         file.

                 llist   Specify a list of releases to which deltas can no
                         longer be made (that is, get −e against one of
                         these locked releases fails). Conforming
                         applications shall use the following syntax to
                         specify a list.  Implementations may accept
                         additional forms as an extension:

                             <list> ::= a | <range-list>
                             <range-list> ::= <range> | <range-list>, <range>
                             <range> ::= <SID>

                         The character a in the list shall be equivalent to
                         specifying all releases for the named SCCS file.
                         The non-terminal <SID> in range shall be the delta
                         number of an existing delta associated with the
                         SCCS file.

                 n       Cause delta to create a null delta in each of those
                         releases (if any) being skipped when a delta is
                         made in a new release (for example, in making delta
                         5.1 after delta 2.7, releases 3 and 4 are skipped).
                         These null deltas shall serve as anchor points so
                         that branch deltas may later be created from them.
                         The absence of this flag shall cause skipped
                         releases to be nonexistent in the SCCS file,
                         preventing branch deltas from being created from
                         them in the future. During the initial creation of
                         an SCCS file, the n flag may be ignored; that is,
                         if the −r option is used to set the release number
                         of the initial SID to a value greater than 1, null
                         deltas need not be created for the ``skipped''
                         releases.

                 qtext   Substitute user-definable text for all occurrences
                         of the %Q% keyword in the SCCS file text retrieved
                         by get.

                 mmod    Specify the module name of the SCCS file
                         substituted for all occurrences of the %M% keyword
                         in the SCCS file text retrieved by get.  If the m
                         flag is not specified, the value assigned shall be
                         the name of the SCCS file with the leading '.'
                         removed.

                 ttype   Specify the type of module in the SCCS file
                         substituted for all occurrences of the %Y% keyword
                         in the SCCS file text retrieved by get.

                 vpgm    Cause delta to prompt for modification request (MR)
                         numbers as the reason for creating a delta. The
                         optional value specifies the name of an MR number
                         validation program. (If this flag is set when
                         creating an SCCS file, the application shall ensure
                         that the m option is also used even if its value is
                         null.)

       −d flag   Remove (delete) the specified flag from an SCCS file.
                 Several −d options may be supplied on a single admin
                 command. See the −f option for allowable flag names. (The
                 llist flag gives a list of releases to be unlocked. See the
                 −f option for further description of the l flag and the
                 syntax of a list.)

       −a login  Specify a login name, or numerical group ID, to be added to
                 the list of users who may make deltas (changes) to the SCCS
                 file. A group ID shall be equivalent to specifying all
                 login names common to that group ID. Several −a options may
                 be used on a single admin command line. As many logins, or
                 numerical group IDs, as desired may be on the list
                 simultaneously.  If the list of users is empty, then anyone
                 may add deltas. If login or group ID is preceded by a '!',
                 the users so specified shall be denied permission to make
                 deltas.

       −e login  Specify a login name, or numerical group ID, to be erased
                 from the list of users allowed to make deltas (changes) to
                 the SCCS file. Specifying a group ID is equivalent to
                 specifying all login names common to that group ID. Several
                 −e options may be used on a single admin command line.

       −y[comment]
                 Insert the comment text into the SCCS file as a comment for
                 the initial delta in a manner identical to that of delta.
                 In the POSIX locale, omission of the −y option shall result
                 in a default comment line being inserted in the form:

                     "date and time created %s %s by %s", <date>, <time>, <login>

                 where <date> is expressed in the format of the date
                 utility's %y/%m/%d conversion specification, <time> in the
                 format of the date utility's %T conversion specification
                 format, and <login> is the login name of the user creating
                 the file.

       −m mrlist Insert the list of modification request (MR) numbers into
                 the SCCS file as the reason for creating the initial delta
                 in a manner identical to delta.  The application shall
                 ensure that the v flag is set and the MR numbers are
                 validated if the v flag has a value (the name of an MR
                 number validation program).  A diagnostic message shall be
                 written if the v flag is not set or MR validation fails.

       −h        Check the structure of the SCCS file and compare the newly
                 computed checksum with the checksum that is stored in the
                 SCCS file. If the newly computed checksum does not match
                 the checksum in the SCCS file, a diagnostic message shall
                 be written.

       −z        Recompute the SCCS file checksum and store it in the first
                 line of the SCCS file (see the −h option above). Note that
                 use of this option on a truly corrupted file may prevent
                 future detection of the corruption.

OPERANDS         top

       The following operands shall be supported:

       file      A pathname of an existing SCCS file or a directory. If file
                 is a directory, the admin utility shall behave as though
                 each file in the directory were specified as a named file,
                 except that non-SCCS files (last component of the pathname
                 does not begin with s.)  and unreadable files shall be
                 silently ignored.

       newfile   A pathname of an SCCS file to be created.

       If exactly one file or newfile operand appears, and it is '−', the
       standard input shall be read; each line of the standard input shall
       be taken to be the name of an SCCS file to be processed. Non-SCCS
       files and unreadable files shall be silently ignored.

STDIN         top

       The standard input shall be a text file used only if −i is specified
       without an option-argument or if a file or newfile operand is
       specified as '−'.  If the first character of any standard input line
       is <SOH> in the POSIX locale, the results are unspecified.

INPUT FILES         top

       The existing SCCS files shall be text files of an unspecified format.

       The application shall ensure that the file named by the −i option's
       name option-argument shall be a text file; if the first character of
       any line in this file is <SOH> in the POSIX locale, the results are
       unspecified. If this file contains more than 99999 lines, the number
       of lines recorded in the header for this file shall be 99999 for this
       delta.

ENVIRONMENT VARIABLES         top

       The following environment variables shall affect the execution of
       admin:

       LANG      Provide a default value for the internationalization
                 variables that are unset or null. (See the Base Definitions
                 volume of POSIX.1‐2008, Section 8.2, Internationalization
                 Variables for the precedence of internationalization
                 variables used to determine the values of locale
                 categories.)

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

       LC_CTYPE  Determine 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
                 Determine the locale that should be used to affect the
                 format and contents of diagnostic messages written to
                 standard error and the contents of the default −y comment.

       NLSPATH   Determine the location of message catalogs for the
                 processing of LC_MESSAGES.

ASYNCHRONOUS EVENTS         top

       Default.

STDOUT         top

       Not used.

STDERR         top

       The standard error shall be used only for diagnostic messages.

OUTPUT FILES         top

       Any SCCS files created shall be text files of an unspecified format.
       During processing of a file, a locking z-file, as described in
       get(1p), may be created and deleted.

EXTENDED DESCRIPTION         top

       None.

EXIT STATUS         top

       The following exit values shall be returned:

        0    Successful completion.

       >0    An error occurred.

CONSEQUENCES OF ERRORS         top

       Default.

       The following sections are informative.

APPLICATION USAGE         top

       It is recommended that directories containing SCCS files be writable
       by the owner only, and that SCCS files themselves be read-only. The
       mode of the directories should allow only the owner to modify SCCS
       files contained in the directories. The mode of the SCCS files
       prevents any modification at all except by SCCS commands.

EXAMPLES         top

       None.

RATIONALE         top

       None.

FUTURE DIRECTIONS         top

       None.

SEE ALSO         top

       delta(1p), get(1p), prs(1p), what(1p)

       The Base Definitions volume of POSIX.1‐2008, Chapter 8, Environment
       Variables, Section 12.2, Utility Syntax Guidelines

COPYRIGHT         top

       Portions of this text are reprinted and reproduced in electronic form
       from IEEE Std 1003.1, 2013 Edition, Standard for Information
       Technology -- Portable Operating System Interface (POSIX), The Open
       Group Base Specifications Issue 7, Copyright (C) 2013 by the
       Institute of Electrical and Electronics Engineers, Inc and The Open
       Group.  (This is POSIX.1-2008 with the 2013 Technical Corrigendum 1
       applied.) In the event of any discrepancy between this version and
       the original IEEE and The Open Group Standard, the original IEEE and
       The Open Group Standard is the referee document. The original
       Standard can be obtained online at http://www.unix.org/online.html .

       Any typographical or formatting errors that appear in this page are
       most likely to have been introduced during the conversion of the
       source files to man page format. To report such errors, see
       https://www.kernel.org/doc/man-pages/reporting_bugs.html .

IEEE/The Open Group                 2013                           ADMIN(1P)