path: root/man1p/admin.1p

.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved 
.TH "ADMIN" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual"
.\" admin 
.SH NAME
admin \- create and administer SCCS files (\fBDEVELOPMENT\fP)
.SH SYNOPSIS
.LP
\fBadmin -i\fP\fB[\fP\fIname\fP\fB][\fP\fB-n\fP\fB][\fP\fB-a\fP
\fIlogin\fP\fB][\fP\fB-d\fP \fIflag\fP\fB][\fP\fB-e\fP \fIlogin\fP\fB][\fP\fB-f\fP
\fIflag\fP\fB][\fP\fB-m\fP
\fImrlist\fP\fB]
.br
\fP \fB\ \ \ \ \ \ \fP \fB[\fP\fB-r\fP
\fIrel\fP\fB][\fP\fB-t\fP\fB[\fP\fIname\fP\fB][\fP\fB-y\fP\fB[\fP\fIcomment\fP\fB]]\fP
\fInewfile\fP\fB
.br
.sp
admin -n\fP\fB[\fP\fB-a\fP \fIlogin\fP\fB][\fP\fB-d\fP \fIflag\fP\fB][\fP\fB-e\fP
\fIlogin\fP\fB][\fP\fB-f\fP
\fIflag\fP\fB][\fP\fB-m\fP \fImrlist\fP\fB][\fP\fB-t\fP\fB[\fP\fIname\fP\fB]]\fP\fB
.br
\ \ \ \ \ \ \fP \fB[\fP\fB-y\fP\fB[\fP\fIcomment\fP\fB]]\fP \fInewfile\fP
\fB\&...
.br
.sp
admin\fP \fB[\fP\fB-a\fP \fIlogin\fP\fB][\fP\fB-d\fP \fIflag\fP\fB][\fP\fB-m\fP
\fImrlist\fP\fB][\fP\fB-r\fP
\fIrel\fP\fB][\fP\fB-t\fP\fB[\fP\fIname\fP\fB]]\fP \fB\fP\fIfile\fP
\fB\&...
.br
.sp
admin -h\fP \fIfile\fP \fB...
.br
.sp
admin -z\fP \fIfile\fP \fB... \fP
\fB
.br
\fP
.SH DESCRIPTION
.LP
The \fIadmin\fP 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.
.LP
All SCCS filenames supplied by the application shall be of the form
s.\fIfilename\fP. 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 \fIadmin\fP shall be
to a temporary \fIx-file\fP, named x.\fIfilename\fP (see \fIget\fP
) created with read-only mode if
\fIadmin\fP 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 \fIadmin\fP, the SCCS file shall be removed
(if it exists), and the \fIx-file\fP 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.
.LP
The \fIadmin\fP utility shall also use a transient lock file (named
z.\fIfilename\fP), which is used to prevent simultaneous
updates to the SCCS file; see \fIget\fP .
.SH OPTIONS
.LP
The \fIadmin\fP utility shall conform to the Base Definitions volume
of IEEE\ Std\ 1003.1-2001, Section 12.2, Utility Syntax Guidelines,
except that the \fB-i\fP, \fB-t\fP, and
\fB-y\fP options have optional option-arguments. These optional option-arguments
shall not be presented as separate arguments. The
following options are supported:
.TP 7
\fB-n\fP
Create a new SCCS file. When \fB-n\fP is used without \fB-i\fP, the
SCCS file shall be created with control information but
without any file data.
.TP 7
\fB-i[\fP\fIname\fP\fB]\fP
Specify the \fIname\fP 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 \fB-r\fP option for the delta numbering scheme).
If the \fB-i\fP option is used, but the \fIname\fP
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 \fB-i\fP option implies the \fB-n\fP option.
.TP 7
\fB-r\ \fP \fISID\fP
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.
.TP 7
\fB-t[\fP\fIname\fP\fB]\fP
Specify the \fIname\fP of a file from which descriptive text for the
SCCS file shall be taken. In the case of existing SCCS
files (neither \fB-i\fP nor \fB-n\fP is specified): 
.RS
.IP " *" 3
A \fB-t\fP option without a \fIname\fP option-argument shall cause
the removal of descriptive text (if any) currently in the
SCCS file.
.LP
.IP " *" 3
A \fB-t\fP option with a \fIname\fP option-argument shall cause the
text (if any) in the named file to replace the descriptive
text (if any) currently in the SCCS file.
.LP
.RE
.TP 7
\fB-f\ \fP \fIflag\fP
Specify a \fIflag\fP, and, possibly, a value for the \fIflag\fP, to
be placed in the SCCS file. Several \fB-f\fP options may
be supplied on a single \fIadmin\fP command line. Implementations
shall recognize the following flags and associated values: 
.TP 7
\fBb\fP
.RS
Allow use of the \fB-b\fP option on a \fIget\fP command to create
branch deltas.
.RE
.TP 7
\fBc\fP\fIceil\fP
.RS
Specify the highest release (that is, ceiling), a number less than
or equal to 9999, which may be retrieved by a \fIget\fP command for
editing. The default value for an unspecified \fBc\fP flag shall be
9999.
.RE
.TP 7
\fBf\fP\fIfloor\fP
.RS
Specify the lowest release (that is, floor), a number greater than
0 but less than 9999, which may be retrieved by a \fIget\fP command
for editing. The default value for an unspecified \fBf\fP flag shall
be 1.
.RE
.TP 7
\fBd\fP\fISID\fP
.RS
Specify the default delta number (SID) to be used by a \fIget\fP command.
.RE
.TP 7
\fBi\fP\fIstr\fP
.RS
Treat the "No ID keywords" message issued by \fIget\fP or \fIdelta\fP
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 \fIget\fP
) 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>s.
.RE
.TP 7
\fBj\fP
.RS
Allow concurrent \fIget\fP commands for editing on the same SID of
an SCCS file. This
allows multiple concurrent updates to the same version of the SCCS
file.
.RE
.TP 7
\fBl\fP\fIlist\fP
.RS
Specify a \fIlist\fP of releases to which deltas can no longer be
made (that is, \fIget\fP \fB-e\fP against one of these locked releases
fails). Conforming applications shall use the
following syntax to specify a \fIlist\fP. Implementations may accept
additional forms as an extension: 
.sp
.RS
.nf

