Provided by: manpages-posix_2017a-2_all bug

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

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.

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

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

SEE ALSO

       delta, get, prs, what

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

COPYRIGHT

       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 .