Ubuntu Manpage: This manual page is part of the POSIX Programmer's Manual. The Linux implementation of this interface

Provided by: manpages-posix_2017a-2_all

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:

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.

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 .

IEEE/The Open Group                                   2017                                         ADMIN(1POSIX)