This web page documents the the GNU cssc package for working with
SCCS files.
Copyright (C) 1997,1998,1999,2000,2001,2002,2003,2004 Free Software Foundation, Inc.
Permission is granted to make and distribute verbatim copies of this manual provided the copyright notice and this permission notice are preserved on all copies.
Permission is granted to copy and distribute modified versions of this manual under the conditions for verbatim copying, provided that the entire resulting derived work is distributed under the terms of a permission notice identical to this one.
Permission is granted to copy and distribute translations of this manual into another language, under the above conditions for modified versions, except that this permission notice may be stated in a translation approved by the Foundation.
The GNU CSSC program is designed to be a compatible replacement for the traditional Unix SCCS suite.
While it is strongly suggested that new projects not use this package, sometimes existing projects require the use of SCCS files. While conversion to other formats is possible, this is also sometimes impractical. See the documentation for CVS and RCS. See What is CVS?. See also the manual pages for RCS.
GNU CSSC is published under the GNU General Public License, which is designed to protect your rights, as the user of this program. You have the right to modify this program, and distribute it. You also have responsibilities to those to whom you distribute copies, as detailed in the license. See GNU General Public License.
GNU CSSC was originally based on the public-domain package MySC, which was written by Ross Ridge. The enhancement work was done by James Youngman.
The sccs program itself and its accompanying documentation
sccs.me and sccs.1 were written by Eric Allman, and are
covered by the BSD license (see BSD Code).
By far the easiest way to use CSSC (or indeed SCCS) is to use VC-mode in GNU Emacs. See Version Systems.
If you can't use VC-mode, the BSD command sccs is a good
interface to the SCCS suite (and hence CSSC).
Other than that, you will need to use each of the programs in the suite individually.
adminTo create an SCCS archive of a source file foo.c, do
admin -ifoo.c s.foo.c
This creates the archive file s.foo.c and initialises it
with the current contents of your source file, foo.c. If you use
Emacs as your editor, you can just use C-x v i instead.
Another frequently-used option is -b, which indicates that the
file is to be treated as a binary file rather than as text. You might
want to do this because the file actually contains binary data, or just
characters that have other meanings within an SCCS file, for
example ^A, the character whose code is 1.
-axxxget -e and delta). Users
must be specified by name and groups by numeric ID.
This feature is often used in conjunction with a setuid installation of
the sccs driver program (see sccs). This is not a good idea
because the CSSC suite is not secure (see Known Problems).
-b
-n or -i options.
This option is not available if binary file support is turned off
(see Interoperability) though this can be re-enabled if necessary
with an environment variable (see Environment).
-dF
-exxx-fF[xxx]
-fv/tmp/checkit sets the
MR-validation flag to /tmp/checkit.
-h
val. Some problems with the SCCS file may not be
diagnosed.
Warning messages may be emitted, indicating things that may or may not be wrong (e.g. time apparently going backwards), but if no actual errors are encountered, the exit value will still be zero.
This option is silently incompatible with all the other options; the
specified SCCS files will not be modified by admin if the
-h flag is used.
-ifoo-n option.
-mMR-list-m option causes delta to
fail.
-n
-i is also used, the new
file will contain control information but the body will be initially
empty. Some versions of SCCS require the -i option to
be specified if -n is used. Therefore for greatest
portability, specify -i/dev/null if you want an empty initial
body. Interoperability.
-rN1.2 or
1.8.2.1). CSSC also allows this, but emits a warning. If
you use the -r option, you must also use the -i
option (not just the -n option). If the initial SID you
specify is not on the trunk, some tools will fail to work with the
resulting file. See also See SCCS Version Differences.
-tdesc-i or -n is used).
-V
-yadayada-y, the
comment is recorded as empty. The following word in the argument list
is not used as the comment. Note that this behaviour is different
to most Unix programs, but is the same as the behaviour of traditional
SCCS.
-z
Flags are set and cleared with the admin program. See admin.
b
-b option of get
(see get).
e
-b option of admin at
the time the file is created (or if admin takes it upon itself to set
this flag automatically), and cannot be unset. The circumstances under
which this can happen are discussed in Interoperability.
f
i
get and delta exit unsuccessfully when the
Warning: No id keywords message is issued.
j
j flag overrides this.
n
-r option to get is used to
skip releases. These empty releases can later serve as branch
points.
x
admin -fx generates a warning to this
effect. If CSSC is simply processing a file which already has
this flag set, no message will be generated. See
Interoperability for more information on compatibility between
CSSC and other implementations of SCCS.
c
f
d
get command is given
without the -r option. The default behaviour for get is
defined in get.
l
get -e. The special value a denotes all releases.
q
%Q% keyword as described in
Keyword Substitution. This flag is referred to in the output of
SCCS as csect name, and is variously referred to here as
that, or the "user flag" or the "Q flag".
m
%M% keyword as described in
Keyword Substitution.
t
%Y% keyword as described in Keyword Substitution.
v
y
admin -fyQ,M,Y restricts keyword expansion so that
%Q%, %M% and %Y% are expanded, while other
keywords such as %Z% are not.
This flag is an extension introduced by Sun Solaris 8. See
Interoperability for a discussion of the interoperability of
CSSC with other SCCS implementations.
MRs are identifiers that can be specified when checking in a
revision using delta (or even using admin, when creating a
file).
If the v ("validate") flag is set, the user running
delta is prompted for MR numbers as well as revision
comments. If this flag is not set, no validation is performed and no
MR numbers are prompted for. If the -m option is given on
the command line for delta, the user is not prompted.
MR numbers are not required by CSSC to be actual numbers; they may contain any non-whitespace printable characters; other implementations may not be so flexible.
MR numbers are frequently used to tie code revisions to other things, for example engineering change management documents or bug-tracking databases. If your change management systems are computer-based, you can use the validation program to ensure that the offered MR number is valid and that the calling user is allowed to change the file.
The first argument passed to the validation program is the name of the g-file and the following arguments are the MR numbers offered. The validating program should return zero if all the MR numbers are acceptable.
One might think that it would be useful to associate the MR number
with the action of checking out for a modification (get -e), but
this is not possible with SCCS. If you want to do that kind of
thing, you must use a more advanced system, for example GNU CVS.
cdcThe cdc command allows you to add comments to the commentary for
a particular delta in an SCCS file. Any delta in the file (other
than ones removed with rmdel) can be modified.
If a comment is not specified on the command line, comments are accepted via standard input.
If the special argument name - is being used, this means that a
list of files to operate on is being read from standard input, and
therefore the -y option is mandatory in this case.
The new comments are prepended to the existing comment for that delta,
followed by a line of the form *** CHANGED *** yy/mm/dd hh:mm:ss
who. This is followed by the original comment. Comments cannot be
removed using cdc, but they can be added.
Only three options are supported:-
-mMR-list!), then the
indicated delta is removed from the existing list of MRs for the
delta. The file comment is modified to indicate what MRs have been
removed. If an MR to be removed is in fact not present in any
case, this is silently ignored. and the comment is not updated for that
MR. If you do not also want to add to the comment for the delta,
specify an empty comment option (that, is, a bare -y).
-rSIDrmdel.
-yCommentcdc. An empty -y
option can be used to indicate that the commentary for this delta is not
to be modified (this is only useful when the -m option is used).
If the -y option is not given, the user is prompted for comments.
combThis program is not yet implemented or documented in the manual, there are no tests for it in the test suite yet, but it is part of SCCS so it will eventually be implemented.
deltaThe delta command is used to add a new revision to the ones
already stored in an SCCS file. Before being able to do this you
need to run get -e to check the file out for editing.
A new revision is created by the delta program. These revisions
are each identified by a unique SID. A SID looks like
1.2.3.4, where the four numbers are the release,
level, branch and sequence numbers.
New revisions on the main sequence (the trunk) have no branch or
sequence numbers and so just have two number components (1.2, for
example).
When a new version is checked in, delta usually prompts for
comments describing the changes just made. At this point you can enter
any comments, separating lines with backslash-newline pairs. An
unescaped newline terminates the comment, allowing operation to
continue.
Sometimes, running delta results in the creation of a branch in
the SCCS file; this is controlled by the get command at the
time the file is checked out for editing (see branches).
The delta program checks to see if you are authorised to check
in a delta to this file. The list of authorised users can be
maintained with the admin program (see admin). If the
MR-validation flag (see Flags) is set, you must also supply a
valid MR-number in order to be able to check in your change.
deltaAlthough there are several valid command-line options for delta,
they are not frequently used; the most common usage of delta is
delta SCCS/s.umsp.c
and this command simply applies the changes to the file umsp.c to
the SCCS file which tracks it. Though it is possible to specify
the comment and MR-number for this change using command-line options,
it's more common to type them when prompted, unless delta is
being driven by another program; either way, it's unusual to specify
options for delta on the command line.
Note that the filename you specify on the command line is that of the
SCCS file, not the filename of the working file. The BSD wrapper
program, sccs(1), will guess the correct filename for you, but this
doesn't happen unless you do actually invoke it (sccs delta
umsp.c for example).
delta-gsid-Listget. The list is a list of
SIDs separated by commas, or can contain ranges of SIDs (these
are indicated by a dash). Untested.
-mmr-listdelta will prompt for MR numbers if none
are given on the command line. If the v flag has a non-empty
value, as opposed to just being set, then the supplied list of MR
numbers will be verified using that program. The requested delta will
not be made if this validation fails (the validation program returns a
nonzero exit status).
When the v flag is set, deltas must be checked in using
this flag. If you are using Emacs's vc-mode, you can do this by setting
the variable vc-checkin-flags to "-m2677" if the MR
with which you are working is numbered 2677, for example.
-n
get
command.
-p
diff is echoed on the standard
output.
-r
-r command-line option is
used to specify which checked-out version this change is in reference
to. When get is used to check out a version for editing, it
announces two SIDs:-
3.1
new delta 3.2
402 lines
One identifies the version forming the basis of the change, and the
other specifies the SID that the new version will be assigned once
it is checked in again. Either of these two SIDs (in this case,
3.1 or 3.2) can be used for the -r option of delta.
-s
-y
-y. If this option is not given
on the command line, delta will prompt the user for a comment.
getThe get command is to retrieve previous revisions from an
SCCS file. With the -e option, it also locks the gotten
revision so that a modified version can be checked in later using
delta.
getget. Below,
s.foo.c denotes the name of any existing SCCS file.
get s.foo.c
s.foo.c into the
file foo.c.
get -Gbar s.foo.c
s.foo.c, into bar rather than the
default foo.c. The file produced by get is often referred
to as the "g-file".
get -r1.3 s.foo.c
s.foo.c into foo.c. The -G
option can be used to set the name of the gotten file.
get -p s.foo.c
-r option could also be used to specify some other revision.
Unless you specify the -k or -e option, the retrieved file
will be created read-only.
get-aN-b
-e option. If the -e option is not given, or if
the b (branch) flag is not set in the SCCS file, this option
has no effect; a branch is not made. If the version to be checked out
for editing has a successor, a branch is created whether or not the
-b flag is present (see branches).
-cwhen-c92, you get the latest version which was available
in the year 1992. It is possible to give four digits for the year as a
CSSC-specific extension, but only if none of the other fields are
omitted. If only two digits are used and the resulting value is less
than 69, the year is assumed to be in the twenty-first century
(see prs options and Year 2000 Issues).
-D
-e
j flag is set (see Flags), get -e will
fail if someone else already has the file locked. If the list of
authorised users in the SCCS file is not empty, you must be in
that list in order to use this option.
-g
-Gfoo-ilist-x.
-k
-e is specified. The gotten file is writable.
-l
-lp
-m
delta which introduced this line to the file.
-n
-m option.
-p
-rX-s
-t
get is to get the highest revision on the trunk. The
-t option only modifies this behaviour in the situation where the
topmost trunk revision is a branch point. In this case, the -t
option causes the topmost revision on this branch to be retrieved. In
other words, the -t option removes the restriction that the
retrieved version should be on the trunk. This option is used by
comb (see comb) and by the driver program sccs from
BSD (see sccs).
-V
-wXXX%Z%%M% <TAB> %I% as the substitution
value for %W%.
-xlistNormally, editing revision 1.1 of a file produces revision 1.2. Editing that produces revision 1.3, and so on. Sometimes, however, we need to make a change to an earlier version which has already been superseded.
This might happen, for example, when a bug has been reported in a released version of a file; a rapid bug-fix is required, but you're in the middle of working towards a new release. A viable strategy is to make a branch at the previously-released version, modify that to fix the bug (and release this bug-fix). Meanwhile, development can be continued along the "main trunk", and the same bug-fix can be incorporated in this, ready for the next release later on.
When you check out a version of a file for editing, CSSC tells you
what the SID of the new version will be. For normal progress along
the trunk, the level number is incremented. This is the second
numeric element of the SID. In general, a SID is composed of
four numbers R.L.B.S, where "R" stands for "Release", "L"
stands for "Level", "B" stands for "Branch", and "S" stands for
"Sequence number" (not the same as the sequence numbers produced in
the output of prt).
Trunk revisions have only two components; you can think of the branch and sequence numbers as being zero. Non-trunk revisions have four components. When a branch is created from an existing SID, the release and level numbers are copied, the branch number is set to the lowest unused value for that release and level, and the sequence number is set to one. Hence the first branch from version 1.1 will be version 1.1.1.1, and if a branch is made from that, its SID will be 1.1.2.1.
Branches are made from any given version when that version already has a
successor. For example, a get -e on version 1.1 will result in a
branch (1.1.1.1) if version 1.2 exists, and a get -e on version
1.2.1.1 will result in a branch (1.2.2.1) if version 1.2.1.2 exists.
If the "enable branches" flag is set, it is also possible to make
branches for revisions that do not have successors. This is done with
the -b flag of get.
Keyword substitution is performed unless the -k option or the
-e option is given to get.
what contains a keyword substitution example.
The keywords are all of the form %x% where x stands for
an upper-case letter, one of:
%Z% %Y% %M% %I% %Z%.
s.foo.c.
m (module) flag, or the base name
of the SCCS file with the s. removed if the module flag is
unset.
q flag. The q flag has no other purpose, and
can be set with admin -fqfoo-w
flag, if given.
t (module type) flag.
@(#). See what.
Some of the keywords listed above have expansions that are described
in terms of the contents of other keywords. This expansion is
performed as if the y flag in the SCCS file is not set.
For example, admin -fyA will cause the %I% keyword not
to be expanded, but the %A% keyword is still fully expanded,
even though it is defined in terms of %I%.
This section describes how included, excluded and ignored deltas are handled by CSSC. Little documentation is available on how SCCS handles this, and so while this section describes how CSSC works, it may in fact not be an accurate description of how CSSC should work.
If you spot a defect in this section (or of course any other section) of the CSSC manual, please report this as a bug (see Problems).
The usual case is where none of the deltas in the SCCS file has any included, excluded or ignored deltas. All the lines in the body of the SCCS file are there because they were first inserted by a particular delta. All of these lines are copied through to the gotten file, unless they are deleted by a later delta. For example if an SCCS file contains deltas 1.1 and 1.2, then all the lines from delta 1.2 will be included, and all the lines from delta 1.1 which are not deteled in version 1.2 are also included.
Normally the contents of the gotten delta is included in the output, along with all the non-deleted lines of its ancestors. However, a delta can also specify that some other delta should be included. This really only makes a difference when there is a branch in the file.
For example, if delta 1.5 includes 1.3.1.5, then the gotten file will include the contents of versions 1.1 through to 1.5, plus the contents of the 1.3.1 branch up to and including 1.3.1.5. Lines which were (say) added in 1.2 but delted in 1.3.1.1 will not appear in the output, since we have included a delta that deletes them.
Excluding a delta is, unsurprisingly, more or less the opposite of including one. The exclusion of a delta supercedes the inclusion of a delta. One might specify, for example, that delta 1.6 should exclude delta 1.5 (for example to back out of any changes it made). Exclusion can also be used to reverse the effect of an inclusion. Suppose that delta 1.6 in the example from the section above excludes 1.3.1.5, then 1.6 will include the contents of deltas 1.1 through to 1.4, plus the contents of delta 1.5 itself, but it will not include the data from the 1.3.1 branch that would have been used if we had gotten delta 1.5.
Ignored deltas are "silent"; that is, lines which are added by a delta which is (explicitly or implcitly) included will not appear in the gotten file. Conversely, lines deleted by an ignored delta will still appear in the gotten file.
helpThis module is not implemented, and it probably will never be, because
it exists to translate the sometimes obscure error messages produced by
(genuine) SCCS. These messages come with identifying codes (like
"(ge4)"); one might type help ge4 to translate an obscure
message into a more readable message detailing what has gone wrong. The
problem with this approach is that it results in a program called
help on the user's path. When a naive user types help they
are probably not looking for an explanation of an obscure message from
SCCS. In fact, help is in any case a shell builtin for GNU
Bash. Explanations of any obscure or unusual error messages belong in
this manual, and so no sccs-help program is provided or planned.
prsThe prs command (mnemonic: "print revision summary") prints
information about an SCCS file in a user-defined format. There are
options for selecting which deltas are reported on; selection is
possible by check-in time or by SID. The format of the output can
also be specified on the command line. All parts of an SCCS file
can be dumped with prs. Those parts which appear once per delta
can be uniquely identified by SID or by time.
Typical uses for prs are
get -m command is also useful for
this, see Options for get.
prsHere are some examples of the use of prs, with explanations of what they do.
prs s.myfile.c
myfile.c.
prs SCCS
SCCS.
prs -e -d:P: s.main.c | sort -u
prs -l -c`date +%y%m%d --date "last week"` SCCS
SCCS. Show any deltas
that have been created since last week.
prs-a
-c[cc]YYMMDDHHMMSSprs is the last one checked in before the
cutoff. As usual, any fields left unspecified in the cutoff are given
the maximum legal value (for example, the seconds field defaults to 59).
The fields can be separated by any non-numeric character, for example
-c97/11/02-11:25:42.
As an extension specific to CSSC, if the argument contains more
than twelve (12) digits, and the first four characters are all digits,
it is assumed that a four-digit year form has been used. This means
that you can say -c1997/11/02-11:25:42 to mean the same as the
above.
In line with the X/Open CAE Specification, Commands and Utilities (version 2, September 1994, pages 588 and 361), if the century field is not given and the year is less than 69, it is assumed to be a year in the twenty-first century. The X/Open document does not mandate a four-digit year specifier, but it would not make sense to apply this rule if a four-digit year is specified. See Year 2000 Issues.
This behaviour is usually not the one required, and hence the -e
or -l options are specified too.
-dformatIf one specifies the -d option, prs by default only gives
information about the latest delta. To restore the default behavior of
showing all the deltas, use the -e option as well.
-e
-c option select deltas created at or earlier than the
specified time. Makes the -r option select deltas before and
including the one specified by the indicated SID.
-l
-e option, but select only later deltas rather than
earlier ones.
-rSID-d option of prsThese keywords expand to the same thing, no matter which version is being examined. Many of these are SCCS file flags (see Flags).
:BD:
-b option of prt (see prt options).
:BF:
yes or no) of the branch flag.
:CB:
:Ds:
:F:
:FB:
:FD:
:FL:
:J:
yes or no) of the joint-edit flag.
:KF:
yes or no) of the keyword-warning flag (see admin).
:LK:
:M:
m flag).
:MF:
yes or no) of the MR validation flag
(see delta).
:MP:
:ND:
n) flag (yes or no).
:Q:
:PN:
:UN:
-a and
-e of admin; if this list is empty, any user is
allowed to use delta on this file (subject to the usual file
permissions checks made by the operating system). However, in this
case the UN data keyword somewhat curiously expands to
none.
:Y:
The :BD:, :FD:, :FL: and :UN: keywords from
this section may expand to strings containing newlines.
These keywords expand to data that is specific to a particular version.
:A:
:Z::Y: :M: :I::Z:, useful for what.
:B:
:C:
:D:
:Dy:/:Dm:/:Dd:. The year is always represented as two digits but
is not ambiguous since the two-digit year is no later than 2068
(see Year 2000 Issues).
:Dd:
:Dg:
:DI:
:Dn:/:Dx:/:Dg: (sequence numbers
included/excluded/ignored).
:DL:
:Li:/:Ld:/:Lu: (lines inserted/deleted/unchanged).
:Dm:
:Dn:
:DP:
:DS:
:Dt:
:DT: :I: :D: :T: :P: :DS: :DP:.
:DT:
R (removed) or D (normal).
:Dx:
:Dy:
:GB:
:BD:. Keyword expansion will be performed
in the same way as if get had been used.
:I:
:L:
:Ld:
:Li:
:Lu:
:MR:
:P:
:R:
:S:
:T:
:Th:::Tm:::Ts:).
:Th:
:T:).
:Tm:
:T:).
:Ts:
:T:).
:W:
:Z::M:<TAB>:I:, suitable for what
(see what).
:Z:
@(#) (see what).
The :C:, :GB: and :MR: keywords from this section
may expand to strings containing newlines.
prtThe prt command provides information about an SCCS file
without modifying it. There are many options, though the default
behaviour is usually appropriate. It is possible to select what
revisions to print information on, by SID or by date.
Some SCCS implementations lack the prt command, though
none lack the prs command (see prs) which is otherwise
quite similar.
prtThe output provided by prt when no options are given is
sufficient most of the time, and so it's common to use it without any
options:-
prt s.umsp.c
If you require more detail, the -e ("everything") option
produces more detail:-
prt -e s.umsp.c
As usual, any argument that is the name of a directory causes all
SCCS files in that directory to be processed; the special argument
- indicates that a list of SCCS files are to be read from
prt's standard input.
prt-a
rmdel has been used to remove
a delta.
-b
^A (Control-A, ASCII code 1) which
starts some lines of an SCCS file is printed as three asterisks,
***. Lines that do not start with the control character are
indented by one tab stop. For encoded (binary) files, the encoded form
of the file data is printed (this is what actually appears in the
SCCS file itself). If you want to extract the actual body of the
SCCS file, use the :BD: keyword of prs (see Data Keywords.
-d
-b, -f, -t and -u flags, but
specifying -d on the command line again will ensure that the
delta information is printed.
-e
-i -u -f -t -d.
-c[cc]YYMMDDHHMMSSprt stops printing delta information when it reaches a SID
at least as old as the cutoff. As usual, any fields left unspecified in
the cutoff are given the maximum legal value (for example, the seconds
field defaults to 59). The fields can be separated by any non-numeric
character, for example -c97/11/02-11:25:42.
As an extension specific to CSSC, if the argument contains more
than twelve (12) digits, and the first four characters are all digits,
it is assumed that a four-digit year form has been used. This means
that you can say -c1997/11/02-11:25:42 to mean the same as the
above.
In line with the X/Open CAE Specification, Commands and Utilities (version 2, September 1994, pages 588 and 361), if the century field is not given and the year is less than 69, it is assumed to be a year in the twenty-first century. The X/Open document does not mandate a four-digit year specifier, but it would not make sense to apply this rule if a four-digit year is specified. See Year 2000 Issues.
The -c and -r options are mutually exclusive.
-f
-i
-r[cc]YYMMDDHHMMSS-c option, but with the opposite
sense; that is, nothing is printed for deltas that are more recent than
the indicated time.
The -c and -r options are mutually exclusive.
-s
-t
admin
-t (see admin).
-u
-ySID-y, the most recent delta is selected. The oder in which delta
information is stored within the SCCS file is such that the
SID selected by this option will be the last one printed.
If the -y option is used in conjunction with either the -c
or the -Y option, processing stops when either condition (date or
SID match) is satisfied.
prt output formatThe output format is fixed, though parts of the output can be omitted.
-d, -e, also the default,
but not if -b, -f, -t, -u are specified).
This section is printed once for each selected delta.
This begins with a newline as a separator (except when a cutoff is being used, in which case the SCCS file name is used, followed by a colon and a TAB character).
inserted/deleted/unchanged. These
statistics are capped at 99999, due to a limitation in the file
format.
-s option has been specified.
everyone is printed)
-t option of admin).
^A that begins some lines is
printed as *** , and other lines are printed indented
by one tab stop. Other than that, the body is printed as found
in the SCCS file. This means that binary files are left
encoded.
rmdelThe rmdel ("Remove Delta") command allows the last version last
checked in to an SCCS file to be removed again. Typically, one
does this after realizing that newly checked in version doesn't compile,
or doesn't work, and the fix is simple. In the author's opinion, it's
almost always better to be honest about mistakes, and just make a new
delta for the fixed version.
The SID of a removed delta is soon re-used by delta, usually
for the fixed version.
The rmdel command takes only one option, -r, which
specifies the SID of the version to be removed. This option is
mandatory.
The rmdel command will fail if you hadn't checked in that
revision, or if it is in use in some way. For example, rmdel
fails if the specified SID is not the latest revision on its
branch, or if it has been checked out for editing.
As usual, any number of SCCS files can be named on the command
line. The special argument - indicates that the list of files to
be operated on should be read from standard input. If an argument is a
directory, the RMDEL command is applied to all SCCS files in
that directory.
sactThe sact ("Show Editing Activity") command provides
a summary of which files are currently checked out for editing.
For each checked-out file, a summary line is given. This line is of
the form old-SID new-SID user date time.
old-SID
new-SID
delta when the
working file is checked in again.
user
date time
No output is produced for SCCS files that are not currently locked
for editing. If a directory is specified on the command line, the whole
directory is examined. Directory hierarchies are not descended beyond
this one level. If - is given as an argument, filenames are read
from standard input.
Note that times in SCCS files (and lock-files) are stored as local time, so if you are collaborating with developers in another time zone, the date shown will be in their local time for files that they are editing.
sccsThe sccs utility is available with CSSC. The code has
been adapted to support GNU Autoconf, but it should function in the same
way. The only difference between the operation of the original BSD
sccs program and that of the one provided by CSSC is that
way that the called programs are searched for. While the original
program has the paths hard-coded in as /usr/sccs/*, the version
accompanying CSSC first searches for them on the PATH, and then
falls back on /usr/sccs/*. If the executable is running
set-user-id, the PATH environment variable is ignored. The
sccs program itself should be fairly secure, but the other
programs in the suite are not. See Known Problems, for more
information.
The sccs program is documented in its online manual page, and
also in An Introduction to the Source Code Control System by Eric
Allman, a copy of which is included with this suite.
Unlike all the other parts of the suite, the sccs program and its
accompanying documentation are covered by the BSD copyright license; see
BSD Code, and the file COPYING.bsd, for more information.
The original BSD version of the sccs program can easily be found
on BSD mirrors, for example ftp://ftp.freebsd.org/.
sccsdiffThe sccsdiff command compares two revisions stored in an
SCCS file, using the system utility diff. Options can be
passed on to diff, for example to set the output format. As with
the other utilities in the suite, sccsdiff will operate on a list
of s-files, but unlike most of the others, it will not process
directories named on the command line.
If you wish to compare the working copy of a file with a version stored
in the s-file, you should use the command sccs diffs
(see sccs).
The options for sccsdiff are described below.
--help
--version
sccsdiff program.
-p
-rSID
All other options not appearing above are passed on to the diff
program. All the non-option arguments will be processed in turn as
SCCS files.
ungetThe unget command is used to reverse the effect of get
-e. Typically you might do this when you embark on an edit of a
file, and it all goes horribly wrong. Using unget allows you to
revert to a previously-known state. In fact, if you have exercised some
care in checking in new revisions, perhaps using a test suite, then
unget can be used to return you to the last working version.
unget-n
-s
-rsidvalThe val command is used to validate a (possibly suspect)
SCCS file. If an SCCS command reports that the checksum of
an SCCS file is incorrect, this may mean that the file has been
corrupted. In this case, val may help to confirm this
(but see Why val doesn't solve the whole problem).
Example usages:-
val s.foo
val -mfoo s.foo
val -r1.2 s.foo
val s.foo s.bar SCCS/s.*
val /proj/python/spam/spam/eggs/spam
val-mname-s
-V
-rwanted-ytypeSome possible problems with SCCS files are not definitively
errors. In these situations, val will emit a warning message
but the validation will not fail (that is, if there are no other
problems the return value will be zero). An explanation of the
possible warnings appears below.
Some versions of SCCS, but not CSSC exhibit a peculiar
behaviour in these circumstances, and do not include in the gotten
file any lines apparently inserted after the date of the delta which
has been selected. This applies to get but more importantly
also applies to the temporary file generated by DELTA which is
compared with the working copy of tyhe file. Once this has happened
there is no way to recover from this problem other than to hand-edit
the SCCS file.
y flag of the SCCS file
is set to a value which includes a keyword letter which is not known.
This is harmless unless you intended to set the flag to some other value.
Flags.
The value returned by the val program depends on the outcome of
the validation as follows :-
-m option was used but the module name did not match.
-y option was used but the module type did not match.
-r option was used but the specified SID was ambiguous, or
not present in the history file.
-r option was used but the specified SID was invalid.
Things that paranoid people might bear in mind are
val concludes that a history file is structurally valid,
this does not mean that the file contains what you thought it did (for
example, perhaps the file was corrupted by having another, valid,
SCCS file copied over it, or perhaps it was overwritten by an old
backup version).
Things that an optimistic person might bear in mind are
val does are very small indeed.
val performs are done anyway (CSSC differs slightly in this
respect from the traditional SCCS toolset).
The summary is that it is theoretically possible to fool the integrity
checks performed by the SCCS file checksum and by val but
the checksum isn't fooled often and the chances of fooling both
together are very small. The use of quality hardware reduces the
chance of data corruption yet further.
whatThe what program is designed to search in files for the
recognition string @(#). All the strings it finds matching this
are printed on standard output.
The exit status of what if zero is a matching string as found,
and 1 otherwise.
whatwhat [-s] [-V] file [file ...]
-s
-V
what.
While the file is being edited (either at first or after get -e):-
#ifndef CONFIG_NO_SCCS_IDS
static const char sccs_id[] = "%W%";
#endif
When the file is checked out for compiling (with get):-
#ifndef CONFIG_NO_SCCS_IDS
static const char sccs_id[] = "@(#)foo.c 1.3";
#endif
After compiling:-
$ what foo
foo:
foo.c 1.3
If the executable is linked from several source files, you will get a
line of output for each string containing the identification string
@(#). This is useful for finding out exactly what code went into
an executable. This technique also works on object files, archive
libraries, text files, and in fact any sorts of files at all.
Unlike the strings command, there is no way to make what
operate on standard input. The data would need to be written to a file
first.
The rationale for the preprocessor construct CONFIG_NO_SCCS_IDS
is that sometimes compilers or lint-pickers complain that the variable
sccs_id is unused, and defining CONFIG_NO_SCCS_IDS will
remove these IDs and thus silence the warnings.
Temporary files are used during normal operation of CSSC (and SCCS). Many of these are given fixed names. The prefixes for the various files used by CSSC are listed in the table below.
s.
p.
z.
x.
q.
d.
diff in this file instead.
u.
All of the temporary files in the above table are created in the same directory as the s-file, rather than in the current working directory.
Since these filenames are always fixed, it is important that the permissions on the directory containing the SCCS file be secure; otherwise you have a security vulnerability where a malicious user can cause you to accidentally over-write files you own or have access to, but they do not. If you are the super-user, they can use this feature to overwrite any file on the system.
This chapter provides a description of the format of SCCS files. It is not authoritative, and may not match some of the peculiarities of your vendor's implementation.
An SCCS file contains two parts, the header and the body. The header contains information about both the file as a whole and also information about each version stored in the file. After this comes the body itself, which is a stream of fragments from the controlled file interspersed with control information which indicates which versions these fragments appear in.
Most of the control information for SCCS files appears on lines
which are marked as special by the character whose value is 1 (ASCII
SOH); this is usually referred to as ^A. Lines in SCCS
files always end with a line feed (ASCII LF) rather than a carriage
return (ASCII CR) followed by a line feed.
There are several parts to the SCCS file header:-
The first line of an SCCS file contains the checksum, preceded by
^Ah. The checksum is in decimal and is generated by adding
together the values of all the characters in the file, and taking the
result modulo 65536. A checksum line might look like this:-
^Ah36650
On systems whose C implementation considers the char type to be
unsigned, characters with their highest bit set appear to be considered
positive, and on machines with a signed char type, these
characters appear to be considered negative. This seems to mean that
these two types of machines will not agree on the correctness of an
SCCS file's checksum.
The BitKeeper suite uses ^AH to introduce its checksum
line rather than ^Ah, but the checksum is computed in the same
way.
The checksum is followed by the delta table. Each entry describes one version stored in the history file, and is composed of three lines plus some comment lines. The first line introduces a new delta table entry and has the form
^As 00001/00000/00010
The three numbers represent the numbers of lines inserted, deleted and unchanged in this version (with respect to its predecessor). For the oldest version in the history file, the numbers of lines deleted and unchanged should be zero and the number of lines inserted is the number of lines in the initial version of the working file. These numbers are always five digits long. If the true count of inserted, deleted or unchanged lines is greater than 99999, then the fields will still only contain 99999.
The second line has the form
^AD 1.5 68/12/31 23:59:59 james 5 4
Here, the D indicates that this is a normal delta. The only
other type of delta is the removed delta. Removed deltas are created
with the rmdel program and are labelled with an R instead
of a D. This is followed by the SID, which will have either
two or four fields separated by a decimal point (ASCII code 46 decimal).
A SID with only two fields (release and level) is said to be on the
trunk of the revision tree. A SID with the full four fields (the
last two are the branch number and the sequence number) is said to be a
"branch revision". Each field in the SID, if present, must
contain a positive integer no larger than 9999. This means that
1.0 would not be a valid version number, for example.
The third and fourth fields on this line are the date and time at which this delta was added to the history file (rather than, for example, the modification time of the working file which was checked in). The year is represented with only two digits, and is deemed to be in the range 1969 to 2068 (see Year 2000 Issues). Despite having only two year digits, the date is in ISO order (year/month/day). The time is indicated using 24-hour clock notation. The date in the above example is the latest date it is possible to represent in an SCCS file.
The fifth field is the name of the user who checked this version in. For the gratification of pedants, it should be noted that this is the name associated with the actual user-id rather than the effective user-id, or the name appearing in the system log as the user who logged in on the controlling terminal.
The final two fields are called delta sequence numbers, or
seqnos. They are for the internal use of the implementation and
should not be confused with "sequence numbers", which are the final
fields of four-field ("branch") SIDS. The seqno of the delta
added last will be larger than that of any other delta. Each delta has
a unique seqno. The first of these two fields is the seqno of this
delta itself, and the second field is the seqno of its predecessor (that
is, the version which had been checked out with get -e). The
seqno 0 is special and appears only as the (nonexistent) predecessor of
the first delta.
Since the delta table entries appear in reverse order of addition (i.e. new entries are always added at the top), the initial delta appears at the foot of the delta table. Many of the SCCS utilities define their cutoffs in such a way that they can stop traversing the delta table when they find a delta which is too old.
After the ^Ad line there may be several lines which indicate
lists of included, excluded or ignored sequence numbers for this delta.
I don't understand this area of the functionality of SCCS very
well, so any description here may be vague or incorrect. The CSSC
implementation may also be incomplete in this area.
The list of included seqnos is introduced with ^Ai, the
excluded seqnos with ^Ax, and ignored seqnos with ^Ag.
These are followed by a space character, and then the list itself, which
is a space-separated list of integers.
If the MR-validation flag (see Flags) was turned on at the time of the creation of this delta, one or more lines of the form
^Am mr1
^Am mr2
^Am mr3
^Am mr4
may occur. These lines constitute a list of Modification Request Numbers, one on each line.
The next part of the delta table entry is the the delta commentary.
This comment is intended to contain a description of the changes made in
this delta, and is written and read by humans. This may extend over one
or many lines, each introduced with ^Ac, like this:-
^Ac The end of the world
^Ac as we know it
If there is no comment for a particular delta, because it was suppressed
with the -y option to delta or cdc, or because the
user was presented with a prompt for comments but just typed the return
key, an empty ^Ac control line will appear at this point.
CSSC is currently slightly incorrect in this area. If the comment is
suppressed with the -y option, it emits no ^Ac lines at
all.
The BitKeeper suite uses comment lines of the form ^AcX
(where X is a non-blank character) to store data which is
specific to BitKeeper. This data is ignored by CSSC, which
provides read-only support for BitKeeper files. These special lines
are distinguished from normal comment lines by the fact that there is
no space after the c:-
^AcHathlon.transmeta.com
^AcK09043
^AcParch/arm/boot/Makefile
^AcRe1f91d8bfa21c521
^AcV4
^AcX0x821
^AcZ-08:00
Some SCCS files contain an MR list which follows rather than precedes the comments for a delta, but this is unusual.
The comment block, and in fact the whole delta table entry, is terminated by a control line of the form
^Ae
To illustrate this further, here are two more delta table entries from an SCCS file:-
^As 00001/00000/00007
^Ad D 1.2 99/12/31 23:59:59 mcvoy 2 1
^Ac Added an extra line
^Ae
^As 00007/00000/00000
^Ad D 1.1 69/01/01 00:00:00 dmr 1 0
^Ac created at the dawn of time
^Ae
Next, there is the list of authorised users, introduced by a ^Au
line. Only users in the authorised users list can modify the SCCS
file. This list always appears (though many implementations will not
complain if you remove it with an editor) but is often empty. One user
login name appears on each line. Lines can alternatively contain
numbers, denoting whole groups of users (as listed in /etc/group
on many systems). The authorised-users list is terminated with a
^AU line. Some broken implementations emit lines of the form
^AU 0 here instead; the polite thing to do is to ignore gaffes of
this sort. This is of course what CSSC does.
The file flags section occurs after the authorised-users list. Each file flag occurs on a separate line and are possibly followed by their values (except the boolean flags, whose mere presence is sufficient). These lines look like this:-
^Af f e 0
^Af f n
^Af f q Q-flag-value
^Af f v /bin/true
The e flag, if set to a nonzero value, indicates that the
controlled file is binary and is therefore stored in uuencoded form in
the file body. If this flag is set to zero or is missing, then the file
body is not encoded. See Flags for information about the other
possible flag letters and their meanings. See Interoperability
for information about sharing SCCS files with other implementations
of SCCS.
The e flag is a boolean flag but is stored within the SCCS
file with a value, as shown in the example above. When CSSC
initially writes the SCCS file header for a new SCCS fiel
created with admin -i, it does not know if the initial body of
the file is binary or not, so ^Af f e 0 is written into the
header and if the file turns out to need encoding, admin will
seek back to the header and change ^Af f e 0 to ^Af f e
1. If binary file support is disabled (see Binary File Support,
^Af f e 0 is still used but will never be changed to ^Af
f e 1.
The value for the y flag is stored as a space-separated list of
keyword letters, even though the letters were separated by commas when
they were passed to admin -fy. This flag is an extension
introduced by Sun Solaris 8. See Interoperability for a
discussion of the interoperability of CSSC with other SCCS
implementations.
The flags section is followed by the descriptive text for the history
file. This section is intended to contain text which might contain a
copyright statement, or might indicate the purpose of a file or
contain special instructions, and so on. This section starts with a
^At control line and is terminated with a ^AT control
line:-
^At
This is the blah blah...
... blah.
^AT
The ^AT control line marks the end of the SCCS file's
header. The following line is the first line of the file body.
This example also includes the file body, since the body is short.
^Ah38213
^As 00002/00000/00000
^Ad D 1.3 98/11/22 18:25:43 james 3 2
^Ax 2
^Am 99
^Ac This delta was produced using "get -e -x1.2 s.foo" and
^Ac then "delta s.foo".
^Ae
^As 00001/00000/00000
^Ad D 1.2 98/11/22 18:22:56 james 2 1
^Am mr1
^Am mr2
^Am
^Ac comment goes here.
^Ae
^As 00000/00000/00000
^Ad D 1.1 98/11/22 18:21:11 james 1 0
^Ac date and time created 98/11/22 18:21:11 by james
^Ae
^Au
^AU
^Af e 0
^Af n
^Af q UMSP
^Af v /bin/true
^At
Descriptive text
^AT
^AI 3
this delta was made from a working file which was gotten for editing
but excluded the delta named 1.2.
^AE 3
^AI 2
blurg
^AE 2
^AI 1
^AE 1
The body of an SCCS file is usually much longer than its header,
but contains fewer ingredients. It contains control lines, which signal
the beginning or end of a chunk of user data, and the user data itself.
If, for example, you added the text I was here to the controlled
file as a delta whose delta sequence number was 7, the history might
contain these lines:-
^AI 7
I was here
^AE 7
I currently have no clear understanding of the interaction of excluded,
included or excluded revisions with the normal check-in processing.
Hence I can't thoroughly explain the precise meaning of the ^AI,
^AE and ^AD control lines. This section will be completed
at a future date. If you have an understanding of these issues, please
let me (jay@gnu.org) know.
This part of the CSSC manual describes how CSSC interoperates with SCCS. For the enormous majority of cases, this occurs seamlessly; however sometimes it is not possible for CSSC to pick "one right way" to proceed unaided. Circumstances where this occurs are described in detail, below.
In order to interoperate better with other implementations of SCCS, the CSSC suite can also be configured to turn off several features which provide flexibility beyond that which is available in some other implementations of SCCS. Some other interoperability features of CSSC exist to maintain compatibility but do not need to be turned off.
Binary file support can be turned off when you run "configure" by
specifying the --disable-binary option. This will cause
admin to refuse to create an SCCS file whose "e" flag is set
(see Flags). The admin program would normally do this if the
user requested it via the -b option or if it discovered that the
file could not safely be stored in the normal SCCS file format.
This setting can be overridden with the environment variable
CSSC_BINARY_SUPPORT; for a description of how to use this
environment variable, see Environment.
If you use CSSC with support for encoded SCCS files turned off, encoded files will still be handled; CSSC will just refuse to create a new one. This provides as great a degree of interoperability with other implementations of SCCS as possible.
The support that CSSC provides for binary files allows the controlled file to contain any sequence of bytes. That doesn't imply that the controlled file is used for any particular purpose. For example, JPEG files can contain non-ASCII acharacters.
This should be contrasted with support for executable files,
which have a specific Unix file mode bit set (see the manual page for
chmod for more details). Unix executable files may or may not
be binary files. It's common to control shell scripts with
CSSC, for example. Shell scripts are normaly executable but not
binary.
If the x flag is set, CSSC will generate a g-file whose
execute bits are set. This feature exists for compatibility with SCO
OpenServer's SCCS. Do not use this feature if you wish to
interoperate with other implementations of SCCS. Setting this
flag with admin -fx generates a warning about this.
Read-only support is provided for files produced by the BitKeeper suite. Flags and information which are specific to BitKeeper is ignored by CSSC. At the moment, it is not possible to turn off support for BitKeeper files, but a warning message is issued when one is encountered.
Actions on BitKeeper files that CSSC will not perform include
CSSC does not prevent the use of unget on BitKeeper files,
because unget does not examine the SCCS file header (and
therefore has no way to determine if the file is a BitKeeper file or
not).
By default, CSSC enforces no line length limits. The CSSC tools
will correctly process input files containing lines of arbitrary
length, subject to the limits of available memory. The system command
diff may impose its own limit however; this is discussed below
(see Limitations of diff).
If you are working with a binary file (that is, the -b option
to admin was used when the history file was created), the
encoding mechanism used by CSSC (and those SCCS
implementations that support binary files) ensures that data is
encoded before being stored in the body of the history file, and so
the "binary" file can contain any sequence of bytes at all - the
"line length" is no longer important.
Most other implementations of SCCS do however have an upper limit
on the maximum length of line that can be handled in a text file (that
is, those versions of SCCS which have such a limit do not apply
this limit for binary files). To set such a limit in CSSC, use
the --enable-max-line-length=N option to "configure". This
sets the limit to the specified value.
This setting can be overridden with the environment variable
CSSC_MAX_LINE_LENGTH; for a description of how to use this
environment variable, see Environment. To determine the current
setting of the line length limit, run admin -V and read the
output.
If (and only if) you have configured CSSC with such a maximum line length limitation, the lengths of input lines are checked as they are being read. When CSSC is adding a new delta to an existing file, if it finds an input line which is longer than N characters, it will fail with an explanatory message (the alternative would be that an SCCS file would be generated that could not be read by other implementations of SCCS having a lower line length limit).
When CSSC is creating a new SCCS file in response to the
admin -i command, one of two things will happen when an
over-length line is found. If binary file support is enabled, the
SCCS file will automatically be created as an encoded file.
Otherwise, admin will fail with an explanatory message.
When the CSSC tools are reading a history file, the lines in the
SCCS file are not subject to the limits described above; that is,
CSSC imposes these limits on lines it puts into the
SCCS file, but not on lines it reads from the SCCS
file. This means that the CSSC get utility will cope with
arbitrarily long lines in the SCCS file, even if CSSC has
been configured in sauch a way that delta would not put such
long lines into the history file.
The diff utility may have limits on the lengths of lines that
it can process, though the GNU diff program has no such limits.
This means that if you are using CSSC in combination with a
diff which has a line length limit, that limit will apply to
the operation of the CSSC delta and sccsdiff
programs (though not to any other component of CSSC).
This kind of problem may cause delta to fail because the file
you are checking in contains an over-length line. However, because
SCCS files may be operated on by SCCS implementations that
have different upper limits, you might also find that the delta you
checked out from the history file already contained a line which is
longer than can be coped with by your delta utility. GNU
CSSC can always be switched back a mode in which there is no line
length limit (i.e. the mode which is usually the default) and so can
be used to work around such situations.
Bear in mind that implementations of diff and SCCS on a
given system can have different limits on the sizes of lines
that can be handled by delta, get and diff. This
is not the case with the GNU system however, which has no such limits.
The diff utility will also fail if the last line in one of the
files being compared does not end in a newline. To work around this
you can either encode the file as a binary file (see admin) or add
a terminating newline (which is usually the best course of action).
The diff program to be used by the CSSC tools is selected
when the configure script is run, before CSSC is compiled.
Configuration explains how you can determine which diff command
is used by CSSC.
To discover how a particular installation of CSSC is configured,
pass the -V option to any of the CSSC tools. The
"configure" script defaults to not limiting the maximum line length,
but you must specifically indicate if binary file support is to be
enabled or not when running "configure".
Some other implementations of SCCS have bugs, too. Where we know about these and can work around them, we do this. Please not that these bugs only affect some other versions of SCCS - if they affected all versions, they'd be the correct behaviour of CSSC too!
There are some features of SCCS implementations with which CSSC cannot maintain compatibility.
This section outlines some of the ways in which various versions of SCCS differ from each other and therefore sometimes from CSSC.
The various versions of SCCS differ in their level of support for binary files (see Binary File Support), and in the maximum line length that they will support (see Maximum Line Length.
There are some small variations in the way that the several versions
of sccsdiff behave. These are outlined in the table below :-
diff output for each
s-file. This separator is output before the first set of diff output,
even if only one s-file has been named on the command line.
There are a few differences in the behaviour of the admin
command across the various SCCS Implementations :-
-n option
-n option
without the -i option. A workaround is to use -n
-i/dev/null instead.
-b
option to admin. See Binary File Support, for more
information.
x
flag, which turns on the executable bits of the mode of the g-file
when it is created. Other versions of SCCS do not have this
feature. While CSSSC provides this feature also, its use is not
recommended. The prt -f command does not indi