# admin

## PROLOG



           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



           admin — create and administer SCCS files (**DEVELOPMENT**)
    


## SYNOPSIS



           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



           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



           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.
    
                     **c** _ceil_   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.
    
                     **f** _floor_  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.
    
                     **d** _SID_    Specify the default delta number (SID) to be
                             used by a _get_ command.
    
                     **i** _str_    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.
    
                     **l** _list_   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.
    
                     **q** _text_   Substitute user-definable _text_ for all
                             occurrences of the %**Q** % keyword in the SCCS file
                             text retrieved by _get_.
    
                     **m** _mod_    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.
    
                     **t** _type_   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_.
    
                     **v** _pgm_    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 **l** _list_ 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 _login_ s, 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



           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



           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



           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



           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



           Default.
    


## STDOUT



           Not used.
    


## STDERR



           The standard error shall be used only for diagnostic messages.
    


## OUTPUT FILES



           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



           None.
    


## EXIT STATUS



           The following exit values shall be returned:
    
            0    Successful completion.
    
           >0    An error occurred.
    


## CONSEQUENCES OF ERRORS



           Default.
    
           _The following sections are informative._
    


## APPLICATION USAGE



           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



           None.
    


## RATIONALE



           None.
    


## FUTURE DIRECTIONS



           None.
    


* * *