\fB<list> ::= a | <range-list>
<range-list> ::= <range> | <range-list>, <range>
<range> ::= <SID>
\fP
.fi
.RE
.LP
The character \fIa\fP in the \fIlist\fP shall be equivalent to specifying
all releases for the named SCCS file. The
non-terminal <\fISID\fP> in range shall be the delta number of an
existing delta associated with the SCCS file.
.RE
.TP 7
\fBn\fP
.RS
Cause \fIdelta\fP 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 \fBn\fP flag may
be ignored; that is, if the \fB-r\fP 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.
.RE
.TP 7
\fBq\fP\fItext\fP
.RS
Substitute user-definable \fItext\fP for all occurrences of the %\fBQ\fP%
keyword in the SCCS file text retrieved by \fIget\fP.
.RE
.TP 7
\fBm\fP\fImod\fP
.RS
Specify the module name of the SCCS file substituted for all occurrences
of the %\fBM\fP% keyword in the SCCS file text
retrieved by \fIget\fP. If the \fBm\fP flag is not specified, the
value assigned shall be the
name of the SCCS file with the leading \fB'.'\fP removed.
.RE
.TP 7
\fBt\fP\fItype\fP
.RS
Specify the \fItype\fP of module in the SCCS file substituted for
all occurrences of the %\fBY\fP% keyword in the SCCS file
text retrieved by \fIget\fP.
.RE
.TP 7
\fBv\fP\fIpgm\fP
.RS
Cause \fIdelta\fP 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 \fBm\fP option is
also used even if its value is null.)
.RE
.sp
.TP 7
\fB-d\ \fP \fIflag\fP
Remove (delete) the specified \fIflag\fP from an SCCS file. Several
\fB-d\fP options may be supplied on a single \fIadmin\fP
command. See the \fB-f\fP option for allowable \fIflag\fP names. (The
\fBl\fP \fIlist\fP flag gives a \fIlist\fP of releases
to be unlocked. See the \fB-f\fP option for further description of
the \fBl\fP flag and the syntax of a \fIlist\fP.)
.TP 7
\fB-a\ \fP \fIlogin\fP
Specify a \fIlogin\fP 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 \fIlogin\fP
names common to that group ID. Several \fB-a\fP options may be
used on a single \fIadmin\fP command line. As many \fIlogin\fPs, 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 \fIlogin\fP or group ID is preceded by a
\fB'!'\fP , the users so specified shall be denied permission to make
deltas.
.TP 7
\fB-e\ \fP \fIlogin\fP
Specify a \fIlogin\fP 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 \fIlogin\fP
names common to that group ID. Several \fB-e\fP
options may be used on a single \fIadmin\fP command line.
.TP 7
\fB-y[\fP\fIcomment\fP\fB]\fP
Insert the \fIcomment\fP text into the SCCS file as a comment for
the initial delta in a manner identical to that of \fIdelta\fP. In
the POSIX locale, omission of the \fB-y\fP option shall result in
a default comment
line being inserted in the form: 
.sp
.RS
.nf

