1GET(1P) POSIX Programmer's Manual GET(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 get - get a version of an SCCS file (DEVELOPMENT)
13
15 get [-begkmnlLpst][-c cutoff][-i list][-r SID][-x list] file...
16
18 The get utility shall generate a text file from each named SCCS file
19 according to the specifications given by its options.
20 The generated text shall normally be written into a file called the g-
22 file whose name is derived from the SCCS filename by simply removing
23 the leading "s." .
24
26 The get utility shall conform to the Base Definitions volume of
27 IEEE Std 1003.1-2001, Section 12.2, Utility Syntax Guidelines.
28 The following options shall be supported:
30 -r SID
32 Indicate the SCCS Identification String (SID) of the version
33 (delta) of an SCCS file to be retrieved. The table shows, for
34 the most useful cases, what version of an SCCS file is retrieved
35 (as well as the SID of the version to be eventually created by
36 delta if the -e option is also used), as a function of the SID
37 specified.
38 -c cutoff
40 Indicate the cutoff date-time, in the form:
41 YY[MM[DD[HH[MM[SS]]]]]
44 For the YY component, values in the range [69,99] shall refer to years
46 1969 to 1999 inclusive, and values in the range [00,68] shall refer to
47 years 2000 to 2068 inclusive.
48 Note:
50 It is expected that in a future version of IEEE Std 1003.1-2001
51 the default century inferred from a 2-digit year will change.
52 (This would apply to all commands accepting a 2-digit year as
53 input.)
54 No changes (deltas) to the SCCS file that were created after the speci‐
57 fied cutoff date-time shall be included in the generated text file.
58 Units omitted from the date-time default to their maximum possible val‐
59 ues; for example, -c 7502 is equivalent to -c 750228235959.
60 Any number of non-numeric characters may separate the various 2-digit
62 pieces of the cutoff date-time. This feature allows the user to specify
63 a cutoff date in the form: -c "77/2/2 9:22:25".
64 -e Indicate that the get is for the purpose of editing or making a
66 change (delta) to the SCCS file via a subsequent use of delta.
67 The -e option used in a get for a particular version (SID) of
68 the SCCS file shall prevent further get commands from editing on
69 the same SID until delta is executed or the j (joint edit) flag
70 is set in the SCCS file. Concurrent use of get -e for different
71 SIDs is always allowed.
72 If the g-file generated by get with a -e option is accidentally ruined
74 in the process of editing, it may be regenerated by re-executing the
75 get command with the -k option in place of the -e option.
76 SCCS file protection specified via the ceiling, floor, and authorized
78 user list stored in the SCCS file shall be enforced when the -e option
79 is used.
80 -b Use with the -e option to indicate that the new delta should
82 have an SID in a new branch as shown in the table below. This
83 option shall be ignored if the b flag is not present in the file
84 or if the retrieved delta is not a leaf delta. (A leaf delta is
85 one that has no successors on the SCCS file tree.)
86 Note:
88 A branch delta may always be created from a non-leaf delta.
89 -i list
92 Indicate a list of deltas to be included (forced to be applied)
93 in the creation of the generated file. The list has the follow‐
94 ing syntax:
95 <list> ::= <range> | <list> , <range>
98 <range> ::= SID | SID - SID
99 SID, the SCCS Identification of a delta, may be in any form shown in
101 the "SID Specified" column of the table in the EXTENDED DESCRIPTION
102 section, except that the result of supplying a partial SID is unspeci‐
103 fied. A diagnostic message shall be written if the first SID in the
104 range is not an ancestor of the second SID in the range.
105 -x list
107 Indicate a list of deltas to be excluded (forced not to be
108 applied) in the creation of the generated file. See the -i
109 option for the list format.
110 -k Suppress replacement of identification keywords (see below) in
112 the retrieved text by their value. The -k option shall be
113 implied by the -e option.
114 -l Write a delta summary into an l-file.
116 -L Write a delta summary to standard output. All informative output
118 that normally is written to standard output shall be written to
119 standard error instead, unless the -s option is used, in which
120 case it shall be suppressed.
121 -p Write the text retrieved from the SCCS file to the standard out‐
123 put. No g-file shall be created. All informative output that
124 normally goes to the standard output shall go to standard error
125 instead, unless the -s option is used, in which case it shall
126 disappear.
127 -s Suppress all informative output normally written to standard
129 output. However, fatal error messages (which shall always be
130 written to the standard error) shall remain unaffected.
131 -m Precede each text line retrieved from the SCCS file by the SID
133 of the delta that inserted the text line in the SCCS file. The
134 format shall be:
135 "%s\t%s", <SID>, <text line>
138 -n Precede each generated text line with the %M% identification
140 keyword value (see below). The format shall be:
141 "%s\t%s", <%M% value>, <text line>
144 When both the -m and -n options are used, the <text line> shall be
146 replaced by the -m option-generated format.
147 -g Suppress the actual retrieval of text from the SCCS file. It is
149 primarily used to generate an l-file, or to verify the existence
150 of a particular SID.
151 -t Use to access the most recently created (top) delta in a given
153 release (for example, -r 1), or release and level (for example,
154 -r 1.2).
155
158 The following operands shall be supported:
159 file A pathname of an existing SCCS file or a directory. If file is a
161 directory, the get utility shall behave as though each file in
162 the directory were specified as a named file, except that non-
163 SCCS files (last component of the pathname does not begin with
164 s.) and unreadable files shall be silently ignored.
165 If exactly one file operand appears, and it is '-', the standard input
167 shall be read; each line of the standard input is taken to be the name
168 of an SCCS file to be processed. Non-SCCS files and unreadable files
169 shall be silently ignored.
170
173 The standard input shall be a text file used only if the file operand
174 is specified as '-' . Each line of the text file shall be interpreted
175 as an SCCS pathname.
176
178 The SCCS files shall be files of an unspecified format.
179
181 The following environment variables shall affect the execution of get:
182 LANG Provide a default value for the internationalization variables
184 that are unset or null. (See the Base Definitions volume of
185 IEEE Std 1003.1-2001, Section 8.2, Internationalization Vari‐
186 ables for the precedence of internationalization variables used
187 to determine the values of locale categories.)
188 LC_ALL If set to a non-empty string value, override the values of all
190 the other internationalization variables.
191 LC_CTYPE
193 Determine the locale for the interpretation of sequences of
194 bytes of text data as characters (for example, single-byte as
195 opposed to multi-byte characters in arguments and input files).
196 LC_MESSAGES
198 Determine the locale that should be used to affect the format
199 and contents of diagnostic messages written to standard error,
200 and informative messages written to standard output (or standard
201 error, if the -p option is used).
202 NLSPATH
204 Determine the location of message catalogs for the processing of
205 LC_MESSAGES .
206 TZ Determine the timezone in which the times and dates written in
208 the SCCS file are evaluated. If the TZ variable is unset or
209 NULL, an unspecified system default timezone is used.
210
213 Default.
214
216 For each file processed, get shall write to standard output the SID
217 being accessed and the number of lines retrieved from the SCCS file, in
218 the following format:
219 "%s\n%d lines\n", <SID>, <number of lines>
222 If the -e option is used, the SID of the delta to be made shall appear
224 after the SID accessed and before the number of lines generated, in the
225 POSIX locale:
226 "%s\nnew delta %s\n%d lines\n", <SID accessed>,
229 <SID to be made>, <number of lines>
230 If there is more than one named file or if a directory or standard
232 input is named, each pathname shall be written before each of the lines
233 shown in one of the preceding formats:
234 "\n%s:\n", <pathname>
237 If the -L option is used, a delta summary shall be written following
239 the format specified below for l-files.
240 If the -i option is used, included deltas shall be listed following the
242 notation, in the POSIX locale:
243 "Included:\n"
246 If the -x option is used, excluded deltas shall be listed following the
248 notation, in the POSIX locale:
249 "Excluded:\n"
252 If the -p or -L options are specified, the standard output shall con‐
254 sist of the text retrieved from the SCCS file.
255
257 The standard error shall be used only for diagnostic messages, except
258 if the -p or -L options are specified, it shall include all informative
259 messages normally sent to standard output.
260
262 Several auxiliary files may be created by get. These files are known
263 generically as the g-file, l-file, p-file, and z-file. The letter
264 before the hyphen is called the tag. An auxiliary filename shall be
265 formed from the SCCS filename: the application shall ensure that the
266 last component of all SCCS filenames is of the form s. module-name;
267 the auxiliary files shall be named by replacing the leading s with the
268 tag. The g-file shall be an exception to this scheme: the g-file is
269 named by removing the s. prefix. For example, for s.xyz.c, the auxil‐
270 iary filenames would be xyz.c, l.xyz.c, p.xyz.c, and z.xyz.c, respec‐
271 tively.
272 The g-file, which contains the generated text, shall be created in the
274 current directory (unless the -p option is used). A g-file shall be
275 created in all cases, whether or not any lines of text were generated
276 by the get. It shall be owned by the real user. If the -k option is
277 used or implied, the g-file shall be writable by the owner only (read-
278 only for everyone else); otherwise, it shall be read-only. Only the
279 real user need have write permission in the current directory.
280 The l-file shall contain a table showing which deltas were applied in
282 generating the retrieved text. The l-file shall be created in the cur‐
283 rent directory if the -l option is used; it shall be read-only and it
284 is owned by the real user. Only the real user need have write permis‐
285 sion in the current directory.
286 Lines in the l-file shall have the following format:
288 "%c%c%c %s\t%s %s\n", <code1>, <code2>, <code3>,
291 <SID>, <date-time>, <login>
292 where the entries are:
294 <code1>
296 A <space> if the delta was applied; '*' otherwise.
297 <code2>
299 A <space> if the delta was applied or was not applied and
300 ignored; '*' if the delta was not applied and was not ignored.
301 <code3>
303 A character indicating a special reason why the delta was or was
304 not applied:
305 I
307 Included.
308 X
310 Excluded.
311 C
313 Cut off (by a -c option).
314 <date-time>
317 Date and time (using the format of the date utility's %y / %m /
318 %d %T conversion specification format) of creation.
319 <login>
321 Login name of person who created delta.
322 The comments and MR data shall follow on subsequent lines, indented one
325 <tab>. A blank line shall terminate each entry.
326 The p-file shall be used to pass information resulting from a get with
328 a -e option along to delta. Its contents shall also be used to prevent
329 a subsequent execution of get with a -e option for the same SID until
330 delta is executed or the joint edit flag, j, is set in the SCCS file.
331 The p-file shall be created in the directory containing the SCCS file
332 and the application shall ensure that the effective user has write per‐
333 mission in that directory. It shall be writable by owner only, and
334 owned by the effective user. Each line in the p-file shall have the
335 following format:
336 "%s %s %s %s%s%s\n", <g-file SID>,
339 <SID of new delta>, <login-name of real user>,
340 <date-time>, <i-value>, <x-value>
341 where <i-value> uses the format "" if no -i option was specified, and
343 shall use the format:
344 " -i%s", <-i option option-argument>
347 if a -i option was specified and <x-value> uses the format "" if no -x
349 option was specified, and shall use the format:
350 " -x%s", <-x option option-argument>
353 if a -x option was specified. There can be an arbitrary number of lines
355 in the p-file at any time; no two lines shall have the same new delta
356 SID.
357 The z-file shall serve as a lock-out mechanism against simultaneous
359 updates. Its contents shall be the binary process ID of the command
360 (that is, get) that created it. The z-file shall be created in the
361 directory containing the SCCS file for the duration of get. The same
362 protection restrictions as those for the p-file shall apply for the z-
363 file. The z-file shall be created read-only.
364
366 Determination of SCCS Identification String
367 SID* -b Keyletter Other SID SID of Delta
368 Specified Used& Conditions Retrieved to be Created
369 none&& no R defaults to mR mR.mL mR.(mL+1)
370 none&& yes R defaults to mR mR.mL mR.mL.(mB+1).1
371 R no R > mR mR.mL R.1***
372 R no R = mR mR.mL mR.(mL+1)
373 R yes R > mR mR.mL mR.mL.(mB+1).1
374 R yes R = mR mR.mL mR.mL.(mB+1).1
375 R - R < mR and R does not hR.mL** hR.mL.(mB+1).1
376 exist
377 R - Trunk successor in R.mL R.mL.(mB+1).1
378 release > R and R
379 exists
380 R.L no No trunk successor R.L R.(L+1)
381 R.L yes No trunk successor R.L R.L.(mB+1).1
382 R.L - Trunk successor in R.L R.L.(mB+1).1
383 release >= R
384 R.L.B no No branch successor R.L.B.mS R.L.B.(mS+1)
385 R.L.B yes No branch successor R.L.B.mS R.L.(mB+1).1
386 R.L.B.S no No branch successor R.L.B.S R.L.B.(S+1)
387 R.L.B.S yes No branch successor R.L.B.S R.L.(mB+1).1
388 R.L.B.S - Branch successor R.L.B.S R.L.(mB+1).1
389 * R, L, B, and S are the release, level, branch, and sequence com‐
391 ponents of the SID, respectively; m means maximum. Thus, for
392 example, R.mL means "the maximum level number within release
393 R''; R.L.(mB+1).1 means "the first sequence number on the new
394 branch (that is, maximum branch number plus one) of level L
395 within release R". Note that if the SID specified is of the form
396 R.L, R.L.B, or R.L.B.S, each of the specified components shall
397 exist.
398 ** hR is the highest existing release that is lower than the speci‐
400 fied, nonexistent, release R.
401 *** This is used to force creation of the first delta in a new
403 release.
404 & The -b option is effective only if the b flag is present in the
406 file. An entry of '-' means "irrelevant".
407 && This case applies if the d (default SID) flag is not present in
409 the file. If the d flag is present in the file, then the SID
410 obtained from the d flag is interpreted as if it had been speci‐
411 fied on the command line. Thus, one of the other cases in this
412 table applies.
413 System Date and Time
416 When a g-file is generated, the creation time of deltas in the SCCS
417 file may be taken into account. If any of these times are apparently in
418 the future, the behavior is unspecified.
419 Identification Keywords
421 Identifying information shall be inserted into the text retrieved from
422 the SCCS file by replacing identification keywords with their value
423 wherever they occur. The following keywords may be used in the text
424 stored in an SCCS file:
425 %M% Module name: either the value of the m flag in the file, or if
427 absent, the name of the SCCS file with the leading s. removed.
428 %I% SCCS identification (SID) (%R%.%L% or %R%.%L%.%B%.%S%) of the
430 retrieved text.
431 %R% Release.
433 %L% Level.
435 %B% Branch.
437 %S% Sequence.
439 %D% Current date (YY/MM/DD).
441 %H% Current date (MM/DD/YY).
443 %T% Current time (HH:MM:SS).
445 %E% Date newest applied delta was created (YY/MM/DD).
447 %G% Date newest applied delta was created (MM/DD/YY).
449 %U% Time newest applied delta was created (HH:MM:SS).
451 %Y% Module type: value of the t flag in the SCCS file.
453 %F% SCCS filename.
455 %P% SCCS absolute pathname.
457 %Q% The value of the q flag in the file.
459 %C% Current line number. This keyword is intended for identifying
461 messages output by the program, such as "this should not have
462 happened" type errors. It is not intended to be used on every
463 line to provide sequence numbers.
464 %Z% The four-character string "@(#)" recognizable by what.
466 %W% A shorthand notation for constructing what strings:
468 %W%=%Z%%M%<tab>%I%
471 %A% Another shorthand notation for constructing what strings:
473 %A%=%Z%%Y%%M%%I%%Z%
476
479 The following exit values shall be returned:
480 0 Successful completion.
482 >0 An error occurred.
484
487 Default.
488 The following sections are informative.
490
492 Problems can arise if the system date and time have been modified (for
493 example, put forward and then back again, or unsynchronized clocks
494 across a network) and can also arise when different values of the TZ
495 environment variable are used.
496 Problems of a similar nature can also arise for the operation of the
498 delta utility, which compares the previous file body against the work‐
499 ing file as part of its normal operation.
500
502 None.
503
505 None.
506
508 The -lp option may be withdrawn in a future version.
509
511 admin, delta, prs, what
512
514 Portions of this text are reprinted and reproduced in electronic form
515 from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology
516 -- Portable Operating System Interface (POSIX), The Open Group Base
517 Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of
518 Electrical and Electronics Engineers, Inc and The Open Group. In the
519 event of any discrepancy between this version and the original IEEE and
520 The Open Group Standard, the original IEEE and The Open Group Standard
521 is the referee document. The original Standard can be obtained online
522 at http://www.opengroup.org/unix/online.html .
523IEEE/The Open Group 2003 GET(1P)