admin(1p) — Linux manual page

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‐2017, 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‐2017, 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‐2017, 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-2017, Standard for Information
       Technology -- Portable Operating System Interface (POSIX), The
       Open Group Base Specifications Issue 7, 2018 Edition, Copyright
       (C) 2018 by the Institute of Electrical and Electronics
       Engineers, Inc and The Open Group.  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.opengroup.org/unix/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               2017                         ADMIN(1P)

Pages that refer to this page: delta(1p)get(1p)prs(1p)rmdel(1p)sccs(1p)val(1p)