\fB"date and time created %s %s by %s", <\fP\fIdate\fP\fB>, <\fP\fItime\fP\fB>, <\fP\fIlogin\fP\fB>
\fP
.fi
.RE
.LP
where <\fIdate\fP> is expressed in the format of the \fIdate\fP utility's
\fB%y\fP / \fB%m\fP / \fB%d\fP conversion specification, <\fItime\fP>
in the format of the \fIdate\fP utility's \fB%T\fP conversion specification
format, and <\fIlogin\fP> is the
login name of the user creating the file.
.TP 7
\fB-m\ \fP \fImrlist\fP
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 \fIdelta\fP. The application shall ensure that
the \fBv\fP flag is set
and the MR numbers are validated if the \fBv\fP flag has a value (the
name of an MR number validation program). A diagnostic
message shall be written if the \fBv\fP flag is not set or MR validation
fails.
.TP 7
\fB-h\fP
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.
.TP 7
\fB-z\fP
Recompute the SCCS file checksum and store it in the first line of
the SCCS file (see the \fB-h\fP option above). Note that
use of this option on a truly corrupted file may prevent future detection
of the corruption.
.sp
.SH OPERANDS
.LP
The following operands shall be supported:
.TP 7
\fIfile\fP
A pathname of an existing SCCS file or a directory. If \fIfile\fP
is a directory, the \fIadmin\fP 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 \fBs.\fP) and unreadable files shall be silently ignored.
.TP 7
\fInewfile\fP
A pathname of an SCCS file to be created.
.sp
.LP
If exactly one \fIfile\fP or \fInewfile\fP operand appears, and it
is \fB'-'\fP , 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.
.SH STDIN
.LP
The standard input shall be a text file used only if \fB-i\fP is specified
without an option-argument or if a \fIfile\fP or
\fInewfile\fP operand is specified as \fB'-'\fP . If the first character
of any standard input line is <SOH> in the POSIX
locale, the results are unspecified.
.SH INPUT FILES
.LP
The existing SCCS files shall be text files of an unspecified format.
.LP
The application shall ensure that the file named by the \fB-i\fP option's
\fIname\fP 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.
.SH ENVIRONMENT VARIABLES
.LP
The following environment variables shall affect the execution of
\fIadmin\fP:
.TP 7
\fILANG\fP
Provide a default value for the internationalization variables that
are unset or null. (See the Base Definitions volume of
IEEE\ Std\ 1003.1-2001, Section 8.2, Internationalization Variables
for
the precedence of internationalization variables used to determine
the values of locale categories.)
.TP 7
\fILC_ALL\fP
If set to a non-empty string value, override the values of all the
other internationalization variables.
.TP 7
\fILC_CTYPE\fP
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).
.TP 7
\fILC_MESSAGES\fP
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 \fB-y\fP comment.
.TP 7
\fINLSPATH\fP
Determine the location of message catalogs for the processing of \fILC_MESSAGES
\&.\fP
.sp
.SH ASYNCHRONOUS EVENTS
.LP
Default.
.SH STDOUT
.LP
Not used.
.SH STDERR
.LP
The standard error shall be used only for diagnostic messages.
.SH OUTPUT FILES
.LP
Any SCCS files created shall be text files of an unspecified format.
During processing of a \fIfile\fP, a locking
\fIz-file\fP, as described in \fIget\fP , may be created and deleted.
.SH EXTENDED DESCRIPTION
.LP
None.
.SH EXIT STATUS
.LP
The following exit values shall be returned:
.TP 7
\ 0
Successful completion.
.TP 7
>0
An error occurred.
.sp
.SH CONSEQUENCES OF ERRORS
.LP
Default.
.LP
\fIThe following sections are informative.\fP
.SH APPLICATION USAGE
.LP
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.
.SH EXAMPLES
.LP
None.
.SH RATIONALE
.LP
None.
.SH FUTURE DIRECTIONS
.LP
None.
.SH SEE ALSO
.LP
\fIdelta\fP , \fIget\fP , \fIprs\fP , \fIwhat\fP
.SH COPYRIGHT
Portions of this text are reprinted and reproduced in electronic form
from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology
-- Portable Operating System Interface (POSIX), The Open Group Base
Specifications Issue 6, Copyright (C) 2001-2003 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 .