diff options
Diffstat (limited to 'man1p/get.1p')
-rw-r--r-- | man1p/get.1p | 737 |
1 files changed, 737 insertions, 0 deletions
diff --git a/man1p/get.1p b/man1p/get.1p new file mode 100644 index 000000000..9d0d31b1b --- /dev/null +++ b/man1p/get.1p @@ -0,0 +1,737 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "GET" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" get +.SH NAME +get \- get a version of an SCCS file (\fBDEVELOPMENT\fP) +.SH SYNOPSIS +.LP +\fBget\fP \fB[\fP\fB-begkmnlLpst\fP\fB][\fP\fB-c\fP \fIcutoff\fP\fB][\fP\fB-i\fP +\fIlist\fP\fB][\fP\fB-r\fP \fISID\fP\fB][\fP\fB-x\fP \fIlist\fP\fB]\fP +\fIfile\fP\fB... \fP +.SH DESCRIPTION +.LP +The \fIget\fP utility shall generate a text file from each named SCCS +\fIfile\fP according to the specifications given by its +options. +.LP +The generated text shall normally be written into a file called the +\fBg-file\fP whose name is derived from the SCCS filename +by simply removing the leading \fB"s."\fP . +.SH OPTIONS +.LP +The \fIget\fP utility shall conform to the Base Definitions volume +of IEEE\ Std\ 1003.1-2001, Section 12.2, Utility Syntax Guidelines. +.LP +The following options shall be supported: +.TP 7 +\fB-r\ \fP \fISID\fP +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 \fIdelta\fP +if the \fB-e\fP option is also used), as a function of the SID specified. +.TP 7 +\fB-c\ \fP \fIcutoff\fP +Indicate the \fIcutoff\fP date-time, in the form: +.sp +.RS +.nf + +\fIYY\fP\fB[\fP\fIMM\fP\fB[\fP\fIDD\fP\fB[\fP\fIHH\fP\fB[\fP\fIMM\fP\fB[\fP\fISS\fP\fB]]]]]\fP +.fi +.RE +.LP +For the \fIYY\fP 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 7 +\fBNote:\fP +.RS +It is expected that in a future version of IEEE\ Std\ 1003.1-2001 +the default century inferred from a 2-digit year will +change. (This would apply to all commands accepting a 2-digit year +as input.) +.RE +.sp +.LP +No changes (deltas) to the SCCS file that were created after the specified +\fIcutoff\fP date-time shall be included in the +generated text file. Units omitted from the date-time default to their +maximum possible values; for example, \fB-c\fP 7502 is +equivalent to \fB-c\fP 750228235959. +.LP +Any number of non-numeric characters may separate the various 2-digit +pieces of the \fIcutoff\fP date-time. This feature allows +the user to specify a \fIcutoff\fP date in the form: \fB-c\fP "77/2/2\ 9:22:25". +.TP 7 +\fB-e\fP +Indicate that the \fIget\fP is for the purpose of editing or making +a change (delta) to the SCCS file via a subsequent use of +\fIdelta\fP. The \fB-e\fP option used in a \fIget\fP for a particular +version (SID) of the +SCCS file shall prevent further \fIget\fP commands from editing on +the same SID until \fIdelta\fP is executed or the \fBj\fP (joint edit) +flag is set in the SCCS file. Concurrent use of +\fIget\fP \fB-e\fP for different SIDs is always allowed. +.LP +If the \fBg-file\fP generated by \fIget\fP with a \fB-e\fP option +is accidentally ruined in the process of editing, it may be +regenerated by re-executing the \fIget\fP command with the \fB-k\fP +option in place of the \fB-e\fP option. +.LP +SCCS file protection specified via the ceiling, floor, and authorized +user list stored in the SCCS file shall be enforced when +the \fB-e\fP option is used. +.TP 7 +\fB-b\fP +Use with the \fB-e\fP 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 \fBb\fP 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.) +.TP 7 +\fBNote:\fP +.RS +A branch delta may always be created from a non-leaf delta. +.RE +.sp +.TP 7 +\fB-i\ \fP \fIlist\fP +Indicate a \fIlist\fP of deltas to be included (forced to be applied) +in the creation of the generated file. The \fIlist\fP +has the following syntax: +.sp +.RS +.nf + +\fB<list> ::= <range> | <list> , <range> +<range> ::= SID | SID - SID +\fP +.fi +.RE +.LP +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. +.TP 7 +\fB-x\ \fP \fIlist\fP +Indicate a \fIlist\fP of deltas to be excluded (forced not to be applied) +in the creation of the generated file. See the +\fB-i\fP option for the \fIlist\fP format. +.TP 7 +\fB-k\fP +Suppress replacement of identification keywords (see below) in the +retrieved text by their value. The \fB-k\fP option shall be +implied by the \fB-e\fP option. +.TP 7 +\fB-l\fP +Write a delta summary into an \fBl-file\fP. +.TP 7 +\fB-L\fP +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 \fB-s\fP option is used, in +which case it shall be suppressed. +.TP 7 +\fB-p\fP +Write the text retrieved from the SCCS file to the standard output. +No \fBg-file\fP shall be created. All informative output +that normally goes to the standard output shall go to standard error +instead, unless the \fB-s\fP option is used, in which case it +shall disappear. +.TP 7 +\fB-s\fP +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. +.TP 7 +\fB-m\fP +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: +.sp +.RS +.nf + +\fB"%s\\t%s", <\fP\fISID\fP\fB>, <\fP\fItext line\fP\fB> +\fP +.fi +.RE +.TP 7 +\fB-n\fP +Precede each generated text line with the %\fBM\fP% identification +keyword value (see below). The format shall be: +.sp +.RS +.nf + +\fB"%s\\t%s", <\fP\fI%M% value\fP\fB>, <\fP\fItext line\fP\fB> +\fP +.fi +.RE +.LP +When both the \fB-m\fP and \fB-n\fP options are used, the <\fItext\ line\fP> +shall be replaced by the \fB-m\fP +option-generated format. +.TP 7 +\fB-g\fP +Suppress the actual retrieval of text from the SCCS file. It is primarily +used to generate an \fBl-file\fP, or to verify the +existence of a particular SID. +.TP 7 +\fB-t\fP +Use to access the most recently created (top) delta in a given release +(for example, \fB-r 1\fP), or release and level (for +example, \fB-r 1.2\fP). +.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 \fIget\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. +.LP +If exactly one \fIfile\fP operand appears, and it is \fB'-'\fP , 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. +.sp +.SH STDIN +.LP +The standard input shall be a text file used only if the \fIfile\fP +operand is specified as \fB'-'\fP . Each line of the +text file shall be interpreted as an SCCS pathname. +.SH INPUT FILES +.LP +The SCCS files shall be files of an unspecified format. +.SH ENVIRONMENT VARIABLES +.LP +The following environment variables shall affect the execution of +\fIget\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 informative messages written to standard output (or standard error, +if the \fB-p\fP option is used). +.TP 7 +\fINLSPATH\fP +Determine the location of message catalogs for the processing of \fILC_MESSAGES +\&.\fP +.TP 7 +\fITZ\fP +Determine the timezone in which the times and dates written in the +SCCS file are evaluated. If the \fITZ\fP variable is unset +or NULL, an unspecified system default timezone is used. +.sp +.SH ASYNCHRONOUS EVENTS +.LP +Default. +.SH STDOUT +.LP +For each file processed, \fIget\fP 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 +.nf + +\fB"%s\\n%d lines\\n", <\fP\fISID\fP\fB>, <\fP\fInumber of lines\fP\fB> +\fP +.fi +.RE +.LP +If the \fB-e\fP 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 +.nf + +\fB"%s\\nnew delta %s\\n%d lines\\n", <\fP\fISID accessed\fP\fB>, + <\fP\fISID to be made\fP\fB>, <\fP\fInumber of lines\fP\fB> +\fP +.fi +.RE +.LP +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 +.nf + +\fB"\\n%s:\\n", <\fP\fIpathname\fP\fB> +\fP +.fi +.RE +.LP +If the \fB-L\fP option is used, a delta summary shall be written following +the format specified below for \fBl-files\fP. +.LP +If the \fB-i\fP option is used, included deltas shall be listed following +the notation, in the POSIX locale: +.sp +.RS +.nf + +\fB"Included:\\n" +\fP +.fi +.RE +.LP +If the \fB-x\fP option is used, excluded deltas shall be listed following +the notation, in the POSIX locale: +.sp +.RS +.nf + +\fB"Excluded:\\n" +\fP +.fi +.RE +.LP +If the \fB-p\fP or \fB-L\fP options are specified, the standard output +shall consist of the text retrieved from the SCCS +file. +.SH STDERR +.LP +The standard error shall be used only for diagnostic messages, except +if the \fB-p\fP or \fB-L\fP options are specified, it +shall include all informative messages normally sent to standard output. +.SH OUTPUT FILES +.LP +Several auxiliary files may be created by \fIget\fP. These files are +known generically as the \fBg-file\fP, \fBl-file\fP, +\fBp-file\fP, and \fBz-file\fP. The letter before the hyphen is called +the \fItag\fP. 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 \fBs.\fP +\fImodule-name\fP; the auxiliary files shall be named by replacing +the leading \fBs\fP with the tag. The \fBg-file\fP shall be +an exception to this scheme: the \fBg-file\fP is named by removing +the \fBs.\fP prefix. For example, for \fBs.xyz.c\fP, the +auxiliary filenames would be \fBxyz.c\fP, \fBl.xyz.c\fP, \fBp.xyz.c\fP, +and \fBz.xyz.c\fP, respectively. +.LP +The \fBg-file\fP, which contains the generated text, shall be created +in the current directory (unless the \fB-p\fP option is +used). A \fBg-file\fP shall be created in all cases, whether or not +any lines of text were generated by the \fIget\fP. It shall +be owned by the real user. If the \fB-k\fP option is used or implied, +the \fBg-file\fP 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. +.LP +The \fBl-file\fP shall contain a table showing which deltas were applied +in generating the retrieved text. The \fBl-file\fP +shall be created in the current directory if the \fB-l\fP 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. +.LP +Lines in the \fBl-file\fP shall have the following format: +.sp +.RS +.nf + +\fB"%c%c%c %s\\t%s %s\\n", <\fP\fIcode1\fP\fB>, <\fP\fIcode2\fP\fB>, <\fP\fIcode3\fP\fB>, + <\fP\fISID\fP\fB>, <\fP\fIdate-time\fP\fB>, <\fP\fIlogin\fP\fB> +\fP +.fi +.RE +.LP +where the entries are: +.TP 7 +<\fIcode1\fP> +A <space> if the delta was applied; \fB'*'\fP otherwise. +.TP 7 +<\fIcode2\fP> +A <space> if the delta was applied or was not applied and ignored; +\fB'*'\fP if the delta was not applied and was not +ignored. +.TP 7 +<\fIcode3\fP> +A character indicating a special reason why the delta was or was not +applied: +.TP 7 +\fBI\fP +.RS +Included. +.RE +.TP 7 +\fBX\fP +.RS +Excluded. +.RE +.TP 7 +\fBC\fP +.RS +Cut off (by a \fB-c\fP option). +.RE +.sp +.TP 7 +<\fIdate-time\fP> +Date and time (using the format of the \fIdate\fP utility's \fB%y\fP +/ \fB%m\fP / +\fB%d\fP \fB%T\fP conversion specification format) of creation. +.TP 7 +<\fIlogin\fP> +Login name of person who created \fIdelta\fP. +.sp +.LP +The comments and MR data shall follow on subsequent lines, indented +one <tab>. A blank line shall terminate each +entry. +.LP +The \fBp-file\fP shall be used to pass information resulting from +a \fIget\fP with a \fB-e\fP option along to \fIdelta\fP. Its contents +shall also be used to prevent a subsequent execution of \fIget\fP +with a +\fB-e\fP option for the same SID until \fIdelta\fP is executed or +the joint edit flag, +\fBj\fP, is set in the SCCS file. The \fBp-file\fP 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 \fBp-file\fP shall have the following +format: +.sp +.RS +.nf + +\fB"%s %s %s %s%s%s\\n", <\fP\fIg-file SID\fP\fB>, + <\fP\fISID of new delta\fP\fB>, <\fP\fIlogin-name of real user\fP\fB>, + <\fP\fIdate-time\fP\fB>, <\fP\fIi-value\fP\fB>, <\fP\fIx-value\fP\fB> +\fP +.fi +.RE +.LP +where <\fIi-value\fP> uses the format \fB""\fP if no \fB-i\fP option +was specified, and shall use the format: +.sp +.RS +.nf + +\fB" -i%s", <-i option\fP \fIoption-argument\fP\fB> +\fP +.fi +.RE +.LP +if a \fB-i\fP option was specified and <\fIx-value\fP> uses the format +\fB""\fP if no \fB-x\fP option was specified, +and shall use the format: +.sp +.RS +.nf + +\fB" -x%s", <-x option\fP \fIoption-argument\fP\fB> +\fP +.fi +.RE +.LP +if a \fB-x\fP option was specified. There can be an arbitrary number +of lines in the \fBp-file\fP at any time; no two lines +shall have the same new delta SID. +.LP +The \fBz-file\fP shall serve as a lock-out mechanism against simultaneous +updates. Its contents shall be the binary process ID +of the command (that is, \fIget\fP) that created it. The \fBz-file\fP +shall be created in the directory containing the SCCS file +for the duration of \fIget\fP. The same protection restrictions as +those for the \fBp-file\fP shall apply for the \fBz-file\fP. +The \fBz-file\fP shall be created read-only. +.br +.SH EXTENDED DESCRIPTION +.TS C +center;c1 s1 s1 s1 s. +\fBDetermination of SCCS Identification String\fP +.T& + l1 l1 lw(22)1 l1 l. +\fBSID*\fP \fB-b Keyletter\fP T{ +.na +\fBOther\fP +.ad +T} \fBSID\fP \fBSID of Delta\fP +\fBSpecified\fP \fBUsed&\fP T{ +.na +\fBConditions\fP +.ad +T} \fBRetrieved\fP \fBto be Created\fP +none&& no T{ +.na +R defaults to mR +.ad +T} mR.mL mR.(mL+1) +none&& yes T{ +.na +R defaults to mR +.ad +T} mR.mL mR.mL.(mB+1).1 +R no T{ +.na +R > mR +.ad +T} mR.mL R.1*** +R no T{ +.na +R = mR +.ad +T} mR.mL mR.(mL+1) +R yes T{ +.na +R > mR +.ad +T} mR.mL mR.mL.(mB+1).1 +R yes T{ +.na +R = mR +.ad +T} mR.mL mR.mL.(mB+1).1 +R - T{ +.na +R < mR and R does not exist +.ad +T} hR.mL** hR.mL.(mB+1).1 +R - T{ +.na +Trunk successor in release > R and R exists +.ad +T} R.mL R.mL.(mB+1).1 +R.L no T{ +.na +No trunk successor +.ad +T} R.L R.(L+1) +R.L yes T{ +.na +No trunk successor +.ad +T} R.L R.L.(mB+1).1 +R.L - T{ +.na +Trunk successor in release >= R +.ad +T} R.L R.L.(mB+1).1 +R.L.B no T{ +.na +No branch successor +.ad +T} R.L.B.mS R.L.B.(mS+1) +R.L.B yes T{ +.na +No branch successor +.ad +T} R.L.B.mS R.L.(mB+1).1 +R.L.B.S no T{ +.na +No branch successor +.ad +T} R.L.B.S R.L.B.(S+1) +R.L.B.S yes T{ +.na +No branch successor +.ad +T} R.L.B.S R.L.(mB+1).1 +R.L.B.S - T{ +.na +Branch successor +.ad +T} R.L.B.S R.L.(mB+1).1 +.TE +.TP 7 +* +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. +.TP 7 +** +hR is the highest existing release that is lower than the specified, +nonexistent, release R. +.TP 7 +*** +This is used to force creation of the first delta in a new release. +.TP 7 +& +The \fB-b\fP option is effective only if the \fBb\fP flag is present +in the file. An entry of \fB'-'\fP means +"irrelevant". +.TP 7 +&& +This case applies if the \fBd\fP (default SID) flag is not present +in the file. If the \fBd\fP flag is present in the file, +then the SID obtained from the \fBd\fP flag is interpreted as if it +had been specified on the command line. Thus, one of the other +cases in this table applies. +.sp +.SS System Date and Time +.LP +When a \fBg-file\fP 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 +.LP +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: +.TP 7 +%\fBM\fP% +Module name: either the value of the \fBm\fP flag in the file, or +if absent, the name of the SCCS file with the leading +\fBs.\fP removed. +.TP 7 +%\fBI\fP% +SCCS identification (SID) (%\fBR\fP%.%\fBL\fP% or %\fBR\fP%.%\fBL\fP%.%\fBB\fP%.%\fBS\fP%) +of the retrieved text. +.TP 7 +%\fBR\fP% +Release. +.TP 7 +%\fBL\fP% +Level. +.TP 7 +%\fBB\fP% +Branch. +.TP 7 +%\fBS\fP% +Sequence. +.TP 7 +%\fBD\fP% +Current date (\fIYY\fP/\fIMM\fP/\fIDD\fP). +.TP 7 +%\fBH\fP% +Current date (\fIMM\fP/\fIDD\fP/\fIYY\fP). +.TP 7 +%\fBT\fP% +Current time (\fIHH\fP:\fIMM\fP:\fISS\fP). +.TP 7 +%\fBE\fP% +Date newest applied delta was created (\fIYY\fP/\fIMM\fP/\fIDD\fP). +.TP 7 +%\fBG\fP% +Date newest applied delta was created (\fIMM\fP/\fIDD\fP/\fIYY\fP). +.TP 7 +%\fBU\fP% +Time newest applied delta was created (\fIHH\fP:\fIMM\fP:\fISS\fP). +.TP 7 +%\fBY\fP% +Module type: value of the \fBt\fP flag in the SCCS file. +.TP 7 +%\fBF\fP% +SCCS filename. +.TP 7 +%\fBP\fP% +SCCS absolute pathname. +.TP 7 +%\fBQ\fP% +The value of the \fBq\fP flag in the file. +.TP 7 +%\fBC\fP% +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. +.TP 7 +%\fBZ\fP% +The four-character string \fB"@(#)"\fP recognizable by \fIwhat\fP. +.TP 7 +%\fBW\fP% +A shorthand notation for constructing \fIwhat\fP strings: +.sp +.RS +.nf + +\fB%W%=%Z%%M%<tab>%I% +\fP +.fi +.RE +.TP 7 +%\fBA\fP% +Another shorthand notation for constructing \fIwhat\fP strings: +.sp +.RS +.nf + +\fB%A%=%Z%%Y%%M%%I%%Z% +\fP +.fi +.RE +.sp +.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 +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 \fITZ\fP environment variable are +used. +.LP +Problems of a similar nature can also arise for the operation of the +\fIdelta\fP utility, +which compares the previous file body against the working file as +part of its normal operation. +.SH EXAMPLES +.LP +None. +.SH RATIONALE +.LP +None. +.SH FUTURE DIRECTIONS +.LP +The \fB-lp\fP option may be withdrawn in a future version. +.SH SEE ALSO +.LP +\fIadmin\fP , \fIdelta\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 . |