admin

Document Sample
admin Powered By Docstoc
					ADMIN(P)                                    POSIX Programmer’s Manual                                        ADMIN(P)


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, parame-
       ters 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 simultane-
       ous updates to the SCCS file; see get .
OPTIONS
       The admin utility shall conform to the Base Definitions volume of IEEE Std 1003.1-2001, 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 sup-
       ported:
       -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 consti-
                  tutes 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.




IEEE/The Open Group                                      2003                                                          1
ADMIN(P)                                 POSIX Programmer’s Manual                                        ADMIN(P)


                * 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>s.
       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


IEEE/The Open Group                                    2003                                                          2
ADMIN(P)                                   POSIX Programmer’s Manual                                      ADMIN(P)


                  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 sin-
              gle admin command. See the -f option for allowable flag names. (The l list 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 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 check-
                  sum that is stored in the SCCS file. If the newly computed checksum does not match the check-
                  sum 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:




IEEE/The Open Group                                     2003                                                        3
ADMIN(P)                                     POSIX Programmer’s Manual                                         ADMIN(P)


        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 unread-
        able 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 IEEE Std 1003.1-2001, 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.




IEEE/The Open Group                                        2003                                                           4
ADMIN(P)                                   POSIX Programmer’s Manual                                ADMIN(P)


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




IEEE/The Open Group                                   2003                                                    5

				
DOCUMENT INFO