pdp11v/usr/man/u_man/man1/get.1

'\" t
.tr ~
.nr f 0
.de SP
.if n .ul
\%[\fB\-\\$1\fR\\c
.if n .ul 0
\\$2\\$3
..
.de SF
.if n .ul
\%[\fB\-\\$1\fR]
.if n .ul 0
..
.ds M)  \fB\s-1MR\s+1\fR
.ds S)  \s-1SCCS\s+1
.ds I)  \s-1SID\s+1
.TH GET 1
.SH NAME
get \- get a version of an \s-1SCCS\s+1 file
.SH SYNOPSIS
.B get
.SP r SID ]
.SP c cutoff ]
.SP i list ]
.SP x list ]
.SP a seq-no. ]
.SF k
.SF e
.if n .ul
[\-l[p]]
.if n .ul 0
.SF p
.SF m
.SF n
.SF s
.SF b
.SF g
.SF t
file
.B ".\|.\|."
.SH DESCRIPTION
.I Get\^
generates an \s-1ASCII\s+1 text file from
each named \*(S) file according to the specifications given
by its keyletter arguments,
which begin with \fB\-\fR.
The arguments
may be specified in any order,
but all keyletter arguments apply to all named \*(S) files.
If a directory is named,
.I get\^
behaves as though each file in the directory were
specified as a named file,
except that non-\*(S) files
(last component of the path name does not begin with
.BR s. )
and unreadable files
are silently ignored.
If a name of \fB\-\fR is given, the standard input is read;
each line of the standard input is taken to be the name of an \*(S) file
to be processed.
Again, non-\*(S) files and unreadable files are silently ignored.
.PP
The generated text is normally written into a file called the
.I g-file\^
whose name is derived from the \*(S) file name by simply
removing the leading
.BR s. ;
(see also \fI\s-1FILES\s+1\fP\^, below).
.PP
Each of the keyletter arguments is explained below
as though only one \*(S) file is to be processed,
but the effects of any keyletter argument applies independently to
each named file.
.TP "\w'\fB\-a\fIseq-no.\fR~~'u"
.BI \-r SID\^
The
.IR S "\s-1CCS\s+1 " ID entification
string (\*(I)) of the version (delta)
of an \*(S) file to be retrieved.
Table~1 below shows, for the most useful cases, what version
of an \*(S) file is retrieved (as well as the \*(I)
of the version to be eventually created by
.IR delta (1)
if the
.B \-e
keyletter is also used),
as a function of the \*(I) specified.
.TP
.BI \-c cutoff\^
\fICutoff\fR
date-time,
in the form:
.IP
	\s-1YY[MM[DD[HH[MM[SS]]]]]\s+1
.IP
No changes (deltas) to the \*(S) file which were created after
the specified \fIcutoff\fR date-time are included in the generated
\s-1ASCII\s+1 text file.
Units omitted from the date-time default
to their maximum possible values;
that is,
.B \-c7502
is equivalent to
.BR \-c750228235959 .
Any number of non-numeric characters may separate
the various 2 digit pieces of the \fIcutoff\fR date-time.
This feature allows one to specify a \fIcutoff\fR date in the form:
\&"\fB\-c77/2/2 9:22:25\fP".
Note that this implies that one may use the
%\&E% and %\&U% identification keywords
(see below)
for nested
.I gets\^
within,
say
the input to a
.IR send (1C)
command:
.tr ~~
.IP
	~!get  "\-c%\&E%  %\&U%"  s.file
