This file documents the the GNU cssc package for working with SCCS files.

Copyright (C) 1997, 1998, 1999, 2000, 2001, 2002, 2003, 2004, 2005 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.

This file documents the the GNU CSSC package, which is a work-alike for the traditional Unix SCCS suite.

This is edition 1.08, for CSSC Version 1.01.

Overview
********

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? (The CVS Manual).  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).

How to use the suite
********************

By far the easiest way to use CSSC (or indeed SCCS) is to use VC-mode in GNU Emacs.  See Version Systems (The GNU Emacs manual).

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.

Invoking CSSC programs
**********************

The menu items are arranged in approximate order of frequency of use, except admin, which is first because you have to use it to start with.

admin
=====

To 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.

-aXXX
     Add user or group XXX to the list of those authorised to check revisions in (that is, use get -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
     Ensure that the file is encoded as a binary file.  This option only works in conjunction with the -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 Variables).

-dF
     Delete flag F from the flags present in the file (see Flags).

-eXXX
     Erase the specified user or group from the list of those authorised to check revisions in or out.

-fF[XXX]
     Add the flag F (with optional value XXX) to the file's flags (see Flags).  For example, -fv/tmp/checkit sets the MR-validation flag to /tmp/checkit.

-h
     Check the SCCS file.  The exit value will be 0 if the file is valid, and not 0 otherwise.  The checks made are the same as those made for 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
     Initialise the SCCS file with the contents of the file FOO. If no argument is given, read from standard input.  This implies the -n option.

-mMR-LIST
     When initialising a file, add the specified list of MR numbers (see Modification Request Numbers) to the delta commentary for the initial version.  This list can be empty.  The specified MRs are validated according to the setting of the V flag, which should be set (see Flags).  If the V flag is set but has no value (i.e. is set to the empty string), validation silently succeeds.  If the V flag is not set, the -m option causes delta to fail.

-n
     Create a new SCCS file.  Unless -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.

-rN
     Set the initial release number to N.  The initial level within that release is always 1.  Some versions of SCCS allow you to specify actual an actual SID here (for example 1.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 SCCS Version Differences.

-tDESC
     Read in descriptive text for this file from DESC.  This replaces any existing description.  If no argument, remove any existing description (this is illegal if -i or -n is used).

-V
     Display version information.

-yADAYADA
     When initialising a file, set the comment for that delta to ADAYADA.  If the option is given just as -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
     Fix the checksum information.  The SCCS file is still validated by CSSC; apart from possibly having an incorrect checksum, the s-file must be valid.  If you use this option on an SCCS file which really is invalid, then the attempt may fail or silently write out a valid but incorrect file.  This option does not work on BitKeeper files.  Use this option with extreme care.

Flags
-----

Flags are set and cleared with the admin program.  See admin.

Boolean Flags
.............

b
     Enable branch deltas: this enables the -b option of get (see get).

e
     This flag indicates that the file controlled by this SCCS file is a binary file, and hence the body of the SCCS file is uuencoded. This flag can only be set with the -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
     This flag is specific to the BitKeeper suite, and is only supported if CSSC has recognised the file as a BitKeeper file. CSSC does not understand the significance of this flag.

i
     Make get and delta exit unsuccessfully when the Warning: No id keywords message is issued.

j
     Enables concurrent updates: if you try to get a revision for editing, this normally fails if another user already has the file locked. Setting the j flag overrides this.

n
     Create empty releases when the -r option to get is used to skip releases.   These empty releases can later serve as branch points.

x
     Sets the executable bit on the g-file.  This flag is a SCO OpenServer extension and is not supported by other versions of SCCS. Setting this flag with 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.

Other Flags
...........

c
     Set the release ceiling.  Releases higher than the ceiling cannot be checked out.

f
     Set the release floor.  Releases lower then the release floor cannot be checked out.

d
     Set the default delta which is used when the get command is given without the -r option.   The default behaviour for get is defined in get.

l
     Set the locked release list.  These releases cannot be checked out with get -e.   The special value a denotes all releases.

q
     Sets the value substituted for the %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
     Sets the overridden value for the %M% keyword as described in Keyword Substitution.

t
     Sets the value for the %Y% keyword as described in Keyword Substitution.

v
     Sets the name of the program used to validate MR (modification request) numbers; MRs are described in Modification Request Numbers.  This flag can be set to the empty string, in which case MRs are allowed and the validation silently succeeds without any program being run.

y
     By default, all keywords are expanded in the gotten file. See Keyword Substitution for a list of such keywords.  This flag can be set to a list of letters separated by commas, in which case keyword expansion will be limited to the specified keywords.  For example, 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.

Modification Request Numbers
----------------------------

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.

cdc
===

The 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
     The specified (space-separated) list of MRs is added to the MR-list for the relevant delta.  If more than one MR number is to be added, the whole option should be quoted, to protect the spaces. If an MR is prefixed with an exclamation mark (!), 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).

-rSID
     This indicates which delta is to be changed.   It must refer to an existing delta in the file, which has not been removed with rmdel.

-yCOMMENT
     This option introduces a comment to be added to the commentary for the specified SID.  If more than one line is needed, it is a good idea to enclose the option in quotation marks to ensure that the shell includes them in the argument passed to cdc.  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.

comb
====

This 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.

delta
=====

The 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 Making 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.

Basic usage for delta
---------------------

Although 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).

Options for delta
-----------------

-gSID-LIST
     The specified list of deltas are to be ignored when the version being checked in is retrieved using get.  The list is a list of SIDs separated by commas, or can contain ranges of SIDs (these are indicated by a dash).  Untested.

-mMR-LIST
     Specify the indicated list of MR numbers (separated by spaces) for this change (see Modification Request Numbers).  If the V flag (see Flags) is set, delta 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
     If this option is given, the edited file is not deleted once processing has succeeded.  The edited file is referred to as the ``g-file'', since it is the file which was previously ``gotten'' by the get command.

-p
     Display the differences between the old and new versions of the file during processing.  The output of diff is echoed on the standard output.

-r
     If several versions are checked out, the -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
     Suppress warning or confirmation messages.  Error messages go to standard error.  This option is not covered in the test suite.

-y
     Specify a comment for the revision log.  This option is usually quoted to protect the spaces contained in it.  An empty comment can be specified by just using a naked -y.  If this option is not given on the command line, delta will prompt the user for a comment.

get
===

The 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.

Basic Usage for get
-------------------

     There are very few common basic usage patterns for get.  Below, s.foo.c denotes the name of any existing SCCS file.

get s.foo.c
     Get a copy of the most recent trunk revision of s.foo.c into the file foo.c.

get -Gbar s.foo.c
     Get a version from 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
     Get revision 1.3 from 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
     Get the most recent trunk revision, and print it on standard output. The -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.

Options for get
---------------

     Full description of options

-aN
     Retrieve the version corresponding to the delta sequence number N.  Mainly for use by other programs in the suite.

-b
     Create a new branch when the resulting file is checked back in.  Used with the -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 Making Branches).

-cwhen
     Get the version that was current at the time specified by when.  The format of the argument is [cc]yy[mm[dd[hh[mm[ss]]]]].  Any fields omitted (except ``cc'') assume their maximum possible values so that if you specify -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
     Turns on debugging output, indicating what is going on as the SCCS file is read.  This option may go away or have its behaviour change in the near future.

-e
     Indicates that the retrieved version is for editing.  When checked back in the resulting file will have a new revision number.  The retrieved file is writable, and keyword substitution does not take place.  A p-file is created; this file contains information about what versions of the s-file are being edited, and by whom. Unless the 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
     Do a dry-run, showing what version would be retrieved, but don't actually get the file.  This is sometimes done by scripts, just to test the exit status.

