diff options
Diffstat (limited to 'man1p/admin.1p')
| -rw-r--r-- | man1p/admin.1p | 436 |
1 files changed, 436 insertions, 0 deletions
diff --git a/man1p/admin.1p b/man1p/admin.1p new file mode 100644 index 000000000..28fe5afb5 --- /dev/null +++ b/man1p/admin.1p @@ -0,0 +1,436 @@ +.\" 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 . |