diff options
Diffstat (limited to 'upstream/archlinux/man1p/get.1p')
| -rw-r--r-- | upstream/archlinux/man1p/get.1p | 850 |
1 files changed, 850 insertions, 0 deletions
diff --git a/upstream/archlinux/man1p/get.1p b/upstream/archlinux/man1p/get.1p new file mode 100644 index 00000000..937d7424 --- /dev/null +++ b/upstream/archlinux/man1p/get.1p @@ -0,0 +1,850 @@ +'\" et +.TH GET "1P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +get +\(em get a version of an SCCS file (\fBDEVELOPMENT\fP) +.SH SYNOPSIS +.LP +.nf +get \fB[\fR-begkmnlLpst\fB] [\fR-c \fIcutoff\fB] [\fR-i \fIlist\fB] [\fR-r \fISID\fB] [\fR-x \fIlist\fB] \fIfile\fR... +.fi +.SH DESCRIPTION +The +.IR get +utility shall generate a text file from each named SCCS +.IR file +according to the specifications given by its options. +.P +The generated text shall normally be written into a file called the +.BR g-file +whose name is derived from the SCCS filename by simply removing the +leading +.BR \(dqs.\(dq . +.SH OPTIONS +The +.IR get +utility shall conform to the Base Definitions volume of POSIX.1\(hy2017, +.IR "Section 12.2" ", " "Utility Syntax Guidelines". +.P +The following options shall be supported: +.IP "\fB\-r\ \fISID\fR" 10 +Indicate the SCCS Identification String (SID) of the version (delta) +of an SCCS file to be retrieved. The table shows, for the most useful +cases, what version of an SCCS file is retrieved (as well as the SID of +the version to be eventually created by +.IR delta +if the +.BR \-e +option is also used), as a function of the SID specified. +.IP "\fB\-c\ \fIcutoff\fR" 10 +Indicate the +.IR cutoff +date-time, in the form: +.RS 10 +.sp +.RS 4 +.nf + +\fIYY\fB[\fIMM\fB[\fIDD\fB[\fIHH\fB[\fIMM\fB[\fISS\fB]]]]]\fR +.fi +.P +.RE +.P +For the +.IR YY +component, values in the range [69,99] shall refer to years 1969 to +1999 inclusive, and values in the range [00,68] shall refer to years +2000 to 2068 inclusive. +.TP 10 +.BR Note: +It is expected that in a future version of this standard the default +century inferred from a 2-digit year will change. (This would apply +to all commands accepting a 2-digit year as input.) +.P +.P +No changes (deltas) to the SCCS file that were created after the +specified +.IR cutoff +date-time shall be included in the generated text file. Units omitted +from the date-time default to their maximum possible values; for +example, +.BR \-c +7502 is equivalent to +.BR \-c +750228235959. +.P +Any number of non-numeric characters may separate the various 2-digit +pieces of the +.IR cutoff +date-time. This feature allows the user to specify a +.IR cutoff +date in the form: +.BR \-c +"77/2/2\09:22:25". +.RE +.IP "\fB\-e\fR" 10 +Indicate that the +.IR get +is for the purpose of editing or making a change (delta) to the SCCS +file via a subsequent use of +.IR delta . +The +.BR \-e +option used in a +.IR get +for a particular version (SID) of the SCCS file shall prevent further +.IR get +commands from editing on the same SID until +.IR delta +is executed or the +.BR j +(joint edit) flag is set in the SCCS file. Concurrent use of +.IR get +.BR \-e +for different SIDs is always allowed. +.RS 10 +.P +If the +.BR g-file +generated by +.IR get +with a +.BR \-e +option is accidentally ruined in the process of editing, it may be +regenerated by re-executing the +.IR get +command with the +.BR \-k +option in place of the +.BR \-e +option. +.P +SCCS file protection specified via the ceiling, floor, and authorized +user list stored in the SCCS file shall be enforced when the +.BR \-e +option is used. +.RE +.IP "\fB\-b\fR" 10 +Use with the +.BR \-e +option to indicate that the new delta should have an SID in a new +branch as shown in the table below. This option shall be ignored if the +.BR b +flag is not present in the file or if the retrieved delta is not a leaf +delta. (A leaf delta is one that has no successors on the SCCS file tree.) +.RS 10 +.TP 10 +.BR Note: +A branch delta may always be created from a non-leaf delta. +.P +.RE +.IP "\fB\-i\ \fIlist\fR" 10 +Indicate a +.IR list +of deltas to be included (forced to be applied) in the creation of the +generated file. The +.IR list +has the following syntax: +.RS 10 +.sp +.RS 4 +.nf + +<list> ::= <range> | <list> , <range> +<range> ::= SID | SID - SID +.fi +.P +.RE +.P +SID, the SCCS Identification of a delta, may be in any form shown in +the ``SID Specified'' column of the table in the EXTENDED DESCRIPTION +section, except that the result of supplying a partial SID is +unspecified. A diagnostic message shall be written if the first SID in +the range is not an ancestor of the second SID in the range. +.RE +.IP "\fB\-x\ \fIlist\fR" 10 +Indicate a +.IR list +of deltas to be excluded (forced not to be applied) in the creation of +the generated file. See the +.BR \-i +option for the +.IR list +format. +.IP "\fB\-k\fR" 10 +Suppress replacement of identification keywords (see below) in the +retrieved text by their value. The +.BR \-k +option shall be implied by the +.BR \-e +option. +.IP "\fB\-l\fR" 10 +Write a delta summary into an +.BR l-file . +.IP "\fB\-L\fR" 10 +Write a delta summary to standard output. All informative output that +normally is written to standard output shall be written to standard +error instead, unless the +.BR \-s +option is used, in which case it shall be suppressed. +.IP "\fB\-p\fR" 10 +Write the text retrieved from the SCCS file to the standard output. No +.BR g-file +shall be created. All informative output that normally goes to the +standard output shall go to standard error instead, unless the +.BR \-s +option is used, in which case it shall disappear. +.IP "\fB\-s\fR" 10 +Suppress all informative output normally written to standard output. +However, fatal error messages (which shall always be written to the +standard error) shall remain unaffected. +.IP "\fB\-m\fR" 10 +Precede each text line retrieved from the SCCS file by the SID of the +delta that inserted the text line in the SCCS file. The format shall be: +.RS 10 +.sp +.RS 4 +.nf + +"%s\et%s", <\fISID\fR>, <\fItext line\fR> +.fi +.P +.RE +.RE +.IP "\fB\-n\fR" 10 +Precede each generated text line with the %\fBM\fP% identification +keyword value (see below). The format shall be: +.RS 10 +.sp +.RS 4 +.nf + +"%s\et%s", <\fI%M% value\fR>, <\fItext line\fR> +.fi +.P +.RE +.P +When both the +.BR \-m +and +.BR \-n +options are used, the <\fItext\ line\fP> shall be replaced by the +.BR \-m +option-generated format. +.RE +.IP "\fB\-g\fR" 10 +Suppress the actual retrieval of text from the SCCS file. It is +primarily used to generate an +.BR l-file , +or to verify the existence of a particular SID. +.IP "\fB\-t\fR" 10 +Use to access the most recently created (top) delta in a given release +(for example, +.BR "\-r 1" ), +or release and level (for example, +.BR "\-r 1.2" ). +.br +.SH OPERANDS +The following operands shall be supported: +.IP "\fIfile\fR" 10 +A pathname of an existing SCCS file or a directory. If +.IR file +is a directory, the +.IR get +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 +.BR s. ) +and unreadable files shall be silently ignored. +.RS 10 +.P +If exactly one +.IR file +operand appears, and it is +.BR '\-' , +the standard input shall be read; each line of the standard input is +taken to be the name of an SCCS file to be processed. Non-SCCS files +and unreadable files shall be silently ignored. +.RE +.SH STDIN +The standard input shall be a text file used only if the +.IR file +operand is specified as +.BR '\-' . +Each line of the text file shall be interpreted as an SCCS pathname. +.SH "INPUT FILES" +The SCCS files shall be files of an unspecified format. +.SH "ENVIRONMENT VARIABLES" +The following environment variables shall affect the execution of +.IR get : +.IP "\fILANG\fP" 10 +Provide a default value for the internationalization variables that are +unset or null. (See the Base Definitions volume of POSIX.1\(hy2017, +.IR "Section 8.2" ", " "Internationalization Variables" +for the precedence of internationalization variables used to determine +the values of locale categories.) +.IP "\fILC_ALL\fP" 10 +If set to a non-empty string value, override the values of all the +other internationalization variables. +.IP "\fILC_CTYPE\fP" 10 +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). +.IP "\fILC_MESSAGES\fP" 10 +.br +Determine the locale that should be used to affect the format and +contents of diagnostic messages written to standard error, and +informative messages written to standard output (or standard error, if +the +.BR \-p +option is used). +.IP "\fINLSPATH\fP" 10 +Determine the location of message catalogs for the processing of +.IR LC_MESSAGES . +.IP "\fITZ\fR" 10 +Determine the timezone in which the times and dates written in the +SCCS file are evaluated. If the +.IR TZ +variable is unset or NULL, an unspecified system default timezone is +used. +.SH "ASYNCHRONOUS EVENTS" +Default. +.SH STDOUT +For each file processed, +.IR get +shall write to standard output the SID being accessed and the number of +lines retrieved from the SCCS file, in the following format: +.sp +.RS 4 +.nf + +"%s\en%d lines\en", <\fISID\fR>, <\fInumber of lines\fR> +.fi +.P +.RE +.P +If the +.BR \-e +option is used, the SID of the delta to be made shall appear after the +SID accessed and before the number of lines generated, in the POSIX +locale: +.sp +.RS 4 +.nf + +"%s\ennew delta %s\en%d lines\en", <\fISID accessed\fR>, + <\fISID to be made\fR>, <\fInumber of lines\fR> +.fi +.P +.RE +.P +If there is more than one named file or if a directory or standard +input is named, each pathname shall be written before each of the lines +shown in one of the preceding formats: +.sp +.RS 4 +.nf + +"\en%s:\en", <\fIpathname\fR> +.fi +.P +.RE +.P +If the +.BR \-L +option is used, a delta summary shall be written following the format +specified below for +.BR l-files . +.P +If the +.BR \-i +option is used, included deltas shall be listed following the notation, +in the POSIX locale: +.sp +.RS 4 +.nf + +"Included:\en" +.fi +.P +.RE +.P +If the +.BR \-x +option is used, excluded deltas shall be listed following the notation, +in the POSIX locale: +.sp +.RS 4 +.nf + +"Excluded:\en" +.fi +.P +.RE +.P +If the +.BR \-p +or +.BR \-L +options are specified, the standard output shall consist of the text +retrieved from the SCCS file. +.SH STDERR +The standard error shall be used only for diagnostic messages, except +if the +.BR \-p +or +.BR \-L +options are specified, it shall include all informative messages +normally sent to standard output. +.SH "OUTPUT FILES" +Several auxiliary files may be created by +.IR get . +These files are known generically as the +.BR g-file , +.BR l-file , +.BR p-file , +and +.BR z-file . +The letter before the +<hyphen-minus> +is called the +.IR tag . +An auxiliary filename shall be formed from the SCCS filename: the +application shall ensure that the last component of all SCCS filenames +is of the form +.BR s. \c +.IR module-name ; +the auxiliary files shall be named by replacing the leading +.BR s +with the tag. The +.BR g-file +shall be an exception to this scheme: the +.BR g-file +is named by removing the +.BR s. +prefix. For example, for +.BR s.xyz.c , +the auxiliary filenames would be +.BR xyz.c , +.BR l.xyz.c , +.BR p.xyz.c , +and +.BR z.xyz.c , +respectively. +.P +The +.BR g-file , +which contains the generated text, shall be created in the current +directory (unless the +.BR \-p +option is used). A +.BR g-file +shall be created in all cases, whether or not any lines of text were +generated by the +.IR get . +It shall be owned by the real user. If the +.BR \-k +option is used or implied, the +.BR g-file +shall be writable by the owner only (read-only for everyone else); +otherwise, it shall be read-only. Only the real user need have write +permission in the current directory. +.P +The +.BR l-file +shall contain a table showing which deltas were applied in generating +the retrieved text. The +.BR l-file +shall be created in the current directory if the +.BR \-l +option is used; it shall be read-only and it is owned by the real user. +Only the real user need have write permission in the current +directory. +.P +Lines in the +.BR l-file +shall have the following format: +.sp +.RS 4 +.nf + +"%c%c%c %s\et%s %s\en", <\fIcode1\fR>, <\fIcode2\fR>, <\fIcode3\fR>, + <\fISID\fR>, <\fIdate-time\fR>, <\fIlogin\fR> +.fi +.P +.RE +.P +where the entries are: +.IP "<\fIcode1\fP>" 10 +A +<space> +if the delta was applied; +.BR '*' +otherwise. +.IP "<\fIcode2\fP>" 10 +A +<space> +if the delta was applied or was not applied and ignored; +.BR '*' +if the delta was not applied and was not ignored. +.IP "<\fIcode3\fP>" 10 +A character indicating a special reason why the delta was or was not +applied: +.RS 10 +.IP "\fBI\fP" 6 +Included. +.IP "\fBX\fP" 6 +Excluded. +.IP "\fBC\fP" 6 +Cut off (by a +.BR \-c +option). +.RE +.IP "<\fIdate-time\fP>" 10 +Date and time (using the format of the +.IR date +utility's +.BR %y /\c +.BR %m /\c +.BR %d +.BR %T +conversion specification format) of creation. +.IP "<\fIlogin\fP>" 10 +Login name of person who created +.IR delta . +.P +The comments and MR data shall follow on subsequent lines, indented one +<tab>. +A blank line shall terminate each entry. +.P +The +.BR p-file +shall be used to pass information resulting from a +.IR get +with a +.BR \-e +option along to +.IR delta . +Its contents shall also be used to prevent a subsequent execution of +.IR get +with a +.BR \-e +option for the same SID until +.IR delta +is executed or the joint edit flag, +.BR j , +is set in the SCCS file. The +.BR p-file +shall be created in the directory containing the SCCS file and the +application shall ensure that the effective user has write permission +in that directory. It shall be writable by owner only, and owned +by the effective user. Each line in the +.BR p-file +shall have the following format: +.sp +.RS 4 +.nf + +"%s %s %s %s%s%s\en", <\fIg-file SID\fR>, + <\fISID of new delta\fR>, <\fIlogin-name of real user\fR>, + <\fIdate-time\fR>, <\fIi-value\fR>, <\fIx-value\fR> +.fi +.P +.RE +.P +where <\fIi\(hyvalue\fP> uses the format +.BR \(dq\^\(dq +if no +.BR \-i +option was specified, and shall use the format: +.sp +.RS 4 +.nf + +" -i%s", <-i option \fIoption-argument\fR> +.fi +.P +.RE +.P +if a +.BR \-i +option was specified and <\fIx\(hyvalue\fP> uses the format +.BR \(dq\^\(dq +if no +.BR \-x +option was specified, and shall use the format: +.sp +.RS 4 +.nf + +" -x%s", <-x option \fIoption-argument\fR> +.fi +.P +.RE +.P +if a +.BR \-x +option was specified. There can be an arbitrary number of lines in the +.BR p-file +at any time; no two lines shall have the same new delta SID. +.P +The +.BR z-file +shall serve as a lock-out mechanism against simultaneous updates. Its +contents shall be the binary process ID of the command (that is, +.IR get ) +that created it. The +.BR z-file +shall be created in the directory containing the SCCS file for the +duration of +.IR get . +The same protection restrictions as those for the +.BR p-file +shall apply for the +.BR z-file . +The +.BR z-file +shall be created read-only. +.br +.SH "EXTENDED DESCRIPTION" +.TS +center tab(@) box; +cB s s s s +cB cB cB cB cB +cB cB cB cB cB +l c lw(4.5c) l l. +Determination of SCCS Identification String += +SID*@\-b Keyletter@Other@SID@SID of Delta +Specified@Used\(dg@Conditions@Retrieved@to be Created +.sp 1.5p += +none\(dd@no@R defaults to mR@mR.mL@mR.(mL+1) +_ +none\(dd@yes@R defaults to mR@mR.mL@mR.mL.(mB+1).1 +.sp 1.5p += +R@no@R > mR@mR.mL@R.1*** +_ +R@no@R = mR@mR.mL@mR.(mL+1) +_ +R@yes@R > mR@mR.mL@mR.mL.(mB+1).1 +_ +R@yes@R = mR@mR.mL@mR.mL.(mB+1).1 +_ +R@\-@T{ +R < mR and +R does not exist +T}@hR.mL**@hR.mL.(mB+1).1 +_ +R@\-@T{ +Trunk successor in release > R +and R exists +T}@R.mL@R.mL.(mB+1).1 +.sp 1.5p += +R.L@no@No trunk successor@R.L@R.(L+1) +_ +R.L@yes@No trunk successor@R.L@R.L.(mB+1).1 +_ +R.L@\-@T{ +Trunk successor +in release \(>= R +T}@R.L@R.L.(mB+1).1 +.sp 1.5p += +R.L.B@no@No branch successor@R.L.B.mS@R.L.B.(mS+1) +_ +R.L.B@yes@No branch successor@R.L.B.mS@R.L.(mB+1).1 +.sp 1.5p += +R.L.B.S@no@No branch successor@R.L.B.S@R.L.B.(S+1) +_ +R.L.B.S@yes@No branch successor@R.L.B.S@R.L.(mB+1).1 +_ +R.L.B.S@\-@Branch successor@R.L.B.S@R.L.(mB+1).1 +.TE +.IP * 8 +R, L, B, and S are the release, level, branch, and sequence components +of the SID, respectively; m means maximum. Thus, for example, R.mL +means ``the maximum level number within release R''; R.L.(mB+1).1 means +``the first sequence number on the new branch (that is, maximum branch +number plus one) of level L within release R''. Note that if the SID +specified is of the form R.L, R.L.B, or R.L.B.S, each of the specified +components shall exist. +.IP ** 8 +hR is the highest existing release that is lower than the specified, +nonexistent, release R. +.IP *** 8 +This is used to force creation of the first delta in a new release. +.IP "\(dg" 8 +The +.BR \-b +option is effective only if the +.BR b +flag is present in the file. An entry of +.BR '\-' +means ``irrelevant''. +.IP "\(dd" 8 +This case applies if the +.BR d +(default SID) flag is not present in the file. If the +.BR d +flag is present in the file, then the SID obtained from the +.BR d +flag is interpreted as if it had been specified on the command line. +Thus, one of the other cases in this table applies. +.SS "System Date and Time" +.P +When a +.BR g-file +is generated, the creation time of deltas in the SCCS file may be taken +into account. If any of these times are apparently in the future, the +behavior is unspecified. +.SS "Identification Keywords" +.P +Identifying information shall be inserted into the text retrieved from +the SCCS file by replacing identification keywords with their value +wherever they occur. The following keywords may be used in the text +stored in an SCCS file: +.IP "%\fBM\fP%" 10 +Module name: either the value of the +.BR m +flag in the file, or if absent, the name of the SCCS file with the +leading +.BR s. +removed. +.IP "%\fBI\fP%" 10 +SCCS identification (SID) (%\fBR\fR%.%\fBL\fR% or +%\fBR\fR%.%\fBL\fR%.%\fBB\fR%.%\fBS\fR%) of the retrieved text. +.IP "%\fBR\fP%" 10 +Release. +.IP "%\fBL\fP%" 10 +Level. +.IP "%\fBB\fP%" 10 +Branch. +.IP "%\fBS\fP%" 10 +Sequence. +.IP "%\fBD\fP%" 10 +Current date (\fIYY\fR/\fIMM\fR/\fIDD\fR). +.IP "%\fBH\fP%" 10 +Current date (\fIMM\fR/\fIDD\fR/\fIYY\fR). +.IP "%\fBT\fP%" 10 +Current time (\fIHH\fR:\fIMM\fR:\fISS\fR). +.IP "%\fBE\fP%" 10 +Date newest applied delta was created (\fIYY\fR/\fIMM\fR/\fIDD\fR). +.IP "%\fBG\fP%" 10 +Date newest applied delta was created (\fIMM\fR/\fIDD\fR/\fIYY\fR). +.IP "%\fBU\fP%" 10 +Time newest applied delta was created (\fIHH\fR:\fIMM\fR:\fISS\fR). +.IP "%\fBY\fP%" 10 +Module type: value of the +.BR t +flag in the SCCS file. +.IP "%\fBF\fP%" 10 +SCCS filename. +.IP "%\fBP\fP%" 10 +SCCS absolute pathname. +.IP "%\fBQ\fP%" 10 +The value of the +.BR q +flag in the file. +.IP "%\fBC\fP%" 10 +Current line number. This keyword is intended for identifying messages +output by the program, such as ``this should not have happened'' type +errors. It is not intended to be used on every line to provide +sequence numbers. +.IP "%\fBZ\fP%" 10 +The four-character string +.BR \(dq@(#)\(dq +recognizable by +.IR what . +.IP "%\fBW\fP%" 10 +A shorthand notation for constructing +.IR what +strings: +.RS 10 +.sp +.RS 4 +.nf + +%\^W\^%=%\^Z\^%%\^M\^%<tab>%\^I\^% +.fi +.P +.RE +.RE +.IP "%\fBA\fP%" 10 +Another shorthand notation for constructing +.IR what +strings: +.RS 10 +.sp +.RS 4 +.nf + +%\^A\^%=%\^Z\^%%\^Y\^%%\^M\^%%\^I\^%%\^Z\^% +.fi +.P +.RE +.RE +.SH "EXIT STATUS" +The following exit values shall be returned: +.IP "\00" 6 +Successful completion. +.IP >0 6 +An error occurred. +.SH "CONSEQUENCES OF ERRORS" +Default. +.LP +.IR "The following sections are informative." +.SH "APPLICATION USAGE" +Problems can arise if the system date and time have been modified (for +example, put forward and then back again, or unsynchronized clocks +across a network) and can also arise when different values of the +.IR TZ +environment variable are used. +.P +Problems of a similar nature can also arise for the operation of the +.IR delta +utility, which compares the previous file body against the working file +as part of its normal operation. +.SH EXAMPLES +None. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIadmin\fR\^", +.IR "\fIdelta\fR\^", +.IR "\fIprs\fR\^", +.IR "\fIwhat\fR\^" +.P +The Base Definitions volume of POSIX.1\(hy2017, +.IR "Chapter 8" ", " "Environment Variables", +.IR "Section 12.2" ", " "Utility Syntax Guidelines" +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 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 . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . |