ADMIN(1P) POSIX Programmer's Manual ADMIN(1P)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.
NAMEadmin — create and administer SCCS files (DEVELOPMENT)
SYNOPSISadmin −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 speci‐
fied 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.file‐
name (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.file‐
name), 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‐2008, 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 fol‐
lowing 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 cre‐
ated 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 num‐
bers 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 descrip‐
tive 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 recog‐
nize 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. Imple‐
mentations may accept additional forms as an exten‐
sion:
<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 cre‐
ated 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 substi‐
tuted 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 creat‐
ing 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 fur‐
ther 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 speci‐
fied 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 speci‐
fying 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 pro‐
gram). 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 vari‐
ables that are unset or null. (See the Base Definitions vol‐
ume of POSIX.1‐2008, Section 8.2, Internationalization Vari‐
ables 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‐2008, 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, 2013 Edition, Standard for Information Technology
-- Portable Operating System Interface (POSIX), The Open Group Base
Specifications Issue 7, Copyright (C) 2013 by the Institute of Electri‐
cal and Electronics Engineers, Inc and The Open Group. (This is
POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) 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.unix.org/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.ker‐
nel.org/doc/man-pages/reporting_bugs.html .
IEEE/The Open Group 2013 ADMIN(1P)