-GFOO
     Name the gotten file FOO, instead of the default name.

-iLIST
     Include the deltas for the listed SIDs.  See also -x.

-k
     Avoid doing keyword substitution (see Keyword Substitution).  This is assumed when -e is specified.  The gotten file is writable.

-l
     Unsupported.

-lp
     Unsupported.

-m
     Prepend to each line of the result the SID corresponding to the delta which introduced this line to the file.

-n
     Precede each line of output with the module name, before any SID added with the -m option.

-p
     Write the result to the standard output, rather than to a file.

-rX
     Retrieve version X, rather than the default.

-s
     Run silently.

-t
     Get the ``top'' delta for the indicated release.  The default behaviour of 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
     Show version information.

-wXXX
     When performing keyword substitution (see Keyword Substitution), use XXX rather than %Z%%M% <TAB> %I% as the substitution value for %W%.

-xLIST
     Exclude the indicated deltas from the result.  Deltas are indicated by specifying the SID at which they arrived in the file.

Making Branches
---------------

Normally, 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
--------------------

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:

A
     Expands to the same as %Z% %Y% %M% %I% %Z%.

B
     The branch number of the gotten version

C
     Current line in the output file

D
     The date at the time the file was gotten, in the form yy/mm/dd.  The year is always represented as two digits but this is not ambiguous since the two-digit year is no later than 2068 (see Year 2000 Issues).

E
     The date that the newest delta in the gotten file was applied, yy/mm/dd.  The year is always represented as two digits but this is not ambiguous since the two-digit year is no later than 2068 (see Year 2000 Issues).

F
     Name of the SCCS file, for example s.foo.c.

G
     As for %E%, but in the US format mm/dd/yy.

H
     As for %D%, but in the US format mm/dd/yy.

I
     Expands to the same as %R%.%L%.%B%.%S%, that is, the SID of the retrieved version.

L
     The level number of the retrieved version.

M
     Module name: the value of the m (module) flag, or the base name of the SCCS file with the s. removed if the module flag is unset.

P
     Full name of the SCCS file.

Q
     Value of the q flag.  The q flag has no other purpose, and can be set with admin -fqfoo.   See Flags.

R
     Release number of the retrieved version.

S
     Sequence number of the retrieved version.

T
     Current time (hh:mm:ss) when the file was retrieved, see %D% and %H%.

W
     Expands to %Z% %M% <TAB> %I% or the argument for the -w flag, if given.

Y
     Value of the t (module type) flag.

Z
     The literal string @(#).  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%.

Included Excluded and Ignored deltas
====================================

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 Reporting Bugs).

The Usual Case
--------------

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.

Included Deltas
---------------

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.

Excluded Deltas
---------------

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
--------------

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.

help
====

This 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.

prs
===

The 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

  * Producing an audit trail of who changed what, and why, for example for a software release report, or for ISO 9000 documentation.

  * Discovering how a particular piece of code became broken, and deducing which change broke it.  The get -m command is also useful for this, see Options for get.

  * Listing all changes made on Friday afternoons, as a preparation for extra checking.

Basic Usage for prs
-------------------

Here are some examples of the use of prs, with explanations of what they do.

prs s.myfile.c
     Show information about all the versions of myfile.c.

prs SCCS
     Show information about all the SCCS files in the directory SCCS.

prs -e -d:P: s.main.c | sort -u
     Show which users have made changes to main.c.

prs -l -c`date +%y%m%d --date "last week"` SCCS
     Examine all the SCCS files in the directory SCCS. Show any deltas that have been created since last week.

Options for prs
---------------

-a
     Include even removed deltas in the output.  Removed deltas have a type "R", as output by the :DT: keyword.

-c[CC]YYMMDDHHMMSS
     Specifies the time of the ``cutoff''.  When this option is given, the delta selected by prs 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.

-dFORMAT
     This specifies the data format for the output.  Because the default output format is sensible, this is typically used either in a shell script which will process the output further, or by a human to retrieve information which is not shown by default.  See Data Keywords for the various keywords that can be used.  Any characters in the data format which are not part of a keyword are output as well.

     If 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
     Makes the -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
     As the -e option, but select only later deltas rather than earlier ones.

-rSID
     Specifies the SID for which information is provided.  If blank, the latest delta is selected.

Data Keywords for the -d option of prs
--------------------------------------

Global Keywords
...............

These keywords expand to the same thing, no matter which version is being examined.  Many of these are SCCS file flags (see Flags).

:BD:
     Emits the body of the SCCS file, that is, the part containing all the delta information.  Note that since this is dumped verbatim, it contains control characters.  If you want a more readable format, consider using the -b option of prt (see prt options).

:BF:
     Indicates the setting (yes or no) of the branch flag.

:CB:
     Indicates the value of the release number ceiling flag.

:Ds:
     The default SID to check out (See Flags and get).

:F:
     Name of the SCCS file.

:FB:
     Indicates the value of the release floor boundary flag.

:FD:
     File descriptive text (see admin).

:FL:
     List of SCCS file flags.

:J:
     Value (yes or no) of the joint-edit flag.

:KF:
     Value (yes or no) of the keyword-warning flag (see admin).

:LK:
     Value of the locked-releases flag.

:M:
     The module name (the value of the m flag).

:MF:
     The value (yes or no) of the MR validation flag (see delta).

:MP:
     The value of the MR validation program flag (see delta).  This is usually the name of an executable file.

:ND:
     The value of the null-delta (n) flag (yes or no).

:Q:
     The value of the (user-defined) Q flag (arbitrary one-line text).

:PN:
     The full path name of the SCCS file.

:UN:
     List of users authorised to make deltas to this file (one per line). This list can be modified with the use of the options -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:
     Value of the module-type flag.

The :BD:, :FD:, :FL: and :UN: keywords from this section may expand to strings containing newlines.

Version-specific Keywords
.........................

These keywords expand to data that is specific to a particular version.

:A:
     Expands to :Z::Y: :M: :I::Z:, useful for what.

:B:
     Branch number of SID

:C:
     Comments for this delta.  These may extend over several lines.

:D:
     Date (yy/mm/dd) that this version was checked in.  Expands to :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:
     Day-of-month on which the delta was checked in (two digits).

:Dg:
     Sequence numbers of ignored deltas (separated by white space).

:DI:
     Expands to :Dn:/:Dx:/:Dg: (sequence numbers included/excluded/ignored).

:DL:
     Expands to :Li:/:Ld:/:Lu: (lines inserted/deleted/unchanged).

:Dm:
     Month when this version as checked in (two digits).

:Dn:
     Sequence numbers of included deltas (separated by white space).

:DP:
     Sequence number of the delta that precedes this one.

:DS:
     Sequence number of this delta.

:Dt:
     Expands to :DT: :I: :D: :T: :P: :DS: :DP:.

:DT:
     Delta type: R (removed) or D (normal).

:Dx:
     Sequence numbers of excluded deltas (separated by white space).

:Dy:
     Year when this version was checked in.  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).

:GB:
     The body for this version, as distinct from the body of the SCCS file itself, which is obtained with :BD:.  Keyword expansion will be performed in the same way as if get had been used.

:I:
     The SID of this version.

:L:
     The level component of the SID (that is, the second number).

:Ld:
     Number of lines deleted in this version, with respect to its predecessor.

:Li:
     Number of lines inserted in this version, with respect to its predecessor.

:Lu:
     Number of lines unchanged in this version, with respect to its predecessor.

:MR:
     The MR numbers specified when this delta was created.

:P:
     Perpetrator: the login name of the user who created this delta.

:R:
     The release number of the SID (the first number).

