logo

oasis-root

Compiled tree of Oasis Linux based on own branch at <https://hacktivis.me/git/oasis/> git clone https://anongit.hacktivis.me/git/oasis-root.git

admin.1p (15702B)


  1. '\" et
  2. .TH ADMIN "1P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual"
  3. .\"
  4. .SH PROLOG
  5. This manual page is part of the POSIX Programmer's Manual.
  6. The Linux implementation of this interface may differ (consult
  7. the corresponding Linux manual page for details of Linux behavior),
  8. or the interface may not be implemented on Linux.
  9. .\"
  10. .SH NAME
  11. admin
  12. \(em create and administer SCCS files (\fBDEVELOPMENT\fP)
  13. .SH SYNOPSIS
  14. .LP
  15. .nf
  16. admin -i\fB[\fIname\fB] [\fR-n\fB] [\fR-a \fIlogin\fB] [\fR-d \fIflag\fB] [\fR-e \fIlogin\fB] [\fR-f \fIflag\fB]
  17. [\fR-m \fImrlist\fB] [\fR-r \fIrel\fB] [\fR-t\fB[\fIname\fB] [\fR-y\fB[\fIcomment\fB]] \fInewfile\fR
  18. .P
  19. admin -n\fB [\fR-a \fIlogin\fB] [\fR-d \fIflag\fB] [\fR-e \fIlogin\fB] [\fR-f \fIflag\fB] [\fR-m \fImrlist\fB]
  20. [\fR-t\fB[\fIname\fB]] [\fR-y\fB[\fIcomment\fB]] \fInewfile\fR...
  21. .P
  22. admin \fB[\fR-a \fIlogin\fB] [\fR-d \fIflag\fB] [\fR-m \fImrlist\fB] [\fR-r \fIrel\fB] [\fR-t\fB[\fIname\fB]]\fR \fIfile\fR...
  23. .P
  24. admin -h \fIfile\fR...
  25. .P
  26. admin -z \fIfile\fR...
  27. .fi
  28. .SH DESCRIPTION
  29. The
  30. .IR admin
  31. utility shall create new SCCS files or change parameters of existing
  32. ones. If a named file does not exist, it shall be created, and its
  33. parameters shall be initialized according to the specified options.
  34. Parameters not initialized by an option shall be assigned a default
  35. value. If a named file does exist, parameters corresponding to
  36. specified options shall be changed, and other parameters shall be left
  37. as is.
  38. .P
  39. All SCCS filenames supplied by the application shall be of the form
  40. s.\fIfilename\fP. New SCCS files shall be given read-only permission
  41. mode. Write permission in the parent directory is required to create a
  42. file. All writing done by
  43. .IR admin
  44. shall be to a temporary
  45. .IR x-file ,
  46. named x.\fIfilename\fP (see
  47. .IR "\fIget\fR\^")
  48. created with read-only mode if
  49. .IR admin
  50. is creating a new SCCS file, or created with the same mode as that of
  51. the SCCS file if the file already exists. After successful execution of
  52. .IR admin ,
  53. the SCCS file shall be removed (if it exists), and the
  54. .IR x-file
  55. shall be renamed with the name of the SCCS file. This ensures that
  56. changes are made to the SCCS file only if no errors occur.
  57. .P
  58. The
  59. .IR admin
  60. utility shall also use a transient lock file (named z.\fIfilename\fP),
  61. which is used to prevent simultaneous updates to the SCCS file; see
  62. .IR "\fIget\fR\^".
  63. .SH OPTIONS
  64. The
  65. .IR admin
  66. utility shall conform to the Base Definitions volume of POSIX.1\(hy2017,
  67. .IR "Section 12.2" ", " "Utility Syntax Guidelines",
  68. except that the
  69. .BR \-i ,
  70. .BR \-t ,
  71. and
  72. .BR \-y
  73. options have optional option-arguments. These optional option-arguments
  74. shall not be presented as separate arguments. The following options are
  75. supported:
  76. .IP "\fB\-n\fP" 10
  77. Create a new SCCS file. When
  78. .BR \-n
  79. is used without
  80. .BR \-i ,
  81. the SCCS file shall be created with control information but without any
  82. file data.
  83. .IP "\fB\-i[\fIname\fB]\fR" 10
  84. Specify the
  85. .IR name
  86. of a file from which the text for a new SCCS file shall be taken. The
  87. text constitutes the first delta of the file (see the
  88. .BR \-r
  89. option for the delta numbering scheme). If the
  90. .BR \-i
  91. option is used, but the
  92. .IR name
  93. option-argument is omitted, the text shall be obtained by reading the
  94. standard input. If this option is omitted, the SCCS file shall be
  95. created with control information but without any file data. The
  96. .BR \-i
  97. option implies the
  98. .BR \-n
  99. option.
  100. .IP "\fB\-r\ \fISID\fR" 10
  101. Specify the SID of the initial delta to be inserted. This SID shall be
  102. a trunk SID; that is, the branch and sequence numbers shall be zero or
  103. missing. The level number is optional, and defaults to 1.
  104. .IP "\fB\-t[\fIname\fB]\fR" 10
  105. Specify the
  106. .IR name
  107. of a file from which descriptive text for the SCCS file shall be taken.
  108. In the case of existing SCCS files (neither
  109. .BR \-i
  110. nor
  111. .BR \-n
  112. is specified):
  113. .RS 10
  114. .IP " *" 4
  115. A
  116. .BR \-t
  117. option without a
  118. .IR name
  119. option-argument shall cause the removal of descriptive text (if any)
  120. currently in the SCCS file.
  121. .IP " *" 4
  122. A
  123. .BR \-t
  124. option with a
  125. .IR name
  126. option-argument shall cause the text (if any) in the named file to
  127. replace the descriptive text (if any) currently in the SCCS file.
  128. .RE
  129. .IP "\fB\-f\ \fIflag\fR" 10
  130. Specify a
  131. .IR flag ,
  132. and, possibly, a value for the
  133. .IR flag ,
  134. to be placed in the SCCS file. Several
  135. .BR \-f
  136. options may be supplied on a single
  137. .IR admin
  138. command line. Implementations shall recognize the following flags
  139. and associated values:
  140. .RS 10
  141. .IP "\fBb\fP" 8
  142. Allow use of the
  143. .BR \-b
  144. option on a
  145. .IR get
  146. command to create branch deltas.
  147. .IP "\fBc\fIceil\fR" 8
  148. Specify the highest release (that is, ceiling), a number less than or
  149. equal to 9\|999, which may be retrieved by a
  150. .IR get
  151. command for editing. The default value for an unspecified
  152. .BR c
  153. flag shall be 9\|999.
  154. .IP "\fBf\fIfloor\fR" 8
  155. Specify the lowest release (that is, floor), a number greater than 0
  156. but less than 9\|999, which may be retrieved by a
  157. .IR get
  158. command for editing. The default value for an unspecified
  159. .BR f
  160. flag shall be 1.
  161. .IP "\fBd\fISID\fR" 8
  162. Specify the default delta number (SID) to be used by a
  163. .IR get
  164. command.
  165. .IP "\fBi\fIstr\fR" 8
  166. Treat the ``No ID keywords'' message issued by
  167. .IR get
  168. or
  169. .IR delta
  170. as a fatal error. In the absence of this flag, the message is only a
  171. warning. The message is issued if no SCCS identification keywords (see
  172. .IR "\fIget\fR\^")
  173. are found in the text retrieved or stored in the SCCS file. If a value
  174. is supplied, the application shall ensure that the keywords exactly
  175. match the given string; however, the string shall contain a keyword,
  176. and no embedded
  177. <newline>
  178. characters.
  179. .IP "\fBj\fP" 8
  180. Allow concurrent
  181. .IR get
  182. commands for editing on the same SID of an SCCS file. This allows
  183. multiple concurrent updates to the same version of the SCCS file.
  184. .IP "\fBl\fIlist\fR" 8
  185. Specify a
  186. .IR list
  187. of releases to which deltas can no longer be made (that is,
  188. .IR get
  189. .BR \-e
  190. against one of these locked releases fails). Conforming applications
  191. shall use the following syntax to specify a
  192. .IR list .
  193. Implementations may accept additional forms as an extension:
  194. .RS 8
  195. .sp
  196. .RS 4
  197. .nf
  198. <list> ::= a | <range-list>
  199. <range-list> ::= <range> | <range-list>, <range>
  200. <range> ::= <SID>
  201. .fi
  202. .P
  203. .RE
  204. .P
  205. The character
  206. .IR a
  207. in the
  208. .IR list
  209. shall be equivalent to specifying all releases for the named SCCS file.
  210. The non-terminal <\fISID\fP> in range shall be the delta number of an
  211. existing delta associated with the SCCS file.
  212. .RE
  213. .IP "\fBn\fP" 8
  214. Cause
  215. .IR delta
  216. to create a null delta in each of those releases (if any) being skipped
  217. when a delta is made in a new release (for example, in making delta 5.1
  218. after delta 2.7, releases 3 and 4 are skipped). These null deltas shall
  219. serve as anchor points so that branch deltas may later be created from
  220. them. The absence of this flag shall cause skipped releases to be
  221. nonexistent in the SCCS file, preventing branch deltas from being
  222. created from them in the future. During the initial creation of an SCCS
  223. file, the
  224. .BR n
  225. flag may be ignored; that is, if the
  226. .BR \-r
  227. option is used to set the release number of the initial SID to a value
  228. greater than 1, null deltas need not be created for the ``skipped''
  229. releases.
  230. .IP "\fBq\fItext\fR" 8
  231. Substitute user-definable
  232. .IR text
  233. for all occurrences of the %\fBQ\fP% keyword in the SCCS file text
  234. retrieved by
  235. .IR get .
  236. .IP "\fBm\fImod\fR" 8
  237. Specify the module name of the SCCS file substituted for all
  238. occurrences of the %\fBM\fP% keyword in the SCCS file text retrieved by
  239. .IR get .
  240. If the
  241. .BR m
  242. flag is not specified, the value assigned shall be the name of the SCCS
  243. file with the leading
  244. .BR '.'
  245. removed.
  246. .IP "\fBt\fItype\fR" 8
  247. Specify the
  248. .IR type
  249. of module in the SCCS file substituted for all occurrences of the
  250. %\fBY\fP% keyword in the SCCS file text retrieved by
  251. .IR get .
  252. .IP "\fBv\fIpgm\fR" 8
  253. Cause
  254. .IR delta
  255. to prompt for modification request (MR) numbers as the reason for
  256. creating a delta. The optional value specifies the name of an MR
  257. number validation program. (If this flag is set when creating an SCCS
  258. file, the application shall ensure that the
  259. .BR m
  260. option is also used even if its value is null.)
  261. .RE
  262. .IP "\fB\-d\ \fIflag\fR" 10
  263. Remove (delete) the specified
  264. .IR flag
  265. from an SCCS file. Several
  266. .BR \-d
  267. options may be supplied on a single
  268. .IR admin
  269. command. See the
  270. .BR \-f
  271. option for allowable
  272. .IR flag
  273. names. (The
  274. .BR l \c
  275. .IR list
  276. flag gives a
  277. .IR list
  278. of releases to be unlocked. See the
  279. .BR \-f
  280. option for further description of the
  281. .BR l
  282. flag and the syntax of a
  283. .IR list .)
  284. .IP "\fB\-a\ \fIlogin\fR" 10
  285. Specify a
  286. .IR login
  287. name, or numerical group ID, to be added to the list of users who may
  288. make deltas (changes) to the SCCS file. A group ID shall be equivalent
  289. to specifying all
  290. .IR login
  291. names common to that group ID. Several
  292. .BR \-a
  293. options may be used on a single
  294. .IR admin
  295. command line. As many
  296. .IR login s,
  297. or numerical group IDs, as desired may be on the list simultaneously.
  298. If the list of users is empty, then anyone may add deltas. If
  299. .IR login
  300. or group ID is preceded by a
  301. .BR '!' ,
  302. the users so specified shall be denied permission to make deltas.
  303. .IP "\fB\-e\ \fIlogin\fR" 10
  304. Specify a
  305. .IR login
  306. name, or numerical group ID, to be erased from the list of users
  307. allowed to make deltas (changes) to the SCCS file. Specifying a group
  308. ID is equivalent to specifying all
  309. .IR login
  310. names common to that group ID. Several
  311. .BR \-e
  312. options may be used on a single
  313. .IR admin
  314. command line.
  315. .IP "\fB\-y[\fIcomment\fB]\fR" 10
  316. Insert the
  317. .IR comment
  318. text into the SCCS file as a comment for the initial delta in a manner
  319. identical to that of
  320. .IR delta .
  321. In the POSIX locale, omission of the
  322. .BR \-y
  323. option shall result in a default comment line being inserted in
  324. the form:
  325. .RS 10
  326. .sp
  327. .RS 4
  328. .nf
  329. "date and time created %s %s by %s", <\fIdate\fR>, <\fItime\fR>, <\fIlogin\fR>
  330. .fi
  331. .P
  332. .RE
  333. .P
  334. where <\fIdate\fP> is expressed in the format of the
  335. .IR date
  336. utility's
  337. .BR %y /\c
  338. .BR %m /\c
  339. .BR %d
  340. conversion specification, <\fItime\fP> in the format of the
  341. .IR date
  342. utility's
  343. .BR %T
  344. conversion specification format, and <\fIlogin\fP> is the login name of
  345. the user creating the file.
  346. .RE
  347. .IP "\fB\-m\ \fImrlist\fR" 10
  348. Insert the list of modification request (MR) numbers into the SCCS
  349. file as the reason for creating the initial delta in a manner identical to
  350. .IR delta .
  351. The application shall ensure that the
  352. .BR v
  353. flag is set and the MR numbers are validated if the
  354. .BR v
  355. flag has a value (the name of an MR number validation program).
  356. A diagnostic message shall be written if the
  357. .BR v
  358. flag is not set or MR validation fails.
  359. .IP "\fB\-h\fP" 10
  360. Check the structure of the SCCS file and compare the newly computed
  361. checksum with the checksum that is stored in the SCCS file. If the
  362. newly computed checksum does not match the checksum in the SCCS file, a
  363. diagnostic message shall be written.
  364. .IP "\fB\-z\fR" 10
  365. Recompute the SCCS file checksum and store it in the first line of the
  366. SCCS file (see the
  367. .BR \-h
  368. option above). Note that use of this option on a truly corrupted
  369. file may prevent future detection of the corruption.
  370. .SH OPERANDS
  371. The following operands shall be supported:
  372. .IP "\fIfile\fR" 10
  373. A pathname of an existing SCCS file or a directory. If
  374. .IR file
  375. is a directory, the
  376. .IR admin
  377. utility shall behave as though each file in the directory were
  378. specified as a named file, except that non-SCCS files (last component
  379. of the pathname does not begin with
  380. .BR s. )
  381. and unreadable files shall be silently ignored.
  382. .IP "\fInewfile\fR" 10
  383. A pathname of an SCCS file to be created.
  384. .P
  385. If exactly one
  386. .IR file
  387. or
  388. .IR newfile
  389. operand appears, and it is
  390. .BR '\-' ,
  391. the standard input shall be read; each line of the standard input shall
  392. be taken to be the name of an SCCS file to be processed. Non-SCCS files
  393. and unreadable files shall be silently ignored.
  394. .SH STDIN
  395. The standard input shall be a text file used only if
  396. .BR \-i
  397. is specified without an option-argument or if a
  398. .IR file
  399. or
  400. .IR newfile
  401. operand is specified as
  402. .BR '\-' .
  403. If the first character of any standard input line is
  404. <SOH>
  405. in the POSIX locale, the results are unspecified.
  406. .SH "INPUT FILES"
  407. The existing SCCS files shall be text files of an unspecified format.
  408. .P
  409. The application shall ensure that the file named by the
  410. .BR \-i
  411. option's
  412. .IR name
  413. option-argument shall be a text file; if the first character of any
  414. line in this file is
  415. <SOH>
  416. in the POSIX locale, the results are unspecified. If this file contains
  417. more than 99\|999 lines, the number of lines recorded in the header for
  418. this file shall be 99\|999 for this delta.
  419. .SH "ENVIRONMENT VARIABLES"
  420. The following environment variables shall affect the execution of
  421. .IR admin :
  422. .IP "\fILANG\fP" 10
  423. Provide a default value for the internationalization variables that are
  424. unset or null. (See the Base Definitions volume of POSIX.1\(hy2017,
  425. .IR "Section 8.2" ", " "Internationalization Variables"
  426. for the precedence of internationalization variables used to determine
  427. the values of locale categories.)
  428. .IP "\fILC_ALL\fP" 10
  429. If set to a non-empty string value, override the values of all the
  430. other internationalization variables.
  431. .IP "\fILC_CTYPE\fP" 10
  432. Determine the locale for the interpretation of sequences of bytes of
  433. text data as characters (for example, single-byte as opposed to
  434. multi-byte characters in arguments and input files).
  435. .IP "\fILC_MESSAGES\fP" 10
  436. .br
  437. Determine the locale that should be used to affect the format and
  438. contents of diagnostic messages written to standard error and the
  439. contents of the default
  440. .BR \-y
  441. comment.
  442. .IP "\fINLSPATH\fP" 10
  443. Determine the location of message catalogs for the processing of
  444. .IR LC_MESSAGES .
  445. .SH "ASYNCHRONOUS EVENTS"
  446. Default.
  447. .SH STDOUT
  448. Not used.
  449. .SH STDERR
  450. The standard error shall be used only for diagnostic messages.
  451. .SH "OUTPUT FILES"
  452. Any SCCS files created shall be text files of an unspecified format.
  453. During processing of a
  454. .IR file ,
  455. a locking
  456. .IR z-file ,
  457. as described in
  458. .IR "\fIget\fR\^",
  459. may be created and deleted.
  460. .SH "EXTENDED DESCRIPTION"
  461. None.
  462. .SH "EXIT STATUS"
  463. The following exit values shall be returned:
  464. .IP "\00" 6
  465. Successful completion.
  466. .IP >0 6
  467. An error occurred.
  468. .SH "CONSEQUENCES OF ERRORS"
  469. Default.
  470. .LP
  471. .IR "The following sections are informative."
  472. .SH "APPLICATION USAGE"
  473. It is recommended that directories containing SCCS files be writable by
  474. the owner only, and that SCCS files themselves be read-only. The mode
  475. of the directories should allow only the owner to modify SCCS files
  476. contained in the directories. The mode of the SCCS files prevents any
  477. modification at all except by SCCS commands.
  478. .SH EXAMPLES
  479. None.
  480. .SH RATIONALE
  481. None.
  482. .SH "FUTURE DIRECTIONS"
  483. None.
  484. .SH "SEE ALSO"
  485. .IR "\fIdelta\fR\^",
  486. .IR "\fIget\fR\^",
  487. .IR "\fIprs\fR\^",
  488. .IR "\fIwhat\fR\^"
  489. .P
  490. The Base Definitions volume of POSIX.1\(hy2017,
  491. .IR "Chapter 8" ", " "Environment Variables",
  492. .IR "Section 12.2" ", " "Utility Syntax Guidelines"
  493. .\"
  494. .SH COPYRIGHT
  495. Portions of this text are reprinted and reproduced in electronic form
  496. from IEEE Std 1003.1-2017, Standard for Information Technology
  497. -- Portable Operating System Interface (POSIX), The Open Group Base
  498. Specifications Issue 7, 2018 Edition,
  499. Copyright (C) 2018 by the Institute of
  500. Electrical and Electronics Engineers, Inc and The Open Group.
  501. In the event of any discrepancy between this version and the original IEEE and
  502. The Open Group Standard, the original IEEE and The Open Group Standard
  503. is the referee document. The original Standard can be obtained online at
  504. http://www.opengroup.org/unix/online.html .
  505. .PP
  506. Any typographical or formatting errors that appear
  507. in this page are most likely
  508. to have been introduced during the conversion of the source files to
  509. man page format. To report such errors, see
  510. https://www.kernel.org/doc/man-pages/reporting_bugs.html .