.br
.tr ~
.TP
.B \-e
Indicates
that the
.I get\^
is for the purpose of editing or making a change
(delta) to the \*(S) file via a subsequent use of
.IR delta (1).
The
.B \-e
keyletter used in a
.I get\^
for a particular version (\*(I)) of the \*(S) file prevents
further
.I get\c\^
s for editing on the same \*(I) until
.I delta\^
is executed or the
.B j
(joint edit) flag is set in the \*(S) file
(see
.IR admin (1)).
Concurrent use of
.B "get \-e"
for different \*(I)s is always allowed.
.IP
If the
.I g-file\^
generated by
.I get\^
with an
.B \-e
keyletter is accidentally ruined in the process of editing it,
it may be regenerated by re-executing the
.I get\^
command with the
.B \-k
keyletter
in place of the \fB\-e\fP keyletter.
.IP
.SM SCCS
file protection specified via the
ceiling, floor, and authorized user list
stored in the \*(S) file
(see
.IR admin (1))
are enforced when the
.B \-e
keyletter is used.
.TP
.B \-b
Used
with the
.B \-e
keyletter to indicate that the new delta should have an \*(I) in a new branch
as shown in Table~1.
This keyletter is ignored if the
.B b
flag is not present in the file
(see
.IR admin (1))
or if the retrieved
.I delta\^
is not a leaf
.IR delta .
(A leaf
.I delta\^
is one that has no successors on
the \*(S) file tree.)
.br
Note: A branch
.I delta\^
may always be created from a non-leaf
.IR delta .
.TP
.BI \-i list\^
A
\fIlist\fR of deltas to be included
(forced to be applied)
in the creation of the generated file.
The \fIlist\fR has the following syntax:
.IP
	<list> ::= <range> \(or <list> , <range>
.br
	<range> ::= \*(I) \(or \*(I) \- \*(I)
.IP
\*(I), the \*(S) Identification of a delta, may
be in any form shown in the ``\*(I) Specified'' column of
Table~1.
Partial \*(I)s are interpreted as shown in the ``\*(I) Retrieved''
column of Table~1.
.TP
.BI \-x list\^
A
\fIlist\fR of deltas to be excluded
(forced not to be applied)
in the creation of the generated file.
See the
.B \-i
keyletter for the \fIlist\fR format.
.TP
.B \-k
Suppresses
replacement of identification keywords
(see below)
in the retrieved text
by their value.
The
.B \-k
keyletter
is implied by the
.B \-e
keyletter.
.TP
.BR \-l [ p ]
Causes
a delta
summary to be written into an
.IR l-file .
If
.B \-lp
is used
then an
.I l-file\^
is not created;
the delta summary is written on the standard output instead.
See \fI\s-1FILES\s+1\fP for the format of the
.IR l-file .
.TP
.B \-p
Causes
the text retrieved
from the \*(S) file to
be written on the standard output.
No
.I g-file\^
is created.
All output which normally goes to the standard output
goes to file descriptor 2 instead,
unless the
.B \-s
keyletter is used,
in which case it disappears.
.TP
.B \-s
Suppresses
all output normally written on the
standard output.
However,
fatal error messages (which always go to file descriptor
2) remain unaffected.
.TP
.B \-m
Causes
each text line retrieved from the \*(S) file
to be preceded by the
\*(I)
of the delta that inserted the text line in the \*(S) file.
The format is:
\*(I),
followed by a horizontal tab, followed by the text line.
.TP
.B \-n
Causes
each generated text line to be preceded with the
%\&M% identification keyword value
(see below).
The format is:
%\&M% value,
followed by a horizontal tab,
followed by the text line.
When both the
.B \-m
and
.B \-n
keyletters are used,
the format is:
%\&M% value,
followed by a horizontal tab,
followed by the
.B \-m
keyletter generated format.
.TP
.B \-g
Suppresses
the actual retrieval of text from the \*(S) file.
It is primarily used to generate an
.IR l-file ,
or to verify the existence of a particular \*(I).
.TP
.B \-t
Used
to access the most recently created
(``top'')
delta in a given release
(e.g.,
.BR \-r1 ),
or
release and level
(e.g.,
.BR \-r1.2 ).
.TP
.BI \-a "seq-no."
The
delta sequence number of the \*(S) file delta (version) to be retrieved
(see
.I sccsfile\c\^
(5)).
This keyletter is used by the
.IR comb (1)
command;
it is not a generally useful keyletter,
and users should not use it.
If both the
.B \-r
and
.B \-a
keyletters are specified,
the
.B \-a
keyletter is used.
Care should be taken when using the
.B \-a
keyletter in conjunction with the
.B \-e
keyletter,
as the \*(I) of the delta to be created
may not be what one expects.
The
.B \-r
keyletter can be used with the
.B \-a
and
.B \-e
keyletters to control the naming of the \*(I) of the delta to
be created.
.i0
.PP
For each file processed,
.I get\^
responds (on the standard output) with the
\*(I)
being accessed and
with the number of lines retrieved from the \*(S) file.
.PP
If the
.B \-e
keyletter is used, the
\*(I)
of the delta to be made appears
after the
\*(I)
accessed and before the number of lines generated.
If there is more than one named file
or if a directory or standard input is named,
each file name is printed
(preceded by a new-line)
before it is processed.
If the
.B \-i
keyletter is used included deltas are listed following the
notation ``Included'';
if the
.B \-x
keyletter is used, excluded deltas are listed following the
notation ``Excluded''.
.ne 10v
.PP
.in 0
.TS
center expand ;
c s s s s
c1 c1 c1 c1 c0
c c c c c
l c l l l .
TABLE 1. Determination of \s-1SCCS\s+1 Identification String
.sp 1.5p
=
\s-1SID\s+1*	\fB\-b\fP Keyletter	Other	\s-1SID\s+1	\s-1SID\s+1 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	\-	R < mR and	hR.mL**	hR.mL.(mB\^+1).1
\^	\^	R does \fInot\fP exist	\^	\^
_
R	\-	Trunk succ.#	R.mL	R.mL.(mB\^+1).1
\^	\^	in release > R	\^	\^
\^	\^	and R exists	\^	\^
.sp 1.5p
=
R.L	no	No trunk succ.	R.L	R.(L\^+1)
_
R.L	yes	No trunk succ.	R.L	R.L.(mB\^+1).1
_
R.L	\-	Trunk succ.	R.L	R.L.(mB\^+1).1
\^	\^	in release \(>= R	\^	\^
.sp 1.5p
=
R.L.B	no	No branch succ.	R.L.B.mS	R.L.B.(mS\^+1)
_
R.L.B	yes	No branch succ.	R.L.B.mS	R.L.(mB\^+1).1
.sp 1.5p
=
R.L.B.S	no	No branch succ.	R.L.B.S	R.L.B.(S\^+1)
_
R.L.B.S	yes	No branch succ.	R.L.B.S	R.L.(mB\^+1).1
_
R.L.B.S	\-	Branch succ.	R.L.B.S	R.L.(mB\^+1).1
.sp 1.5p
=
.TE
.in \n(INu
.PP
.PD 0
.TP "\w@***\ \ \ @u"
*
``R'', ``L'', ``B'', and ``S'' are the ``release'', ``level'',
``branch'', and ``sequence'' components of the \s-1SID\s+1, 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
.I new
branch (i.e., maximum branch number plus
one) of level L within release R''.
Note that if the \s-1SID\s+1 specified is of the form ``R.L'',
``R.L.B'', or ``R.L.B.S'', each of the
specified components
.I must
exist.
.TP
**
``hR'' is the highest
.I existing
release that is lower than
the specified,
.IR nonexistent ,
release\ R.
.TP
***
This is used to force creation of the
.I first
delta in a
.I new
release.
.TP
#
Successor.
.TP
\(dg
The
.B \-b
keyletter is effective only if the
.B b
flag (see
.IR admin\^ (1))
is present in the file.
An entry of \fB\-\fR means ``irrelevant''.
.TP
\(dd
This case applies if the
.B d
(default \s-1SID\s+1) flag is
.I not
present in the file.
If the
.B d
flag
.I is
present in the file, then the
\s-1SID\s+1 obtained from the
.B d
flag is interpreted as if it had been specified on the command line.
Thus, one of the other cases in this table applies.
.PD
.SH IDENTIFICATION KEYWORDS
Identifying information
is inserted into the text retrieved from the \*(S) file by replacing
.I "identification keywords\^"
with their value wherever they occur.
The following keywords may be used in the text stored in an \*(S) file:
.br
.ne 5v
.PP
.PD 0
.TP "\w'Keyword~~~'u"
.I Keyword
.I Value
.TP
.B %\&M%
Module name:
either the value of the
.B m
flag in the file
(see
.IR admin (1)),
or if absent,
the name of the \*(S) file with the
leading
.B s.
removed.
.TP
.B %\&I%
\*(S) identification (\*(I)) (%\&R%.%\&L%.%\&B%.%\&S%) of the retrieved text.
.TP
.B %\&R%
Release.
.TP
.B %\&L%
Level.
.TP
.B %\&B%
Branch.
.TP
.B %\&S%
Sequence.
.TP
.B %\&D%
Current date (\s-1YY/MM/DD\s+1).
.TP
.B %\&H%
Current date (\s-1MM/DD/YY\s+1).
.TP
.B %\&T%
Current time (\s-1HH:MM:SS\s+1).
.TP
.B %\&E%
Date newest applied delta was created (\s-1YY/MM/DD\s+1).
.TP
.B %\&G%
Date newest applied delta was created (\s-1MM/DD/YY\s+1).
.TP
.B %\&U%
Time newest applied delta was created (\s-1HH:MM:SS\s+1).
.TP
.B %\&Y%
Module type:
value of the
.B t
flag in the \*(S) file
(see
.IR admin (1)).
.TP
.B %\&F%
\*(S) file name.
.TP
.B %\&P%
Fully qualified \*(S) file name.
.TP
.B %\&Q%
The
value of the
.B q
flag in the file
(see
.IR admin (1)).
.TP
.B %\&C%
Current line number.
This keyword is intended for identifying messages
output by the program such as ``this shouldn't have happened'' type errors.
It is
.I not\^
intended to be used on every line to provide
sequence numbers.
.TP
.B %\&Z%
The 4-character string \fB@\&(#)\fR
recognizable by
.IR what (1).
.TP
.B %\&W%
A shorthand notation for constructing
.IR what (1)
strings
for the \s-1UNIX\s+1 System program files.
%\&W%~=~%\&Z%%\&M%<horizontal-tab>%\&I%
.TP
.B %\&A%
Another shorthand notation for constructing
.IR what (1)
strings
for non-\s-1UNIX\s+1 System program files.
%\&A%~=~%\&Z%%\&Y%~%\&M%~%\&I%%\&Z%
.PD
.SH FILES
Several auxiliary files may be created by
.IR get ,
These files are known generically as the
.IR g-file ,
.IR l-file ,
.IR p-file ,
and
.IR z-file .
The letter before the hyphen is called the tag.
An auxiliary file name is formed from the \*(S) file name:
the last component of
all \*(S) file names must be of the form \fBs.\fP\fImodule-name\fP,
the auxiliary files are named by replacing the leading \fBs\fR
with the tag.
The
.I g-file\^
is an exception to this scheme:
the
.I g-file\^
is named by removing
the
.B s.
prefix.
For example,
.BR s.xyz.c ,
the auxiliary file names would be
.BR xyz.c ,
.BR l.xyz.c ,
.BR p.xyz.c ,
and
.BR z.xyz.c ,
respectively.
.PP
The
.IR g-file ,
which contains the generated text,
is created
in the current directory
(unless the
.B \-p
keyletter is used).
A
.I g-file\^
is created in all cases, whether or not any lines of text
were generated by the
.IR get .
It is owned by the real user.
If the
.B \-k
keyletter is used or implied its mode is 644;
otherwise its mode is 444.
Only the real user need have
write permission in the current
directory.
.PP
The
.I l-file\^
contains
a table showing which deltas were applied
in generating the retrieved text.
The
.I l-file\^
is created
in the current directory
if the
.B \-l
keyletter is used;
its mode is 444 and it is owned by the real user.
Only the real user need have
write permission in the
current directory.
.PP
Lines in the
.I l-file\^
have the following format:
.PP
.PD 0
.RS
.nr a 0 1
.af a a
.TP
\n+a.
A blank character if the delta was applied;
.br
\fB\(**\fR otherwise.
.TP
\n+a.
A blank character if the delta was applied or wasn't applied and ignored;
.br
\fB\(**\fR if the delta wasn't applied and wasn't ignored.
.TP
\n+a.
A code indicating a ``special'' reason
why the delta was or was not applied:
.RS 10
``I'': Included.
.br
``X'': Excluded.
.br
``C'': Cut off (by a
.B \-c
keyletter).
.RE
.TP
\n+a.
Blank.
.TP
\n+a.
\*(S) identification (\*(I)).
.TP
\n+a.
Tab character.
.TP
\n+a.
Date and time (in the form
\s-1YY/MM/DD~HH:MM:SS\s+1)
of creation.
.TP
\n+a.
Blank.
.TP
\n+a.
Login name of person who created \fIdelta\fP.
.PD
.RE
.IP
The
comments and \*(M) data follow on subsequent lines,
indented one horizontal tab character.
A blank line terminates each entry.
.PP
The
.I p-file\^
is used to
pass information resulting from a
.I get\^
with an
.B \-e
keyletter along to
.IR delta .
Its contents are also used to prevent a subsequent
execution of
.I get\^
with an
.B \-e
keyletter
for the same \*(I) until
.I delta\^
is executed
or the joint edit flag,
.BR j ,
(see
.IR admin (1))
is set in the \*(S) file.
The
.I p-file\^
is created in the directory containing the \*(S) file
and the effective user must have
write permission
in that directory.
Its mode is 644 and it is owned by the effective user.
The format of the
.I p-file\^
is:
the gotten \*(I),
followed by a blank,
followed by the \*(I) that the new delta will have when it is made,
followed by a blank,
followed by the login name of the real user,
followed by a blank,
followed by the date-time
the
.I get\^
was executed,
followed by a blank and the
.B \-i
keyletter argument if it was present,
followed by a blank and the
.B \-x
keyletter argument if it was present,
followed by a new-line.
There can be an arbitrary number of lines in the
.I p-file\^
at any time;
no two lines can have the same new delta \*(I).
.PP
The
.I z-file\^
serves as a
.I lock-out\^
mechanism against simultaneous updates.
Its contents are
the binary (2 bytes) process \s-1ID\s+1 of the
command
(i.e.,
.I get\c\^
)
that created it.
The
.I z-file\^
is created in the directory containing the \*(S) file for the duration of 
.IR get .
The same protection restrictions as those for the
.I p-file\^
apply for the
.IR z-file .
The
.I z-file\^
is
created mode 444.
.SH "SEE ALSO"
admin(1),
delta(1),
help(1),
prs(1),
what(1),
sccsfile(4).
.br
.I "Source Code Control System"
in the
.IR "\s-1UNIX\s+1 System Support Tools Guide" .
.SH DIAGNOSTICS
Use
.IR help (1)
for explanations.
.SH BUGS
If the effective user has
write permission (either explicitly or implicitly) in the directory
containing the \*(S) files,
but the real user doesn't,
then only one file may be named when the
.B \-e
keyletter is used.
.tr ~~
.\"	@(#)get.1	5.2 of 5/18/82