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



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

NNAAMMEE
       admin -- create and administer SCCS files (DDEEVVEELLOOPPMMEENNTT)

SSYYNNOOPPSSIISS
       admin -i[[_n_a_m_e]] [[-n]] [[-a _l_o_g_i_n]] [[-d _f_l_a_g]] [[-e _l_o_g_i_n]] [[-f _f_l_a_g]]
           [[-m _m_r_l_i_s_t]] [[-r _r_e_l]] [[-t[[_n_a_m_e]] [[-y[[_c_o_m_m_e_n_t]]]] _n_e_w_f_i_l_e

       admin -n [[-a _l_o_g_i_n]] [[-d _f_l_a_g]] [[-e _l_o_g_i_n]] [[-f _f_l_a_g]] [[-m _m_r_l_i_s_t]]
           [[-t[[_n_a_m_e]]]] [[-y[[_c_o_m_m_e_n_t]]]] _n_e_w_f_i_l_e...

       admin [[-a _l_o_g_i_n]] [[-d _f_l_a_g]] [[-m _m_r_l_i_s_t]] [[-r _r_e_l]] [[-t[[_n_a_m_e]]]] _f_i_l_e...

       admin -h _f_i_l_e...

       admin -z _f_i_l_e...

DDEESSCCRRIIPPTTIIOONN
       The _a_d_m_i_n 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._f_i_l_e_n_a_m_e. 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 _a_d_m_i_n shall be to a temporary _x_-_f_i_l_e, named
       x._f_i_l_e_n_a_m_e (see _g_e_t) created with read-only mode if _a_d_m_i_n 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 _a_d_m_i_n, the
       SCCS file shall be removed (if it exists), and the _x_-_f_i_l_e 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 _a_d_m_i_n utility shall also use a transient lock file (named
       z._f_i_l_e_n_a_m_e), which is used to prevent simultaneous updates to the SCCS
       file; see _g_e_t.

OOPPTTIIOONNSS
       The _a_d_m_i_n utility shall conform to the Base Definitions volume of
       POSIX.1-2017, _S_e_c_t_i_o_n _1_2_._2, _U_t_i_l_i_t_y _S_y_n_t_a_x _G_u_i_d_e_l_i_n_e_s, except that the
       --ii, --tt, and --yy options have optional option-arguments. These optional
       option-arguments shall not be presented as separate arguments. The
       following options are supported:

       --nn        Create a new SCCS file. When --nn is used without --ii, the SCCS
                 file shall be created with control information but without
                 any file data.

       --ii[[_n_a_m_e]]  Specify the _n_a_m_e 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 --rr option for the delta numbering scheme).
                 If the --ii option is used, but the _n_a_m_e 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 --ii option implies the --nn option.

       --rr _S_I_D    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.

       --tt[[_n_a_m_e]]  Specify the _n_a_m_e of a file from which descriptive text for
                 the SCCS file shall be taken.  In the case of existing SCCS
                 files (neither --ii nor --nn is specified):

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

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

       --ff _f_l_a_g   Specify a _f_l_a_g, and, possibly, a value for the _f_l_a_g, to be
                 placed in the SCCS file. Several --ff options may be supplied
                 on a single _a_d_m_i_n command line. Implementations shall
                 recognize the following flags and associated values:

                 bb       Allow use of the --bb option on a _g_e_t command to create
                         branch deltas.

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

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

                 dd_S_I_D    Specify the default delta number (SID) to be used by
                         a _g_e_t command.

                 ii_s_t_r    Treat the ``No ID keywords'' message issued by _g_e_t or
                         _d_e_l_t_a 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 _g_e_t) 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.

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

                 ll_l_i_s_t   Specify a _l_i_s_t of releases to which deltas can no
                         longer be made (that is, _g_e_t --ee against one of these
                         locked releases fails). Conforming applications shall
                         use the following syntax to specify a _l_i_s_t.
                         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 _l_i_s_t shall be equivalent to
                         specifying all releases for the named SCCS file.  The
                         non-terminal <_S_I_D> in range shall be the delta number
                         of an existing delta associated with the SCCS file.

                 nn       Cause _d_e_l_t_a 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 nn
                         flag may be ignored; that is, if the --rr 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.

                 qq_t_e_x_t   Substitute user-definable _t_e_x_t for all occurrences of
                         the %QQ% keyword in the SCCS file text retrieved by
                         _g_e_t.

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

                 tt_t_y_p_e   Specify the _t_y_p_e of module in the SCCS file
                         substituted for all occurrences of the %YY% keyword in
                         the SCCS file text retrieved by _g_e_t.

                 vv_p_g_m    Cause _d_e_l_t_a 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 mm option is also used even if its value is
                         null.)

       --dd _f_l_a_g   Remove (delete) the specified _f_l_a_g from an SCCS file. Several
                 --dd options may be supplied on a single _a_d_m_i_n command. See the
                 --ff option for allowable _f_l_a_g names. (The ll_l_i_s_t flag gives a
                 _l_i_s_t of releases to be unlocked. See the --ff option for
                 further description of the ll flag and the syntax of a _l_i_s_t.)

       --aa _l_o_g_i_n  Specify a _l_o_g_i_n 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 _l_o_g_i_n
                 names common to that group ID. Several --aa options may be used
                 on a single _a_d_m_i_n command line. As many _l_o_g_i_ns, 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
                 _l_o_g_i_n or group ID is preceded by a ''!!'', the users so
                 specified shall be denied permission to make deltas.

       --ee _l_o_g_i_n  Specify a _l_o_g_i_n 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 _l_o_g_i_n names common to that group ID. Several
                 --ee options may be used on a single _a_d_m_i_n command line.

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


                     "date and time created %s %s by %s", <_d_a_t_e>, <_t_i_m_e>, <_l_o_g_i_n>

                 where <_d_a_t_e> is expressed in the format of the _d_a_t_e utility's
                 %%yy/%%mm/%%dd conversion specification, <_t_i_m_e> in the format of
                 the _d_a_t_e utility's %%TT conversion specification format, and
                 <_l_o_g_i_n> is the login name of the user creating the file.

       --mm _m_r_l_i_s_t 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 _d_e_l_t_a.  The application shall ensure that
                 the vv flag is set and the MR numbers are validated if the vv
                 flag has a value (the name of an MR number validation
                 program).  A diagnostic message shall be written if the vv
                 flag is not set or MR validation fails.

       --hh        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.

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