:S:
     The sequence number of the SID.  Don't confuse this with the delta sequence numbers (see Delta Table), which are internal identifiers for deltas which are output by the keywords :DI:, :Dn:, :Dx: and :Dg:.

:T:
     Time that this version was checked in (:Th:::Tm:::Ts:).

:Th:
     Hours component of check-in time (:T:).

:Tm:
     Minutes  component of check-in time (:T:).

:Ts:
     Seconds  component of check-in time (:T:).

:W:
     Shorthand for :Z::M:<TAB>:I:, suitable for what (see what).

:Z:
     Expands to @(#) (see what).

The :C:, :GB: and :MR: keywords from this section may expand to strings containing newlines.

prt
===

The 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.

Basic usage for prt
-------------------

The 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.

Options for prt
---------------

-a
     ``All deltas''; this means that the output will include ``removed'' deltas.  Removed deltas exist after rmdel has been used to remove a delta.

-b
     Print the body of the SCCS file.  This is printed in a readable format.  The control character ^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
     Print information about the deltas in the file, as opposed to information about the SCCS file itself (for example the authorised users).  This is the default behaviour.  The default behaviour is turned off by the -b, -f, -t and -u flags, but specifying -d on the command line again will ensure that the delta information is printed.

-e
     ``Everything''; Means the same as -i -u -f -t -d.

-c[CC]YYMMDDHHMMSS
     Specifies the time of the ``cutoff''.  When this option is given, prt 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
     Print the flags of the SCCS file (see Flags).

-i
     Print the serial numbers of included, excluded, and ignored deltas.

-r[CC]YYMMDDHHMMSS
     Specifies a cutoff, as with the -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
     Print only a summary line for each delta (that is, the MR list and comments and so on are omitted).

-t
     Print the text description of the SCCS file, as set by admin -t (see admin).

-u
     Print the list of users and group IDs authorised to make deltas, one per line.

-ySID
     Print only information for deltas as new as the specified SID.  If the argument part is empty, that is, the option used is simply -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 format
-----------------

The output format is fixed, though parts of the output can be omitted.

 1. The header

       * Newline

       * SCCS file name, followed by a colon

       * Two further newlines.

 2. Delta table information (for -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).

       * Delta type
          'R' for removed deltas (see rmdel), and 'D' for ordinary ones.

       * TAB

       * Delta creation time (YY/MM/DD hh:mm:ss)

       * The login name of the user who created this delta

       * Sequence number of this delta

       * Sequence number of the previous delta

       * Line statistics inserted/deleted/unchanged.  These statistics are capped at 99999, due to a limitation in the file format.

       * Newline

 3. Delta detail information
     This section is printed once for each selected delta, unless the -s option has been specified.

       * Included deltas

       * Excluded deltas

       * Ignored deltas

       * MR numbers

       * Delta comments

 4. Global information
     Once information has been printed for each of the selected deltas, the global information is printed.   This consists of

       * List of authorised users and group IDs (if the list is blank, everyone is printed)

       * The SCCS file flags (see Flags) are printed.

       * The description of the SCCS file is printed (this is the description set by the -t option of admin).

       * The body of the SCCS file is printed, in a readable format. The control character ^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.

rmdel
=====

The 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.

sact
====

The 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
     Identifies the revision that was checked out for editing.

new-SID
     This is the SID that will be allocated by delta when the working file is checked in again.

user
     The login name of the user who checked out the file.

date time
     The date and time at which the checking-out was done.

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.

sccs
====

The 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/.

sccsdiff
========

The 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
     This option is provided by CSSC but not by other SCCS implementations. It briefly describes the usage of the program.

--version
     Indicates the version information for the sccsdiff program.

-p
     The differences are piped through pr, rather than just being output directly.

-rSID
     This option is used to select a revision from the s-file.   It must be specified exactly twice, in order to select a pair of revisions to compare.

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.

unget
=====

The 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.

Options for unget
-----------------

-n
     Do not delete the g-file which you were editing

-s
     Operate silently

-rSID
     When joint editing is enabled (see Flags), several versions may be checked out for editing.  If this is the case, SID must be used to indicate which edit is to be aborted.

val
===

The 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

Options for val
---------------

-mNAME
     Assert that the module name flag of the SCCS file is set to NAME.  The return value of VAL will be zero only if all the other checks succeed and the history file has its module name flag set to this value.  See Flags, for a description of the SCCS file flags.

-s
     Silent operation; suppress any error or warning messages that would otherwise be emitted; the return value of the program will still indicate the existence and general nature of any problems.

-V
     Display version information .  This option does not exist in the traditional SCCS implementation.

-rWANTED
     Validation will succeed if the SID WANTED is valid, unambiguous, and present in the history file.

-yTYPE
     Assert that the module type flag of the SCCS file is set to TYPE.  The return value of VAL will be zero only if all the other checks succeed and the history file has its module name flag set to this value.  See Flags, for a description of the SCCS file flags.

Validation Warnings
-------------------

Some 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.

WARNING: date for version 1.1 is later than the date for version 1.2
     This message indicates that a delta exists in the history file where the ``parent'' delta has a delta creation time which is later than the creation time of the ``child'' delta.  This is a warning only because the delta creation time is measured in local time, and so if two developers with different time locale settings both edit the file in a short period of time, this can happen.  If all the developers who create deltas in a history file use the same timezone settings, this should not happen.

     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.

Unknown special comment intro
     This message is displayed when a ``c'' control line is seen in the body of the SCCS file in which the initial ``c'' is not followed immediately by a space.  Lines of this type are used as an extension mechanism by some other SCCS implementations, notably the BitKeeper suite, and CSSC knows about this, but if it sees a construction it doesn't recognise, this warning is issued.

The 'y' flag specifies a keyword letter 'X' but %X% is not a recognised SCCS keyword
     This message is displayed when the 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.

Return Value
------------

The value returned by the val program depends on the outcome of the validation as follows :-

0
     Validation succeeded.  No problems were detected.  A small number of potential problems may exist without causing a non-zero return value; see Validation Warnings, for more information.

1
     The -m option was used but the module name did not match.

2
     The -y option was used but the module type did not match.

4
     The -r option was used but the specified SID was ambiguous, or not present in the history file.

8
     The -r option was used but the specified SID was invalid.

16
     Either the named file could not be opened, or it is not an SCCS history file.

32
     The history file is corrupt.

64
     An invalid option letter was used on the command line.

128
     One of the files named on the command line was not present.

Why val doesn't solve the whole problem
---------------------------------------

Things that paranoid people might bear in mind are

  * Not all accidental changes to an SCCS file will necessarily make the file invalid.

  * Since the checksum of an SCCS file is of finite length, there is a finite (though small) chance that a random change will not be detected by the checksum

  * If data is corrupted in the memory of a program, then the program will write the incorrect data out to the history file and set the checksum accordingly (in other words, an on-disk checksum only protects the data while it is on the disk).

  * Even if 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).

  * Consumer-grade hardware (for example commodity PCs) generally lacks error-correcting memory.

Things that an optimistic person might bear in mind are

  * The chances of a random change simultaneously fooling the checksum and the checks that val does are very small indeed.

  * Hardware failures rarely cause file corruption.  The use of ECC memory substantially reduces your changes of having undetected data corruption.

  * When CSSC operates on an SCCS file, most of the checks that 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.

what
====

The 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.

Options for what
----------------

what [-s] [-V] file [file ...]

-s
     Exit successfully after finding the first string.

-V
     Show version information for what.

Example
-------

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.

Filenames
*********

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.
     The history file itself.

p.
     The file containing the list of edit locks.

