1ADMIN(1P) POSIX Programmer's Manual ADMIN(1P)
2
6 This manual page is part of the POSIX Programmer's Manual. The Linux
7 implementation of this interface may differ (consult the corresponding
8 Linux manual page for details of Linux behavior), or the interface may
9 not be implemented on Linux.
10
12 admin - create and administer SCCS files (DEVELOPMENT)
13
15 admin -i[name][-n][-a login][-d flag][-e login][-f flag][-m mrlist]
16 [-r rel][-t[name][-y[comment]] newfile
17 admin -n[-a login][-d flag][-e login][-f flag][-m mrlist][-t[name]]
19 [-y[comment]] newfile ...
20 admin [-a login][-d flag][-m mrlist][-r rel][-t[name]] file ...
22 admin -h file ...
24 admin -z file ...
26
29 The admin utility shall create new SCCS files or change parameters of
30 existing ones. If a named file does not exist, it shall be created, and
31 its parameters shall be initialized according to the specified options.
32 Parameters not initialized by an option shall be assigned a default
33 value. If a named file does exist, parameters corresponding to speci‐
34 fied options shall be changed, and other parameters shall be left as
35 is.
36 All SCCS filenames supplied by the application shall be of the form
38 s.filename. New SCCS files shall be given read-only permission mode.
39 Write permission in the parent directory is required to create a file.
40 All writing done by admin shall be to a temporary x-file, named x.file‐
41 name (see get ) created with read-only mode if admin is creating a new
42 SCCS file, or created with the same mode as that of the SCCS file if
43 the file already exists. After successful execution of admin, the SCCS
44 file shall be removed (if it exists), and the x-file shall be renamed
45 with the name of the SCCS file. This ensures that changes are made to
46 the SCCS file only if no errors occur.
47 The admin utility shall also use a transient lock file (named z.file‐
49 name), which is used to prevent simultaneous updates to the SCCS file;
50 see get .
51
53 The admin utility shall conform to the Base Definitions volume of
54 IEEE Std 1003.1-2001, Section 12.2, Utility Syntax Guidelines, except
55 that the -i, -t, and -y options have optional option-arguments. These
56 optional option-arguments shall not be presented as separate arguments.
57 The following options are supported:
58 -n Create a new SCCS file. When -n is used without -i, the SCCS
60 file shall be created with control information but without any
61 file data.
62 -i[name]
64 Specify the name of a file from which the text for a new SCCS
65 file shall be taken. The text constitutes the first delta of the
66 file (see the -r option for the delta numbering scheme). If the
67 -i option is used, but the name option-argument is omitted, the
68 text shall be obtained by reading the standard input. If this
69 option is omitted, the SCCS file shall be created with control
70 information but without any file data. The -i option implies
71 the -n option.
72 -r SID
74 Specify the SID of the initial delta to be inserted. This SID
75 shall be a trunk SID; that is, the branch and sequence numbers
76 shall be zero or missing. The level number is optional, and
77 defaults to 1.
78 -t[name]
80 Specify the name of a file from which descriptive text for the
81 SCCS file shall be taken. In the case of existing SCCS files
82 (neither -i nor -n is specified):
83 * A -t option without a name option-argument shall cause the
85 removal of descriptive text (if any) currently in the SCCS
86 file.
87 * A -t option with a name option-argument shall cause the text
89 (if any) in the named file to replace the descriptive text
90 (if any) currently in the SCCS file.
91 -f flag
93 Specify a flag, and, possibly, a value for the flag, to be
94 placed in the SCCS file. Several -f options may be supplied on a
95 single admin command line. Implementations shall recognize the
96 following flags and associated values:
97 b
99 Allow use of the -b option on a get command to create branch
100 deltas.
101 cceil
103 Specify the highest release (that is, ceiling), a number less
104 than or equal to 9999, which may be retrieved by a get command
105 for editing. The default value for an unspecified c flag shall
106 be 9999.
107 ffloor
109 Specify the lowest release (that is, floor), a number greater
110 than 0 but less than 9999, which may be retrieved by a get com‐
111 mand for editing. The default value for an unspecified f flag
112 shall be 1.
113 dSID
115 Specify the default delta number (SID) to be used by a get com‐
116 mand.
117 istr
119 Treat the "No ID keywords" message issued by get or delta as a
120 fatal error. In the absence of this flag, the message is only a
121 warning. The message is issued if no SCCS identification key‐
122 words (see get ) are found in the text retrieved or stored in
123 the SCCS file. If a value is supplied, the application shall
124 ensure that the keywords exactly match the given string; how‐
125 ever, the string shall contain a keyword, and no embedded <new‐
126 line>s.
127 j
129 Allow concurrent get commands for editing on the same SID of an
130 SCCS file. This allows multiple concurrent updates to the same
131 version of the SCCS file.
132 llist
134 Specify a list of releases to which deltas can no longer be made
135 (that is, get -e against one of these locked releases fails).
136 Conforming applications shall use the following syntax to spec‐
137 ify a list. Implementations may accept additional forms as an
138 extension:
139 <list> ::= a | <range-list>
142 <range-list> ::= <range> | <range-list>, <range>
143 <range> ::= <SID>
144 The character a in the list shall be equivalent to specifying
146 all releases for the named SCCS file. The non-terminal <SID> in
147 range shall be the delta number of an existing delta associated
148 with the SCCS file.
149 n
151 Cause delta to create a null delta in each of those releases (if
152 any) being skipped when a delta is made in a new release (for
153 example, in making delta 5.1 after delta 2.7, releases 3 and 4
154 are skipped). These null deltas shall serve as anchor points so
155 that branch deltas may later be created from them. The absence
156 of this flag shall cause skipped releases to be nonexistent in
157 the SCCS file, preventing branch deltas from being created from
158 them in the future. During the initial creation of an SCCS
159 file, the n flag may be ignored; that is, if the -r option is
160 used to set the release number of the initial SID to a value
161 greater than 1, null deltas need not be created for the
162 "skipped" releases.
163 qtext
165 Substitute user-definable text for all occurrences of the %Q%
166 keyword in the SCCS file text retrieved by get.
167 mmod
169 Specify the module name of the SCCS file substituted for all
170 occurrences of the %M% keyword in the SCCS file text retrieved
171 by get. If the m flag is not specified, the value assigned shall
172 be the name of the SCCS file with the leading '.' removed.
173 ttype
175 Specify the type of module in the SCCS file substituted for all
176 occurrences of the %Y% keyword in the SCCS file text retrieved
177 by get.
178 vpgm
180 Cause delta to prompt for modification request (MR) numbers as
181 the reason for creating a delta. The optional value specifies
182 the name of an MR number validation program. (If this flag is
183 set when creating an SCCS file, the application shall ensure
184 that the m option is also used even if its value is null.)
185 -d flag
188 Remove (delete) the specified flag from an SCCS file. Several -d
189 options may be supplied on a single admin command. See the -f
190 option for allowable flag names. (The l list flag gives a list
191 of releases to be unlocked. See the -f option for further
192 description of the l flag and the syntax of a list.)
193 -a login
195 Specify a login name, or numerical group ID, to be added to the
196 list of users who may make deltas (changes) to the SCCS file. A
197 group ID shall be equivalent to specifying all login names com‐
198 mon to that group ID. Several -a options may be used on a single
199 admin command line. As many logins, or numerical group IDs, as
200 desired may be on the list simultaneously. If the list of users
201 is empty, then anyone may add deltas. If login or group ID is
202 preceded by a '!', the users so specified shall be denied per‐
203 mission to make deltas.
204 -e login
206 Specify a login name, or numerical group ID, to be erased from
207 the list of users allowed to make deltas (changes) to the SCCS
208 file. Specifying a group ID is equivalent to specifying all
209 login names common to that group ID. Several -e options may be
210 used on a single admin command line.
211 -y[comment]
213 Insert the comment text into the SCCS file as a comment for the
214 initial delta in a manner identical to that of delta. In the
215 POSIX locale, omission of the -y option shall result in a
216 default comment line being inserted in the form:
217 "date and time created %s %s by %s", <date>, <time>, <login>
220 where <date> is expressed in the format of the date utility's %y / %m /
222 %d conversion specification, <time> in the format of the date utility's
223 %T conversion specification format, and <login> is the login name of
224 the user creating the file.
225 -m mrlist
227 Insert the list of modification request (MR) numbers into the
228 SCCS file as the reason for creating the initial delta in a man‐
229 ner identical to delta. The application shall ensure that the v
230 flag is set and the MR numbers are validated if the v flag has a
231 value (the name of an MR number validation program). A diagnos‐
232 tic message shall be written if the v flag is not set or MR val‐
233 idation fails.
234 -h Check the structure of the SCCS file and compare the newly com‐
236 puted checksum with the checksum that is stored in the SCCS
237 file. If the newly computed checksum does not match the check‐
238 sum in the SCCS file, a diagnostic message shall be written.
239 -z Recompute the SCCS file checksum and store it in the first line
241 of the SCCS file (see the -h option above). Note that use of
242 this option on a truly corrupted file may prevent future detec‐
243 tion of the corruption.
244
247 The following operands shall be supported:
248 file A pathname of an existing SCCS file or a directory. If file is a
250 directory, the admin utility shall behave as though each file in
251 the directory were specified as a named file, except that non-
252 SCCS files (last component of the pathname does not begin with
253 s.) and unreadable files shall be silently ignored.
254 newfile
256 A pathname of an SCCS file to be created.
257 If exactly one file or newfile operand appears, and it is '-', the
260 standard input shall be read; each line of the standard input shall be
261 taken to be the name of an SCCS file to be processed. Non-SCCS files
262 and unreadable files shall be silently ignored.
263
265 The standard input shall be a text file used only if -i is specified
266 without an option-argument or if a file or newfile operand is specified
267 as '-' . If the first character of any standard input line is <SOH> in
268 the POSIX locale, the results are unspecified.
269
271 The existing SCCS files shall be text files of an unspecified format.
272 The application shall ensure that the file named by the -i option's
274 name option-argument shall be a text file; if the first character of
275 any line in this file is <SOH> in the POSIX locale, the results are
276 unspecified. If this file contains more than 99999 lines, the number of
277 lines recorded in the header for this file shall be 99999 for this
278 delta.
279
281 The following environment variables shall affect the execution of
282 admin:
283 LANG Provide a default value for the internationalization variables
285 that are unset or null. (See the Base Definitions volume of
286 IEEE Std 1003.1-2001, Section 8.2, Internationalization Vari‐
287 ables for the precedence of internationalization variables used
288 to determine the values of locale categories.)
289 LC_ALL If set to a non-empty string value, override the values of all
291 the other internationalization variables.
292 LC_CTYPE
294 Determine the locale for the interpretation of sequences of
295 bytes of text data as characters (for example, single-byte as
296 opposed to multi-byte characters in arguments and input files).
297 LC_MESSAGES
299 Determine the locale that should be used to affect the format
300 and contents of diagnostic messages written to standard error
301 and the contents of the default -y comment.
302 NLSPATH
304 Determine the location of message catalogs for the processing of
305 LC_MESSAGES .
306
309 Default.
310
312 Not used.
313
315 The standard error shall be used only for diagnostic messages.
316
318 Any SCCS files created shall be text files of an unspecified format.
319 During processing of a file, a locking z-file, as described in get, may
320 be created and deleted.
321
323 None.
324
326 The following exit values shall be returned:
327 0 Successful completion.
329 >0 An error occurred.
331
334 Default.
335 The following sections are informative.
337
339 It is recommended that directories containing SCCS files be writable by
340 the owner only, and that SCCS files themselves be read-only. The mode
341 of the directories should allow only the owner to modify SCCS files
342 contained in the directories. The mode of the SCCS files prevents any
343 modification at all except by SCCS commands.
344
346 None.
347
349 None.
350
352 None.
353
355 delta, get, prs, what
356
358 Portions of this text are reprinted and reproduced in electronic form
359 from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology
360 -- Portable Operating System Interface (POSIX), The Open Group Base
361 Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of
362 Electrical and Electronics Engineers, Inc and The Open Group. In the
363 event of any discrepancy between this version and the original IEEE and
364 The Open Group Standard, the original IEEE and The Open Group Standard
365 is the referee document. The original Standard can be obtained online
366 at http://www.opengroup.org/unix/online.html .
367IEEE/The Open Group 2003 ADMIN(1P)