OOPPEERRAANNDDSS
       The following operands shall be supported:

       _f_i_l_e      A pathname of an existing SCCS file or a directory. If _f_i_l_e
                 is a directory, the _a_d_m_i_n 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 ss..)  and unreadable files shall be silently
                 ignored.

       _n_e_w_f_i_l_e   A pathname of an SCCS file to be created.

       If exactly one _f_i_l_e or _n_e_w_f_i_l_e 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.

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

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

       The application shall ensure that the file named by the --ii option's
       _n_a_m_e 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.

EENNVVIIRROONNMMEENNTT VVAARRIIAABBLLEESS
       The following environment variables shall affect the execution of
       _a_d_m_i_n:

       _L_A_N_G      Provide a default value for the internationalization
                 variables that are unset or null. (See the Base Definitions
                 volume of POSIX.1-2017, _S_e_c_t_i_o_n _8_._2, _I_n_t_e_r_n_a_t_i_o_n_a_l_i_z_a_t_i_o_n
                 _V_a_r_i_a_b_l_e_s for the precedence of internationalization
                 variables used to determine the values of locale categories.)

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

       _L_C___C_T_Y_P_E  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).

       _L_C___M_E_S_S_A_G_E_S
                 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 --yy comment.

       _N_L_S_P_A_T_H   Determine the location of message catalogs for the processing
                 of _L_C___M_E_S_S_A_G_E_S.

AASSYYNNCCHHRROONNOOUUSS EEVVEENNTTSS
       Default.

SSTTDDOOUUTT
       Not used.

SSTTDDEERRRR
       The standard error shall be used only for diagnostic messages.

OOUUTTPPUUTT FFIILLEESS
       Any SCCS files created shall be text files of an unspecified format.
       During processing of a _f_i_l_e, a locking _z_-_f_i_l_e, as described in _g_e_t, may
       be created and deleted.

EEXXTTEENNDDEEDD DDEESSCCRRIIPPTTIIOONN
       None.

EEXXIITT SSTTAATTUUSS
       The following exit values shall be returned:

        0    Successful completion.

       >0    An error occurred.

CCOONNSSEEQQUUEENNCCEESS OOFF EERRRROORRSS
       Default.

       _T_h_e _f_o_l_l_o_w_i_n_g _s_e_c_t_i_o_n_s _a_r_e _i_n_f_o_r_m_a_t_i_v_e_.

AAPPPPLLIICCAATTIIOONN UUSSAAGGEE
       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.

EEXXAAMMPPLLEESS
       None.

RRAATTIIOONNAALLEE
       None.

FFUUTTUURREE DDIIRREECCTTIIOONNSS
       None.

SSEEEE AALLSSOO
       _d_e_l_t_a, _g_e_t, _p_r_s, _w_h_a_t

       The Base Definitions volume of POSIX.1-2017, _C_h_a_p_t_e_r _8, _E_n_v_i_r_o_n_m_e_n_t
       _V_a_r_i_a_b_l_e_s, _S_e_c_t_i_o_n _1_2_._2, _U_t_i_l_i_t_y _S_y_n_t_a_x _G_u_i_d_e_l_i_n_e_s

CCOOPPYYRRIIGGHHTT
       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(1)