z.
     The lock file used to arbitrate access to the history file.  The running CSSC (or SCCS) program puts its PID into this file.  Some versions of SCCS (but not CSSC) will break the lock after 60 seconds if the specified PID is not running on the local machine.  In order to work more reliably over networked filesystems, CSSC will not do this; stale lock files would have to be removed manually.

x.
     Temporary file into which is written the new s-file.  Once processing is complete, the old s-file is replaced by the x-file.

q.
     Temporary file into which is written the new p-file

d.
     Temporary file used by delta; contains the gotten body of the previous version (which we run diff against).  This filename is used by SCCS in the same situation, but according to the SCCS manual pages, it puts the output of diff in this file instead.

u.
     Encoded version of the gotten file; created by delta.

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.

File Format
***********

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.

Overview
========

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.

The Header
==========

There are several parts to the SCCS file header:-

Checksum
--------

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 Delta Table
---------------

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

Authorised User List
--------------------

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 Global Flags Section
------------------------

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.

File Description
----------------

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.

Example SCCS File Header
------------------------

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
========

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.

Interoperability
****************

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
===================

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 Variables.

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.

Executable File Support
=======================

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.

BitKeeper
=========

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

  * get -e

  * delta

  * cdc

  * rmdel

  * Some options to admin

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).

Maximum Line Length
===================

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 Variables. 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.

Limitations of diff
===================

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.

Checking the Current Configuration
==================================

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''.

Bug-for-Bug Compatibility
=========================

Some other implementations of SCCS have bugs, too.  Where we know about these and can work around them, we do this.  Please note that these bugs only affect some other versions of SCCS - if they affected all versions, they'd be the correct behaviour of CSSC too!

  * Some versions of SCCS had a Y2K-related problem where the tens digit in the year fields within the delta table of the SCCS file contains a colon (`:') rather than a digit.  When reading files, CSSC correctly understands this to be a zero and issues a warning message.  The fault is corrected if the SCCS file is being modified. See Year 2000 Issues.

  * Some versions of the Data General implementation were changed to use four-digit years in the p-file instead of two-digit years, apparently as part of a Y2K-fix.  While arguably this in fact might have been the right way to fix the problem, none of the other SCCS implementations went along with the idea. See Year 2000 Issues.  If the file is being modified, the year is written back out as a two-digit field.

  * Although it is unusual for SCCS files to have ``^A m'' lines after ``^A c'' lines, this does sometimes occur.  CSSC accepts either order, but always emits the MR numbers before the comments for each delta.

  * CSSC accepts ``^A m'' lines with no argument, although this is unusual.   This may in fact not actually be a bug.

  * Some versions of SCCS (allegedly some versions of the Sun Code Manager product) emit lines of the form ``^AU 0'' instead of ``^A U''.  CSSC accepts either but only produces the latter.  Similar situations exist for lines of the form ``^At 0'' and ``^A T 0''.

Incompatibilities
=================

There are some features of SCCS implementations with which CSSC cannot maintain compatibility.

  * The CSSC behaviour of correcting the problems mentioned above may not be compatible with those versions of SCCS which actually exhibit those problems (then again, some of them are not able to read their own output in these circumstances, either).

  * The BitSCCS product, part of the BitKeeper suite, uses special comment lines in the delta table, of the form ``^Ac_'' where ``_'' is some character other than a space.  When CSSC sees these, it will avoid changing the SCCS file (though it will still work for read-only operations, even though the significance of the special comment is ignored).  File flags which are specific to BitKeeper are also treated in this way.

SCCS Version Differences
========================

This section outlines some of the ways in which various versions of SCCS differ from each other and therefore sometimes from CSSC.

Binary file support and line lengths
------------------------------------

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.

sccsdiff
--------

There are some small variations in the way that the several versions of sccsdiff behave.  These are outlined in the table below :-

Solaris 8
     Prints a separator line between the 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.

Solaris 2.6 and many other versions of Unix
     Does not print a separator.

admin
-----

There are a few differences in the behaviour of the admin command across the various SCCS Implementations :-

The -n option
     Some versions of Dynix do not allow the use of the -n option without the -i option.  A workaround is to use -n -i/dev/null instead.

Binary file support
     Most implementations of SCCS do not support the encoding of binary files, either automatically or by the use of the -b option to admin.  See Binary File Support, for more information.

Executable file support
     The SCO OpenServer implementation of SCCS provides an 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 indicate the value of the x flag.

Initial delta
     The -r option is used to specify the release of the initial delta.  Some implementations of SCCS allow this to be used to specify more components of a SID than just the release number. The CSSC version of admin allows this usage but issues a warning message.  If the -r option is used to specify a non-trunk SID (that is, a SID with more than two components), this is allowed but some of the other tools in the CSSC suite will not work correctly on the resulting file.

prt
---

If the ``encoded'' flag is set, some versions of prt (but not the CSSC version) omit a newline in the output and so the next thing follows immediately on the same line.

get
---

Sun Solaris 8 features a y flag.  If the y flag is set in the SCCS file, only the specified SCCS keywords will be expanded in the gotten file (assuming that the -k and -e options are not used).

The get command on SCO OpenServer honours the setting of the x flag.  This is described above.

For a discussion of the interoperability of CSSC with other SCCS implementations, see Interoperability.  For a description of the x and y flags, see Flags.

CSSC Extensions
===============

There are some respects in which CSSC behaves unlike other versions of SCCS.  These differences mainly relate to the removal of arbitrary limits or problems, and generally do not pose an interoperability problem.  The most important extensions are listed below.

Line Length
     By default, CSSC enforces no line length limits.  See Maximum Line Length.

Date handling
     The -c option to get supports four-digit years. See The Good News.

Binary file handling
     When you generate a new SCCS file with admin -i, the admin command will automatically determine if the file needs to be encoded.  Other versions of SCCS which do this rely on being able to seek in the input file specified as the argument to the -i option, which means that this is not possible if the initial file body is being read by a pipe.  The CSSC implementation of admin does not have this limitation, since it seeks on the file being created instead.  See Unemulated Features.

Combinations of features
     Various other SCCS implementations have extensions (for example the x and y flags and binary file encoding).  The CSSC suite attempts to honour all of these extensions, and is probably the only implementation which has all these features.  If you try to use a feature which is specific to only one implementation of SCCS, CSSC will issue a warning that what you are doing is not portable.

     If you use features of CSSC which are extensions originating in more than one other SCCS implementation, for example both the x and the y flags, you have effectively tied yourself to CSSC.  Once you are in that position, you are no longer able to interoperate with any other version of SCCS (since, in this example, any other version of SCCS will fail to understand either the x or the y flag).  If interoperability with other versions of SCCS is no longer an issue, you might as well bite the bullet and migrate to a more modern configuration control system entirely.  See Overview.

Validation
     The CSSC implementation of val implements some checks that other implementations lack.  Howver, it is not complete, and so there are also checks that other implementations make that CSSC does not.

Error Messages
     The error messages issued by CSSC are intended to be self-explanatory and so lack reference numbers like (ge4).

Closed File Descriptors
     If you invoke CSSC with file descriptor 0, 1 or 2 closed, that file descriptor is attached to /dev/null.  This prevents error messages going into a file opened by CSSC for writing (for example an SCCS file).

Read-only reaction to unsupported features
     If CSSC discovers a construct in an SCCS file which it doesn't understand, it will avoid modifying the file (though read-only tools like prt and get will still work).

Invoking other tools
     It is usual for CSSC to invoke other programs, for example diff and the MR-validator specified by the v flag. However, with the exception of the sccsdiff shell script, the tools within the CSSC suite do not invoke each other.  For example, delta does not invoke get.  This behaviour is different to the traditional architecture of SCCS and might introduce subtle differences of behaviour.  Any such differences are bugs; see Reporting Bugs.

Environment
     Some environment variables are specific to CSSC. See Environment Variables.

See also Missing Features and other Problems.

Environment Variables
*********************

Several environment variables control the behaviour of CSSC.  This section explains what these variables are and how they work.

Child Processes
===============

Unlike some other implementations of SCCS, CSSC tools do not usually execute each other.  This means for example that delta does not invoke get to extract the previous version of the file, and prs doesn't use get when processing the :GB: keyword.

There are a small number of exceptions to this rule :-

sccs
     The sccs driver program can be used to invoke any of the other tools in the suite.  See Known Problems, for a discussion of the issues this raises.

delta
     The delta program runs a program to validate the Modification Request Numbers offered by the user.  See Modification Request Numbers.

sccsdiff
     The sccsdiff program is a shell script, and invokes get, diff and pr, as well as other tools such as cat, test and rm.  The sccsdiff program must not be installed set-user-id.

The driver program sccs takes a number of precautionary steps if it detects that it is running set-user-id or set-group-id.  These steps are described below, as part of the discussion of each environment variable.

Configuration Variables
=======================

When ``configure'' is run, some default behaviours are set.  These can be overridden with the use of environment variables as described below.

CSSC_BINARY_SUPPORT
-------------------

The CSSC_BINARY_SUPPORT environment variable controls whether CSSC will create ``encoded'' SCCS files.  The three valid values for this variable are as follows :-

enabled
     CSSC will create encoded SCCS files if required

disabled
     CSSC will not create encoded SCCS files

unset
     The default behaviour is used; this default will be the same as for one of enabled or disabled.  The default is set by passing either --enable-binary or --disable-binary to ``configure'' when CSSC is compiled.  If this option was not specified, the default value is enabled.  For more information see Interoperability.

This variable is unset by the sccs driver program, if it is installed set-user-id or set-group-id.

CSSC_MAX_LINE_LENGTH
--------------------

The CSSC_MAX_LINE_LENGTH environment variable controls the maximum length of lines that CSSC will allow to go into an SCCS file. This variable should be set to a decimal integer.

The default behaviour of CSSC when this variable is unset is described in Interoperability.

This variable is unset by the sccs driver program, if it is installed set-user-id or set-group-id.

Other Variables
===============

USER
----

If ``configure'' detects that UIDs are not supported on the system you are running on (that is, you are compiling on a system that doesn't look at all like Unix) then the environment variable USER is used to determine the invoking user's name.  This is then the name which is used in the p-file and in the delta information for new deltas.  This username is also compared against the list of authorised users by delta.  Of course, this doesn't provide much security but in the absence of user ID support, CSSC can't tell who users really are anyway.

The behaviour of CSSC with respect to this option is not sensitive to whether or not programs are installed set-user-id, because this variable is only consulted on systems where set-user-id is not supported.  This may be a problem on systems where it is possible to grant enhanced privileges to a program, but which do not look like Unix to the ``configure'' program.

CSSC_SHOW_SEQSTATE
------------------

If set, the environment variable CSSC_SHOW_SEQSTATE will cause CSSC to emit debugging information about the delta table to stderr. This is only of use when debugging CSSC.

PROJECTDIR
----------

The PROJECTDIR environment variable is used only by the sccs driver program.  This variable is ignored if the the sccs program is installed with the set-user-ID bit set.  See Known Problems, for other remarks concerning setuid execution.

The PROJECTDIR variable is used to locate the SCCS history file corresponding to a filename given on the command line.  If the value of PROJECTDIR starts with a `/', it is used as an absolute directory name.  If PROJECTDIR does not start with a slash, it is assumed to be the name of a user, and SCCS files are assumed to be in the subdirectory ``src'' or ``source'' beneath their home directory.

PATH
----

Normally, the sccs driver program locates the other tools by searching the directories specified in PATH, but if it is running set-user-id or set-group-id, a compiled-in value is used instead.  By default, this value is is /usr/sccs.

If SCCS is not privileged, it will fall back on the compiled-in value in order to find the other tools if they are not found in any of the directories in $PATH.

In normal operation, sccs diffs will use the system diff command by searching the PATH environment variable.  This doesn't happen if it is running set-user-id or set-group-id.

LD_LIBRARY_PATH
---------------

None of the programs in the CSSC suite take any specific action regarding the LD_LIBRARY_PATH environment variable, but your system libraries may take notice of it (or decide not to do so, for example when a program is running set-user-id or set-group-id).

TMPDIR
------

The sccsdiff program ignores the setting of the TMPDIR environment variable.  Temporary files with predictable names are created in the /tmp directory.  See Known Problems.

Locale variables
----------------

The sccs driver program uses the setlocale function, whose behaviour depends on several implementation-dependent environment variables.  If you are using the GNU C library, these variables are LC_COLLATE, LC_CTYPE, LC_MESSAGES, LC_MONETARY, LC_NUMERIC, LC_TIME, and LANG.   The setlocale function is not called if SCCS is running set-user-id or set-group-id.

Missing Features and other Problems
***********************************

Missing Features
================

  * Documentation is incomplete or missing.  That includes this document.

  * Some programs are missing, that is, some programs are present in the SCCS suite and absent from this one.

  * On platforms where the C++ compiler used to compile CSSC does not support exceptions, the normal mechanism for recovering from an error in the processing of an SCCS file is unavailable.  This means that if such an error occurs, the program will immediately make a fatal exit, as opposed to carrying on with the next file.  In order to fix this problem, please either CSSC with a compiler which has working support for exceptions, or process just one file at a time.

  * Some programs behave subtly differently to their original counterparts. Error messages are different, and also extra warnings are provided in some circumstances.  All other differences are also bugs.  Please report them (see Reporting Bugs).

  * Known bugs are listed on the bug tracking system at http://sourceforge.net/bugs/?group_id=8064.  Some historical known issues are listed in the file docs/BUGS.  Once this file has become obsolete it will be removed from the distribution.

     If an item on the TODO list (see the file docs/TODO) has in fact been fixed, this is a bug in the TODO list.  Please report this via the bug tracking system.

  * Some programs are partially implemented.  Not all programs support all the command-line options of their original counterparts.  Also, some features are currently missing.  If you would like support for some feature that is missing, please request it in the same way you would report a bug; I'd like to know which features are required first.

Known Problems
==============

There are a small number of known problems documented in the files docs/BUGS and docs/TODO.  These will be fixed at some point in the future.  Future problems should be reported via the CSSC Bug Tracker, at http://sourceforge.net/bugs/?group_id=8064.

There are also some security problems with this code:-

 1. Temporary file races --- CSSC opens many temporary files, most of them with very predictable names.   This can be used as a lever for compromising the security of a system, often by anticipating the name of a file which will be opened at some point, and creating a symbolic link of the same name.  Most of the temporary files used are created in the same directory as the SCCS file itself.   CSSC should not be used by the owners of files whose security is important, especially to control files whose SCCS file is in a world-writable directory.  See Filenames.

     The sccsdiff program ignores the setting of the TMPDIR environment variable.  Temporary files with predictable names are created in the /tmp directory.

 2. Setuid execution --- It is common to install an extra set of binaries with the set-user-id bit turned on in their modes, to allow a specified group of users to make revisions to some important files.  There are many ways in which a setuid program can be used by malicious users to gain access to the security privileges of the user as whom a program runs.  CSSC has not been reviewed with the relevant security issues in mind.  Please do not install CSSC programs with the set-user-id or set-group-id bits turned on.

 3. Environment variables --- CSSC invokes external programs, notably the diff command and the program specified as the MR validation program.   Some CSSC programs (for example sccsdiff) invoke others.   This is done without ``cleaning up'' the environment, and so this is another reason not to use the set-user-id bit for CSSC programs. See Environment Variables.

Please refer to the section of the GNU General Public License entitled ``NO WARRANTY'' for information regarding the lack of warranty for this program.  CSSC is not a secure program, please do not rely on it to behave in a secure fashion.

Contributions of code or patches to fix these problems are, as always, gleefully welcomed.  Please submit these to the maintainer.

Additionally, there is currently one problem that may not ever be fixed. This problem occurs only in the prt program when the list of ignored or excluded deltas is present for a SID but that list is empty.  In this case SCCS prints the Included: or Excluded: line in its output (with no numbers afterward) and CSSC prints nothing.  Since ``fixing'' this problem would require a horrible kludge, this has not been done.  It is not expected that this will cause a problem for any users; if this is a problem for you, let the maintainer know and it will be fixed.

Unemulated Features
===================

There are some features of (some implementations of) the traditional SCCS suite which it may not be desirable to copy.

 1. If an SCCS file is created with the -i option, and it turns out to need encoding, then genuine SCCS seeks back to the start of the file and encodes it.  However, if the input file is not seekable, for example if it is a pipe, then this doesn't always work.  The SCCS file is then sometimes created containing only the initial part of the body, before the offending segment of the file.  The exit value of the admin program is nevertheless still zero.  Tests for this situation are in tests/binary/seeking.sh but these tests are only carried out if the program under test seems to be CSSC rather than the genuine SCCS suite.   The CSSC suite does not have this problem, and will always detect the need to encode the file, and will successfully complete the process (it does not try to seek on the input pipe).

 2. The normal configuration for CSSC is that it supports binary files and has no limit on line length in file with which it deals.  Both of these features may be different to the features of some version of SCCS with which you want to interoperate.  See Interoperability for more information on how to achieve better interoperability with other implementations of SCCS.

 3. If you have a hard link to an SCCS file, then SCCS programs would ``break'' the hard link because the SCCS file is rewritten.  For this reason, SCCS checks the link count on the file before using it.  The SCCS suite also does this.  While CSSC does this consistently, SCCS does not - for example the VAL program does not do this check.

There are also a small number of respects in which various implementations differ from each other; in such cases CSSC picks a suitable alternative; SCCS Version Differences.

Year 2000 Issues
****************

Primordial (but not current) versions of the genuine SCCS suite fail to work correctly in and after the year 2000.  The commands affected are get and prs.  Unix vendors have ensured that the version of SCCS that they currently ship works correctly in the year 2000.  Sun Microsystems, for example, state in their Year 2000 FAQ (http://www.sun.com/y2000/faq.html)

     * Does Sun see any problems with the source code control system (SCCS)? No, Sun has adopted the X/Open Commands and Utilities Issue 5 standard, the year 2000 compliant version of SCCS will not be affected by the end of century transition.  The X/Open standard states that old dates held in ("yy/mm/dd") format does not change in ``s.'' files, but the values ``yy'' which range from 69 -- 99 are to be interpreted as 1969 -- 1999 respectively. Values of ``yy'' which range from 00 -- 68 are to be interpreted as 2000 -- 2068 respectively.  This interpretation ensures that the year 2000 compliant version of SCCS will work at least to the year 2068.  By implementing X/Open's standard, Sun has ensured SCCS user's compatibility with other providers of the SCCS utility.  For more information please refer to: http://www.xopen.org/public/tech/base/year2000.html

     Copyright © 1994 -- 1997 Sun Microsystems, Inc., 901 San Antonio Road, Palo Alto, CA 94303 USA. All rights reserved.

The Good News
=============

Two-digit years are a problem in two places: firstly, within the actual SCCS files, and secondly within command-line options.  The two-digit year fields in the SCCS files are correctly dealt with according to the strategy mandated by X/Open.  The command-line options are also dealt with similarly.

CSSC provides an additional feature for your convenience.  If the argument to the -c option of get, prt, or prs contains more than twelve digits, the first two are understood to be the century part of the year.  For example, 971120193000 and 19971120193000 both represent exactly the same time (7:30 p.m. on November 20, 1997).  The fields of a date can be separated with other (non-digit) characters, and so 1997/11/20-19:30:00 also denotes the same time (but 1997/11/20 is an error because there are fewer than twelve digits).

Some versions of SCCS are not year 2000 compliant and write incorrect timestamps into SCCS files.  CSSC correctly understands the intended date, and will fix this problem when re-writing the file (see Bug-for-Bug Compatibility).

CSSC represents dates internally in a way that works for Gregorian dates up to at least the year 32767 AD on all systems.  Some countries didn't recognise the Gregorian calendar system until the early twentieth century but this of course is not really a problem now.  The useful life of SCCS is from 1969 until 2068.  Years are stored in two-digit form in SCCS files and so although CSSC has no such limits internally, it's not possible to indicate a year outside this range in an SCCS file if you want to retain compatibility with other implementations of SCCS.  All the CSSC programs will successfully work with any date in this range, all the way up to 2068, on all systems.

In this future, years after 2068 may be represented as four-digit fields, but CSSC doesn't do this yet.

The CSSC test suite (see The Test Suite) contains some test files which may be useful in determining the date range with which your usual SCCS implementation will cope.  These are in the directory tests/year-2000.

The Bad News
============

It's not all good news though.  When new deltas are created with the delta command, CSSC must consult the operating system to find the current date and time.  Some operating systems have a limited range of date representation.  For example, the development system I use for most of the work on CSSC can't report any date later than Tuesday Jan 19 03:14:07 2038 as the current time.  When running on such systems, CSSC will still be able to work with SCCS files containing dates after this, but activities involving the current time will not work correctly.

This date breakdown occurs most obviously with the date stamp that the delta program gives each delta in the SCCS file, but also with the commentary-change message of cdc and the default comment produced by admin when an SCCS file is created.

Year 2000 Summary
=================

To summarise, all reporting activities of CSSC will work correctly throughout the range of time representable in an SCCS file (that is, from 1969 to 2068 inclusive).  However, commands which modify SCCS files and need to add dates may fail earlier than this (but then again, may not, depending on your operating system).

Now that you know that whatever version of SCCS you are using has probably been fixed by the vendor, and that even if your vendor's SCCS implementation cannot be updated for some reason, CSSC is Year-2000 compliant and to an extent Year-2038 compliant, I'd like you to remember the conversion effort that this has saved you.  I'd also like to urge to to actually use that effort to convert your existing projects from SCCS to a more modern version control system, for example GNU CVS.  There are other considerations besides Year-2000 compliance, after all.  CSSC is not called ``Compatibly Stupid Source Control'' for nothing.

The Test Suite
**************

The test suite is the most important single component of the CSSC suite.  It ensures that ports to new platforms are working correctly, and that changes in one part of the suite don't accidentally break anything else.

The test suites cannot cover everything.  More are needed.  If you only ever contribute one thing to CSSC, make it a new test case.  This chapter explains how to run the test suite and also how to write new test cases.

Running the tests
=================

Running the test cases is quite simple.  Typically, you might do it after compiling but before installing CSSC.  After running ``configure'', you might compile CSSC with

     make

and test it with

     make check

The full test suite takes just over five minutes to run on a 486 running Linux.  If everything works correctly, you will see messages like:-

     cd tests && make all-tests
     make[1]: Entering directory `..../CSSC/compile-here/tests'
     cd ../lndir && make
     make[2]: Entering directory `..../CSSC/compile-here/lndir'
     make[2]: `lndir' is up to date.
     make[2]: Leaving directory `..../CSSC/compile-here/lndir'
     ../lndir/lndir ../../Master-Source/tests
     ../../Master-Source/tests/get:
     command-names: .././common/command-names
     test-common: .././common/test-common

     ...more messages from lndir...

     /bin/sh -ec 'cd admin && for i in *.sh ; \
     do \
     	/bin/sh $i || break; \
     done'
     C1...passed
     C2...passed
     .... more output ....
     C12...passed
     C13...passed
     PASS comment.sh:
     v1...passed
     .... more output ....
     b11...passed
     b12...passed
     PASS flags.sh:
     .... more output ....
     Tests passed.
     make[1]: Leaving directory `..../CSSC/compile-here/tests'

If something goes wrong you will see a ``FAIL'' message, which looks something like this:-

     C1...FAIL comment.sh C1: ../../admin -ifoo s.new.txt:
     Expected return value 0, got return value 1
     make[1]: *** [test-admin] Error 1
     make[1]: Leaving directory `..../CSSC/compile-here/tests'
     Tests failed.
     make: *** [all-tests] Error 2

The thing to remember is that when you run make check, the make program will print on the last line a message saying ``Error'' only if the tests have failed.

If the test suite does indicate that the tests have failed, please submit a bug report (see Reporting Bugs).  Please include in your bug report

  * The output of the test suite (you may find the Unix script program invaluable for this)

  * The contents of the directory containing the test that failed (if you compiled with separate source and object directories, I just want the one in the ``object'' directory).

  * As much information about your system as you think is useful, for example the names and versions of the operating system and compiler that you are using.

If you want to run just some of the tests, there are rules in the makefile for just running some of them.  For example, the tests in the directory tests/admin can be run with make test-admin. Each test directory is named after one of the CSSC programs.  This indicates which program the tests concentrate on verifying.  Inevitably these tests will use more than just one CSSC program; for example, most of the tests involve using admin to create a SCCS file in the first place.  However, the directory indicates which tool those tests concentrate on.

If is possible for a test to neither pass or fail, but just go wrong. This can happen when the test script comes upon something that prevents the test itself working correctly, for example, because it can't remove a temporary file or uudecode a built-in sample SCCS file.  When this happens you get output much like this:-

     $ sh flags.sh
     rm: foo: Permission denied
     flags.sh: Test could not be completed

The part before the colon (flags.sh) indicates which script could not be completed.  No further tests will be attempted. Diagnosing the problem may or may not be simple.  In this case, it's not hard; the problem is that the test suite is trying to clear away any temporary files but it can't remove the file ``foo'' (because the current directory was made read-only to force the test to miscarry, in this contrived case).  When the test suite miscarries like this and you can't find the problem, please follow the bug-reporting procedure (see Reporting Bugs), but please indicate that it is a miscarriage in the test suite rather than a concrete test failure.

Writing new test cases
======================

The test cases are really just shell scripts.  They are suitable for /bin/sh on most machines.  The procedure for running these is explained in Running the tests.  These shell scripts read in some common function definitions (mostly from tests/common/test-common) and then proceed to conduct the tests. This section explains those commands used in the test scripts that are not simply normal shell commands.  Normal shell commands like sed and grep are not described.

The best approach for writing new test scripts or just individual new test cases is to first think of some aspect that needs better test coverage, and then to write the test script, basing it on an existing script.  To make sure that your new tests are really checking for the right things, you can run them against an existing SCCS implementation other than CSSC.

Testing the Test Suite
----------------------

The best strategy for testing the CSSC test suite itself is to run it against a genuine edition of SCCS, if you have one available.   Before running make check, set the environment variable dir to point to the directory containing the programs to be tested; this should usually be /usr/sccs.

In many implementations of SCCS, some of the tools execute others (for example, delta often executes get to retrieve the previous version of the controlled file).  This means that to correctly test the test suite, your PATH environment variable should be set up to select the SCCS tools you want to test.  Here is an example of the correct way to set up the environment to test SCCS tools in /usr/ccs/bin :-

     dir=/usr/ccs/bin
     PATH=/usr/ccs/bin:$PATH
     export dir
     make check

When you are sure that the test script is expecting the correct behaviour from programs under test, you can then run it against CSSC.  After all, if you're going to set out writing your test by assuming that CSSC is correct in the area under test, of what value is the test?

docommand
---------

The docommand function runs a specified program, and checks its return value, standard output and error output against an expected version.  If any mismatch occurs, fail is called.  The docommand function is invoked with up to six arguments:-

     docommand [--silent] LABEL COMMAND RETVAL STDOUT STDERR

The docommand function normally prints the label to indicate what stage the current test script has reached, followed by ``done'' when it has finished.  The --silent option turns off this behaviour, so that if nothing goes wrong, no progress message is printed.  This is occasionally used for commands that have already been tested by a script and are known to work, but which must be repeated several times in order to make some other kind of test, which is yet to come.  I recommend you try to avoid using this option.

The other arguments to docommand are:-

label
     This is what is printed to indicate what is going on when the test starts.  If all goes according to plan, it is followed by ...done.

command
     This is the command to be executed, with all the required arguments.

retval
     This is the expected return value.  If COMMAND exits returning any other value, fail will be called.  If the test should not care about the return value, use IGNORE as RETVAL.

stdout
     This is the text expected on the standard output of COMMAND.  If the test should not care about the standard output, use IGNORE as STDOUT.

stderr
     This is the text expected on the error output of COMMAND.  If the test should not care about the error output, use IGNORE as STDERR.

This command will run admin with three arguments, and expect it to produce no output at all and return the value zero:-

     docommand C5 "${admin} -ifoo -yMyComment $s" 0 "" ""

This command does something similar, but the command is expected to fail, returning 1 as its exit status:-

     # We should not be able to admin -i if the s-file already exists.
     docommand I7 "${admin} -ifoo $s" 1 "" IGNORE

In the example above, the error messages produced by SCCS and CSSC are different, but both indicate the same thing.  However, since the messages are different, IGNORE is used.

The STDOUT and STDERR arguments are processed with the echo_nonl function, and so escape codes are valid and indeed heavily used:-

     # Test the -m (annotate SID) option with several deltas...
     docommand N4 "$get -p -m $s" 0 \
         "1.1\tline1\n1.1\tline2\n1.2\tline3\n" \
         IGNORE

remove
------

The remove function is for clearing up temporary files after tests have finished, and for making sure that no instance of a file that a test is supposed to create already exists before the test is made. Typical usage is this:-

     f=1test
     s=s.$f
     p=p.$f
     remove $f $s $p

The remove function is defined as:-

     remove () { rm -rf $* || miscarry Could not remove $* ; }

success
-------

The success function prints a message indicating that the current test script has passed, and exits successfully.   This is always done at the foot of a test script.

fail
----

If a test fails, it is usually because one of the docommand calls fails, and so direct calls to the fail function are rare. However, if you do want to call this function directly, you should supply as its argument a short description of what has gone wrong.  For example, the docommand function uses fail in the following way:-

     fail "$label: $1: Expected return value $2, got return value $rv"

echo_nonl
---------

The echo_nonl function outputs its argument, without a following newline.  Escape codes as for echo(1) are understood.  Depending on the actual flavour of system that the test suite is running on, this might internally use echo -n or echo -e .....\c.

Please do not use either the -n or -e options for echo(1) directly in test scripts, because they don't work in the same way on all machines.  The echo_nonl function is provided for this reason; therefore, please use it.  Please note also that while the printf(1) command may seem superior, it absolutely cannot be used because not all systems provide it.

Typical usage of echo_nonl might be:-

     echo_nonl Please wait while I finish what I am doing...
     # ...
     echo done

miscarry
--------

The miscarry function is used to indicate that while the test suite has not found a problem with the programs being tested, there has been some other kind of problem that prevents further testing.

Typical usage might be:-

     remove foo
     echo '%M%' > foo
     test `cat foo` = '%M%' || miscarry cannot create file foo.

real-thing
----------

The various implementations of SCCS vary in several different ways, but the CSSC test suite tries very hard to pass when run against any genuine implementation of SCCS unless it has a definite bug.  This means for example that although the CSSC version of admin -i will support automatic switch-over to binary mode for a file provided via stdin, and the test suite tests this, the same property is not required of SCCS itself.

The real-thing script checks if we are actually tesing a real implementation of SCCS.  It sets the environment variable TESTING_CSSC to true or false, depending on whether we are testing CSSC or not.

If you are really interested in whether the implementation being tested supports binary files or not, you should be using the config-data script instead.

need-prt
--------

The possible non-availability of prt is another thing that the CSSC test suite needs to know about in order to run successfully against all working versions of SCCS.  Some versions of SCCS lack the prt program.  For this reason, the tests for this tool (in the tests/prt directory) are skipped if prt is missing.  When writing test scripts, you should never use prt unless you are actually testing prt itself (you can almost always use prs instead).

If your test is specifically designed to test the functionality of prt itself on the other hand, just source need-prt before the first test.  The need-prt script will skip the remainder of the invoking test script if prt is missing.  You might use it like this, for example :-

     #! /bin/sh
     . ../common/test-common
     . ../common/need-prt
     s=s.testfile
     remove $s
     docommand e1 "${prt} $s" 1 IGNORE IGNORE
     success

Reporting Bugs
**************

If you find a bug in GNU CSSC, please report this via the CSSC bug tracking system at http://sourceforge.net/projects/CSSC. Please include the version number, which you can find by giving the option --version to any CSSC command.  Also include in your message the output that the program produced and the output you expected.  An s. file and instructions for reproducing the error are almost essential unless the bug is very trivial.  If you are unable to send the actual s-file itself due to confidentiality concerns, you can mask the contents by using the script mogrify.awk, which removes the contents of an SCCS file while preserving its structure.  You will need to use admin -z on the result in order to correct the checksum of the transformed version of the file.  If you do this, please make sure that you check that the problem still occurs with the transformed version of the file.

You may also find it helpful to join the mailing list.  See the file docs/mailing-list.txt for information about the mailing list.

If you have other questions, comments or suggestions about GNU CSSC, contact the maintainer via electronic mail to jay@gnu.org .

     [file gpl.texi not included]

BSD Code
********

The program sccs, its source code,  and its accompanying documentation are covered by the following license:-

     Copyright (C) 1998, 1999

     Free Software Foundation, Inc.  All rights reserved.

     Copyright (c) 1980, 1993

     The Regents of the University of California.  All rights reserved.

     Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:

      1. Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.

      2. Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.

      3. Neither the name of the University nor the names of its contributors may be used to endorse or promote products derived from this software without specific prior written permission.

     THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

The original version of the copyright notice above dates from 1993, as you can see.  However, since that time a change has been made to the BSD license by UCB itself.  This change is described on the following letter, which is available on the BSD FTP site in the file README.Impt.License.Change :-

     July 22, 1999

     To All Licensees, Distributors of Any Version of BSD:

     As you know, certain of the Berkeley Software Distribution (``BSD'') source code files require that further distributions of products containing all or portions of the software, acknowledge within their advertising materials that such products contain software developed by UC Berkeley and its contributors.

     Specifically, the provision reads:

          " * 3. All advertising materials mentioning features or use of this software
            *    must display the following acknowledgement:
            *    This product includes software developed by the University of
            *    California, Berkeley and its contributors."

     Effective immediately, licensees and distributors are no longer required to include the acknowledgement within advertising materials.  Accordingly, the foregoing paragraph of those BSD Unix files containing it is hereby deleted in its entirety.

     William Hoskins Director, Office of Technology Licensing University of California, Berkeley

This change has been made to the file COPYING.bsd which accompanies the BSD-derived code.

Glossary
********

archive
     In the context of SCCS and CSSC, This means the same as ``history file''.

branch
     Notionally, a branch is a parallel or forked stream of changes.  See ``branching''.

body
     The actual data within the version-controlled file is called the ``body'', though this is also sometimes used to refer to that part of the SCCS history file that contains data from the body of the controlled file (that is, information from the file as opposed to information about the file).

branching

     Multiple lines of development are called branches; a branch is created by editing a version of a file which already has a derived version (e.g. editing version 1.2 when version 1.3 already exists).

checkin comment
     The delta program asks for a checkin comment; this is a comment which summarised the nature of the change which has just been made to the file.

controlled file
     This is the (working copy of a) file which is version-controlled with an SCCS history file (that is, a file which is managed by SCCS or CSSC).

d-file
     See Filenames.

delta
     Each revision of a controlled file, as recorded in an SCCS file is called a delta.  This is also the name of the program used to check in such changes to the file.

delta table
     This is the section of the SCCS file which records information about each change that has been made (other than the actual contents of the file at that version).

excluded delta
     An excluded delta is one which was specified with the -x option to get.  See Options for get.

g-file
     See gotten file.

gotten file
     This is the working copy of the file; this is read-only unless the file has been checked out for editing.

history file
     Also known as an SCCS archive or ``s-file''.  When SCCS or CSSC is used to keep a historical record of previous versions of the contents of a file, the file in which this historical information is recorded is called the ``history file''.  Sometimes there are known as ``s-files'' or ``archives'' (though ``archive'' is more often used in relation to the ar and tar utilities).

ignored delta
     An ignored delta is one which was specified with the -g option to delta.  See Options for delta.

included delta
     An included delta is one which was specified with the -i option to get.  See Options for get.

keyword
     It is sometimes useful to include information in the gotten file about what its version number is and so on.  Since this information changes with each revision of the file, it makes sense for SCCS (or CSSC) to keep track of this information and place it in the gotten file accordingly.  If a file is checked out for editing, placeholders can be edited into the file which; these are later expanded when the file is checked out read-only.  See Keyword Substitution.  The same name is also sometimes used for the argument following the -d option for prs.  See Data Keywords for the -d option of prs.

level
     The second component of the SID.

MR number
     Modification Request numbers; if the v flag is set in the SCCS file, you will be prompted for ``MR numbers'' when you check in a new revision.  These are not used internally by CSSC but may be used to link changes to external things (for example bug report numbers).  See Options for delta.

p-file
     See Filenames.

q-file
     See Filenames.

release
     The first component of the SID.

revision
     A revision is a specific version of a file which is controlled with an SCCS history file.

sequence number
     The ``sequence number'' is a decimal number used within the SCCS history file to identify a particular revision (or delta) of the file.  These numbers are normally not user-visible (except in the output of prt and prs).  These are sometimes referred to as a ``seqno'' in order to distinguish them from the fourth component of a SID.

s-file
     The SCCS history file is sometimes referred to as the s-file.  See also Filenames.

SID
     Each revision of a file controlled with an SCCS history file is identified by a ``SID''.  This is a series of numbers separated by dots.  A complete SID always has either two components (for revisions which lie on the trunk) or four components (for revisions that lie on a branch).  Examples are 1.1, 1.2 (which both lie on the trunk), 1.3.1.1, 1.3.1.2 (which both lie on a branch) and 1.3.2.1 (which lies on a different branch).  The four components of the SID are, left to right, the release, the level, the branch and the sequence number.  See also sequence number, above.

trunk
     The trunk consists of those deltas within a history file which do not lie on branches; trunk revisions have only two components in their SID.  Normally these are the main sequence of changes to the file.

x-file
     See Filenames.

z-file
     See Filenames.