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

   Copyright (C) 1997, 1998, 1999, 2000, 2001, 2002,
2003, 2004, 2005, 2007, 2008 Free Software Foundation, Inc.

   Permission is granted to copy, distribute and/or modify this document
under the terms of the GNU Free Documentation License, Version 1.2 or
any later version published by the Free Software Foundation; with no
Invariant Sections, with no Front-Cover Texts, and with no Back-Cover
Texts.  A copy of the license is included in the section entitled "GNU
Free Documentation License."

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

   This is edition 1.09, for CSSC Version 1.1.1.

1 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? (cvs).
See also the manual pages for RCS.

   GNU CSSC is published under the GNU General Public License, which is
designed to protect your rights, as the user of this program.  You have
the right to modify this program, and distribute it.  You also have
responsibilities to those to whom you distribute copies, as detailed in
the license.  See GNU General Public License.

   GNU CSSC was originally based on the public-domain package MySC,
which was written by Ross Ridge.  The enhancement work was done by James
Youngman.

   The `sccs' program itself and its accompanying documentation
`sccs.me' and `sccs.1' were written by Eric Allman, and are covered by
the BSD license (see BSD Code).

2 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 (emacs).

   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.

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

3.1 `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).
     When using `admin -dl' to unlock a release, you need to specify
     which release  should be unlocked.  For example `admin -dla'
     unlocks all releases, while `admin -dl2' unlocks only release 2.
     This means that `admin -dl' will do nothing, since no release was
     specified.  If all releases are locked, attempting to unlock just
     one release will have no effect.

`-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. See
     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.

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

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

3.2 `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.

3.3 `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.

3.4 `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.

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

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

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

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

3.5.2 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 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'
     Generates a delta summary file in the current working directory.
     The name of the file is `l.foo' where `foo' is the name that would
     normally be used for the gotten file.  The name of the delta
     summary file is not affected by the `-G' option.  The delta
     summary file is similar in content to the output of `prt', though
     it contains less information.

`-lp'
     This is obsolete; use `-L' instead.

`-L'
     Generate a delta summary as for the `-l' option, but print it on
     stdout instead of creating a file.  If `-L' and `-p' are both
     specified, the delta summary is printed first.

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

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

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

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

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

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

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

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

3.7 `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.

3.8 `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.

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

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

3.8.3 Data Keywords for the `-d' option of `prs'
------------------------------------------------

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

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

3.9 `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.

3.9.1 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

The default output contains slightly more information than the output
of `get -L'.  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.

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

3.9.3 `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.

3.10 `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.

3.11 `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.

3.12 `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/'.

3.13 `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.

3.14 `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.

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

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

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

3.15.2 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.  See Flags.

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

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

3.16 `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.

3.16.1 Options for `what'
-------------------------

`what [-s] [-V] file [file ...]'
`-s'
     Exit successfully after finding the first string.

`-V'
     Show version information for `what'.

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

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

`l.'
     The delta summary file created by `get -l'.  Unlike the other
     files in this table, the l-file is created in the current
     directory.

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

   Except for the l-file, all of the temporary files in the above table
are created in the same directory as the s-file.  The l-file is created
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.

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

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

5.2 The Header
==============

There are several parts to the SCCS file header:-

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

5.2.2 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

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

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

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

5.2.6 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

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

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

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

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

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

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

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

6.6 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".

6.7 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".

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

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

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

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

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

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

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

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

7 Environment Variables
***********************

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

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

7.2 Configuration Variables
===========================

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

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

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

7.3 Other Variables
===================

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

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

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

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

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

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

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

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

8.1 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://savannah.gnu.org/bugs/?group=cssc'.  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.

8.2 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://savannah.gnu.org/bugs/?group=cssc'.

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.

8.3 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; see SCCS Version Differences.

9 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 (C) 1994 - 1997 Sun Microsystems, Inc., 901 San Antonio
     Road, Palo Alto, CA 94303 USA.  All rights reserved.

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

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

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

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

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

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

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

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

10.2.2 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

10.2.3 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 $* ; }

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

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

10.2.6 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

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

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

10.2.9 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

11 Reporting Bugs
*****************

If you find a bug in GNU `CSSC', please report this via the CSSC bug
tracking system at `http://savannah.gnu.org/bugs/?group=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' .

GNU General Public License
**************************

                        Version 3, 29 June 2007

     Copyright (C) 2007 Free Software Foundation, Inc. `http://fsf.org/'

     Everyone is permitted to copy and distribute verbatim copies of this
     license document, but changing it is not allowed.

Preamble
========

The GNU General Public License is a free, copyleft license for software
and other kinds of works.

   The licenses for most software and other practical works are designed
to take away your freedom to share and change the works.  By contrast,
the GNU General Public License is intended to guarantee your freedom to
share and change all versions of a program--to make sure it remains
free software for all its users.  We, the Free Software Foundation, use
the GNU General Public License for most of our software; it applies
also to any other work released this way by its authors.  You can apply
it to your programs, too.

   When we speak of free software, we are referring to freedom, not
price.  Our General Public Licenses are designed to make sure that you
have the freedom to distribute copies of free software (and charge for
them if you wish), that you receive source code or can get it if you
want it, that you can change the software or use pieces of it in new
free programs, and that you know you can do these things.

   To protect your rights, we need to prevent others from denying you
these rights or asking you to surrender the rights.  Therefore, you
have certain responsibilities if you distribute copies of the software,
or if you modify it: responsibilities to respect the freedom of others.

   For example, if you distribute copies of such a program, whether
gratis or for a fee, you must pass on to the recipients the same
freedoms that you received.  You must make sure that they, too, receive
or can get the source code.  And you must show them these terms so they
know their rights.

   Developers that use the GNU GPL protect your rights with two steps:
(1) assert copyright on the software, and (2) offer you this License
giving you legal permission to copy, distribute and/or modify it.

   For the developers' and authors' protection, the GPL clearly explains
that there is no warranty for this free software.  For both users' and
authors' sake, the GPL requires that modified versions be marked as
changed, so that their problems will not be attributed erroneously to
authors of previous versions.

   Some devices are designed to deny users access to install or run
modified versions of the software inside them, although the
manufacturer can do so.  This is fundamentally incompatible with the
aim of protecting users' freedom to change the software.  The
systematic pattern of such abuse occurs in the area of products for
individuals to use, which is precisely where it is most unacceptable.
Therefore, we have designed this version of the GPL to prohibit the
practice for those products.  If such problems arise substantially in
other domains, we stand ready to extend this provision to those domains
in future versions of the GPL, as needed to protect the freedom of
users.

   Finally, every program is threatened constantly by software patents.
States should not allow patents to restrict development and use of
software on general-purpose computers, but in those that do, we wish to
avoid the special danger that patents applied to a free program could
make it effectively proprietary.  To prevent this, the GPL assures that
patents cannot be used to render the program non-free.

   The precise terms and conditions for copying, distribution and
modification follow.

TERMS AND CONDITIONS
====================

  0. Definitions.

     "This License" refers to version 3 of the GNU General Public
     License.

     "Copyright" also means copyright-like laws that apply to other
     kinds of works, such as semiconductor masks.

     "The Program" refers to any copyrightable work licensed under this
     License.  Each licensee is addressed as "you".  "Licensees" and
     "recipients" may be individuals or organizations.

     To "modify" a work means to copy from or adapt all or part of the
     work in a fashion requiring copyright permission, other than the
     making of an exact copy.  The resulting work is called a "modified
     version" of the earlier work or a work "based on" the earlier work.

     A "covered work" means either the unmodified Program or a work
     based on the Program.

     To "propagate" a work means to do anything with it that, without
     permission, would make you directly or secondarily liable for
     infringement under applicable copyright law, except executing it
     on a computer or modifying a private copy.  Propagation includes
     copying, distribution (with or without modification), making
     available to the public, and in some countries other activities as
     well.

     To "convey" a work means any kind of propagation that enables other
     parties to make or receive copies.  Mere interaction with a user
     through a computer network, with no transfer of a copy, is not
     conveying.

     An interactive user interface displays "Appropriate Legal Notices"
     to the extent that it includes a convenient and prominently visible
     feature that (1) displays an appropriate copyright notice, and (2)
     tells the user that there is no warranty for the work (except to
     the extent that warranties are provided), that licensees may
     convey the work under this License, and how to view a copy of this
     License.  If the interface presents a list of user commands or
     options, such as a menu, a prominent item in the list meets this
     criterion.

  1. Source Code.

     The "source code" for a work means the preferred form of the work
     for making modifications to it.  "Object code" means any
     non-source form of a work.

     A "Standard Interface" means an interface that either is an
     official standard defined by a recognized standards body, or, in
     the case of interfaces specified for a particular programming
     language, one that is widely used among developers working in that
     language.

     The "System Libraries" of an executable work include anything,
     other than the work as a whole, that (a) is included in the normal
     form of packaging a Major Component, but which is not part of that
     Major Component, and (b) serves only to enable use of the work
     with that Major Component, or to implement a Standard Interface
     for which an implementation is available to the public in source
     code form.  A "Major Component", in this context, means a major
     essential component (kernel, window system, and so on) of the
     specific operating system (if any) on which the executable work
     runs, or a compiler used to produce the work, or an object code
     interpreter used to run it.

     The "Corresponding Source" for a work in object code form means all
     the source code needed to generate, install, and (for an executable
     work) run the object code and to modify the work, including
     scripts to control those activities.  However, it does not include
     the work's System Libraries, or general-purpose tools or generally
     available free programs which are used unmodified in performing
     those activities but which are not part of the work.  For example,
     Corresponding Source includes interface definition files
     associated with source files for the work, and the source code for
     shared libraries and dynamically linked subprograms that the work
     is specifically designed to require, such as by intimate data
     communication or control flow between those subprograms and other
     parts of the work.

     The Corresponding Source need not include anything that users can
     regenerate automatically from other parts of the Corresponding
     Source.

     The Corresponding Source for a work in source code form is that
     same work.

  2. Basic Permissions.

     All rights granted under this License are granted for the term of
     copyright on the Program, and are irrevocable provided the stated
     conditions are met.  This License explicitly affirms your unlimited
     permission to run the unmodified Program.  The output from running
     a covered work is covered by this License only if the output,
     given its content, constitutes a covered work.  This License
     acknowledges your rights of fair use or other equivalent, as
     provided by copyright law.

     You may make, run and propagate covered works that you do not
     convey, without conditions so long as your license otherwise
     remains in force.  You may convey covered works to others for the
     sole purpose of having them make modifications exclusively for
     you, or provide you with facilities for running those works,
     provided that you comply with the terms of this License in
     conveying all material for which you do not control copyright.
     Those thus making or running the covered works for you must do so
     exclusively on your behalf, under your direction and control, on
     terms that prohibit them from making any copies of your
     copyrighted material outside their relationship with you.

     Conveying under any other circumstances is permitted solely under
     the conditions stated below.  Sublicensing is not allowed; section
     10 makes it unnecessary.

  3. Protecting Users' Legal Rights From Anti-Circumvention Law.

     No covered work shall be deemed part of an effective technological
     measure under any applicable law fulfilling obligations under
     article 11 of the WIPO copyright treaty adopted on 20 December
     1996, or similar laws prohibiting or restricting circumvention of
     such measures.

     When you convey a covered work, you waive any legal power to forbid
     circumvention of technological measures to the extent such
     circumvention is effected by exercising rights under this License
     with respect to the covered work, and you disclaim any intention
     to limit operation or modification of the work as a means of
     enforcing, against the work's users, your or third parties' legal
     rights to forbid circumvention of technological measures.

  4. Conveying Verbatim Copies.

     You may convey verbatim copies of the Program's source code as you
     receive it, in any medium, provided that you conspicuously and
     appropriately publish on each copy an appropriate copyright notice;
     keep intact all notices stating that this License and any
     non-permissive terms added in accord with section 7 apply to the
     code; keep intact all notices of the absence of any warranty; and
     give all recipients a copy of this License along with the Program.

     You may charge any price or no price for each copy that you convey,
     and you may offer support or warranty protection for a fee.

  5. Conveying Modified Source Versions.

     You may convey a work based on the Program, or the modifications to
     produce it from the Program, in the form of source code under the
     terms of section 4, provided that you also meet all of these
     conditions:

       a. The work must carry prominent notices stating that you
          modified it, and giving a relevant date.

       b. The work must carry prominent notices stating that it is
          released under this License and any conditions added under
          section 7.  This requirement modifies the requirement in
          section 4 to "keep intact all notices".

       c. You must license the entire work, as a whole, under this
          License to anyone who comes into possession of a copy.  This
          License will therefore apply, along with any applicable
          section 7 additional terms, to the whole of the work, and all
          its parts, regardless of how they are packaged.  This License
          gives no permission to license the work in any other way, but
          it does not invalidate such permission if you have separately
          received it.

       d. If the work has interactive user interfaces, each must display
          Appropriate Legal Notices; however, if the Program has
          interactive interfaces that do not display Appropriate Legal
          Notices, your work need not make them do so.

     A compilation of a covered work with other separate and independent
     works, which are not by their nature extensions of the covered
     work, and which are not combined with it such as to form a larger
     program, in or on a volume of a storage or distribution medium, is
     called an "aggregate" if the compilation and its resulting
     copyright are not used to limit the access or legal rights of the
     compilation's users beyond what the individual works permit.
     Inclusion of a covered work in an aggregate does not cause this
     License to apply to the other parts of the aggregate.

  6. Conveying Non-Source Forms.

     You may convey a covered work in object code form under the terms
     of sections 4 and 5, provided that you also convey the
     machine-readable Corresponding Source under the terms of this
     License, in one of these ways:

       a. Convey the object code in, or embodied in, a physical product
          (including a physical distribution medium), accompanied by the
          Corresponding Source fixed on a durable physical medium
          customarily used for software interchange.

       b. Convey the object code in, or embodied in, a physical product
          (including a physical distribution medium), accompanied by a
          written offer, valid for at least three years and valid for
          as long as you offer spare parts or customer support for that
          product model, to give anyone who possesses the object code
          either (1) a copy of the Corresponding Source for all the
          software in the product that is covered by this License, on a
          durable physical medium customarily used for software
          interchange, for a price no more than your reasonable cost of
          physically performing this conveying of source, or (2) access
          to copy the Corresponding Source from a network server at no
          charge.

       c. Convey individual copies of the object code with a copy of
          the written offer to provide the Corresponding Source.  This
          alternative is allowed only occasionally and noncommercially,
          and only if you received the object code with such an offer,
          in accord with subsection 6b.

       d. Convey the object code by offering access from a designated
          place (gratis or for a charge), and offer equivalent access
          to the Corresponding Source in the same way through the same
          place at no further charge.  You need not require recipients
          to copy the Corresponding Source along with the object code.
          If the place to copy the object code is a network server, the
          Corresponding Source may be on a different server (operated
          by you or a third party) that supports equivalent copying
          facilities, provided you maintain clear directions next to
          the object code saying where to find the Corresponding Source.
          Regardless of what server hosts the Corresponding Source, you
          remain obligated to ensure that it is available for as long
          as needed to satisfy these requirements.

       e. Convey the object code using peer-to-peer transmission,
          provided you inform other peers where the object code and
          Corresponding Source of the work are being offered to the
          general public at no charge under subsection 6d.

     A separable portion of the object code, whose source code is
     excluded from the Corresponding Source as a System Library, need
     not be included in conveying the object code work.

     A "User Product" is either (1) a "consumer product", which means
     any tangible personal property which is normally used for personal,
     family, or household purposes, or (2) anything designed or sold for
     incorporation into a dwelling.  In determining whether a product
     is a consumer product, doubtful cases shall be resolved in favor of
     coverage.  For a particular product received by a particular user,
     "normally used" refers to a typical or common use of that class of
     product, regardless of the status of the particular user or of the
     way in which the particular user actually uses, or expects or is
     expected to use, the product.  A product is a consumer product
     regardless of whether the product has substantial commercial,
     industrial or non-consumer uses, unless such uses represent the
     only significant mode of use of the product.

     "Installation Information" for a User Product means any methods,
     procedures, authorization keys, or other information required to
     install and execute modified versions of a covered work in that
     User Product from a modified version of its Corresponding Source.
     The information must suffice to ensure that the continued
     functioning of the modified object code is in no case prevented or
     interfered with solely because modification has been made.

     If you convey an object code work under this section in, or with,
     or specifically for use in, a User Product, and the conveying
     occurs as part of a transaction in which the right of possession
     and use of the User Product is transferred to the recipient in
     perpetuity or for a fixed term (regardless of how the transaction
     is characterized), the Corresponding Source conveyed under this
     section must be accompanied by the Installation Information.  But
     this requirement does not apply if neither you nor any third party
     retains the ability to install modified object code on the User
     Product (for example, the work has been installed in ROM).

     The requirement to provide Installation Information does not
     include a requirement to continue to provide support service,
     warranty, or updates for a work that has been modified or
     installed by the recipient, or for the User Product in which it
     has been modified or installed.  Access to a network may be denied
     when the modification itself materially and adversely affects the
     operation of the network or violates the rules and protocols for
     communication across the network.

     Corresponding Source conveyed, and Installation Information
     provided, in accord with this section must be in a format that is
     publicly documented (and with an implementation available to the
     public in source code form), and must require no special password
     or key for unpacking, reading or copying.

  7. Additional Terms.

     "Additional permissions" are terms that supplement the terms of
     this License by making exceptions from one or more of its
     conditions.  Additional permissions that are applicable to the
     entire Program shall be treated as though they were included in
     this License, to the extent that they are valid under applicable
     law.  If additional permissions apply only to part of the Program,
     that part may be used separately under those permissions, but the
     entire Program remains governed by this License without regard to
     the additional permissions.

     When you convey a copy of a covered work, you may at your option
     remove any additional permissions from that copy, or from any part
     of it.  (Additional permissions may be written to require their own
     removal in certain cases when you modify the work.)  You may place
     additional permissions on material, added by you to a covered work,
     for which you have or can give appropriate copyright permission.

     Notwithstanding any other provision of this License, for material
     you add to a covered work, you may (if authorized by the copyright
     holders of that material) supplement the terms of this License
     with terms:

       a. Disclaiming warranty or limiting liability differently from
          the terms of sections 15 and 16 of this License; or

       b. Requiring preservation of specified reasonable legal notices
          or author attributions in that material or in the Appropriate
          Legal Notices displayed by works containing it; or

       c. Prohibiting misrepresentation of the origin of that material,
          or requiring that modified versions of such material be
          marked in reasonable ways as different from the original
          version; or

       d. Limiting the use for publicity purposes of names of licensors
          or authors of the material; or

       e. Declining to grant rights under trademark law for use of some
          trade names, trademarks, or service marks; or

       f. Requiring indemnification of licensors and authors of that
          material by anyone who conveys the material (or modified
          versions of it) with contractual assumptions of liability to
          the recipient, for any liability that these contractual
          assumptions directly impose on those licensors and authors.

     All other non-permissive additional terms are considered "further
     restrictions" within the meaning of section 10.  If the Program as
     you received it, or any part of it, contains a notice stating that
     it is governed by this License along with a term that is a further
     restriction, you may remove that term.  If a license document
     contains a further restriction but permits relicensing or
     conveying under this License, you may add to a covered work
     material governed by the terms of that license document, provided
     that the further restriction does not survive such relicensing or
     conveying.

     If you add terms to a covered work in accord with this section, you
     must place, in the relevant source files, a statement of the
     additional terms that apply to those files, or a notice indicating
     where to find the applicable terms.

     Additional terms, permissive or non-permissive, may be stated in
     the form of a separately written license, or stated as exceptions;
     the above requirements apply either way.

  8. Termination.

     You may not propagate or modify a covered work except as expressly
     provided under this License.  Any attempt otherwise to propagate or
     modify it is void, and will automatically terminate your rights
     under this License (including any patent licenses granted under
     the third paragraph of section 11).

     However, if you cease all violation of this License, then your
     license from a particular copyright holder is reinstated (a)
     provisionally, unless and until the copyright holder explicitly
     and finally terminates your license, and (b) permanently, if the
     copyright holder fails to notify you of the violation by some
     reasonable means prior to 60 days after the cessation.

     Moreover, your license from a particular copyright holder is
     reinstated permanently if the copyright holder notifies you of the
     violation by some reasonable means, this is the first time you have
     received notice of violation of this License (for any work) from
     that copyright holder, and you cure the violation prior to 30 days
     after your receipt of the notice.

     Termination of your rights under this section does not terminate
     the licenses of parties who have received copies or rights from
     you under this License.  If your rights have been terminated and
     not permanently reinstated, you do not qualify to receive new
     licenses for the same material under section 10.

  9. Acceptance Not Required for Having Copies.

     You are not required to accept this License in order to receive or
     run a copy of the Program.  Ancillary propagation of a covered work
     occurring solely as a consequence of using peer-to-peer
     transmission to receive a copy likewise does not require
     acceptance.  However, nothing other than this License grants you
     permission to propagate or modify any covered work.  These actions
     infringe copyright if you do not accept this License.  Therefore,
     by modifying or propagating a covered work, you indicate your
     acceptance of this License to do so.

 10. Automatic Licensing of Downstream Recipients.

     Each time you convey a covered work, the recipient automatically
     receives a license from the original licensors, to run, modify and
     propagate that work, subject to this License.  You are not
     responsible for enforcing compliance by third parties with this
     License.

     An "entity transaction" is a transaction transferring control of an
     organization, or substantially all assets of one, or subdividing an
     organization, or merging organizations.  If propagation of a
     covered work results from an entity transaction, each party to that
     transaction who receives a copy of the work also receives whatever
     licenses to the work the party's predecessor in interest had or
     could give under the previous paragraph, plus a right to
     possession of the Corresponding Source of the work from the
     predecessor in interest, if the predecessor has it or can get it
     with reasonable efforts.

     You may not impose any further restrictions on the exercise of the
     rights granted or affirmed under this License.  For example, you
     may not impose a license fee, royalty, or other charge for
     exercise of rights granted under this License, and you may not
     initiate litigation (including a cross-claim or counterclaim in a
     lawsuit) alleging that any patent claim is infringed by making,
     using, selling, offering for sale, or importing the Program or any
     portion of it.

 11. Patents.

     A "contributor" is a copyright holder who authorizes use under this
     License of the Program or a work on which the Program is based.
     The work thus licensed is called the contributor's "contributor
     version".

     A contributor's "essential patent claims" are all patent claims
     owned or controlled by the contributor, whether already acquired or
     hereafter acquired, that would be infringed by some manner,
     permitted by this License, of making, using, or selling its
     contributor version, but do not include claims that would be
     infringed only as a consequence of further modification of the
     contributor version.  For purposes of this definition, "control"
     includes the right to grant patent sublicenses in a manner
     consistent with the requirements of this License.

     Each contributor grants you a non-exclusive, worldwide,
     royalty-free patent license under the contributor's essential
     patent claims, to make, use, sell, offer for sale, import and
     otherwise run, modify and propagate the contents of its
     contributor version.

     In the following three paragraphs, a "patent license" is any
     express agreement or commitment, however denominated, not to
     enforce a patent (such as an express permission to practice a
     patent or covenant not to sue for patent infringement).  To
     "grant" such a patent license to a party means to make such an
     agreement or commitment not to enforce a patent against the party.

     If you convey a covered work, knowingly relying on a patent
     license, and the Corresponding Source of the work is not available
     for anyone to copy, free of charge and under the terms of this
     License, through a publicly available network server or other
     readily accessible means, then you must either (1) cause the
     Corresponding Source to be so available, or (2) arrange to deprive
     yourself of the benefit of the patent license for this particular
     work, or (3) arrange, in a manner consistent with the requirements
     of this License, to extend the patent license to downstream
     recipients.  "Knowingly relying" means you have actual knowledge
     that, but for the patent license, your conveying the covered work
     in a country, or your recipient's use of the covered work in a
     country, would infringe one or more identifiable patents in that
     country that you have reason to believe are valid.

     If, pursuant to or in connection with a single transaction or
     arrangement, you convey, or propagate by procuring conveyance of, a
     covered work, and grant a patent license to some of the parties
     receiving the covered work authorizing them to use, propagate,
     modify or convey a specific copy of the covered work, then the
     patent license you grant is automatically extended to all
     recipients of the covered work and works based on it.

     A patent license is "discriminatory" if it does not include within
     the scope of its coverage, prohibits the exercise of, or is
     conditioned on the non-exercise of one or more of the rights that
     are specifically granted under this License.  You may not convey a
     covered work if you are a party to an arrangement with a third
     party that is in the business of distributing software, under
     which you make payment to the third party based on the extent of
     your activity of conveying the work, and under which the third
     party grants, to any of the parties who would receive the covered
     work from you, a discriminatory patent license (a) in connection
     with copies of the covered work conveyed by you (or copies made
     from those copies), or (b) primarily for and in connection with
     specific products or compilations that contain the covered work,
     unless you entered into that arrangement, or that patent license
     was granted, prior to 28 March 2007.

     Nothing in this License shall be construed as excluding or limiting
     any implied license or other defenses to infringement that may
     otherwise be available to you under applicable patent law.

 12. No Surrender of Others' Freedom.

     If conditions are imposed on you (whether by court order,
     agreement or otherwise) that contradict the conditions of this
     License, they do not excuse you from the conditions of this
     License.  If you cannot convey a covered work so as to satisfy
     simultaneously your obligations under this License and any other
     pertinent obligations, then as a consequence you may not convey it
     at all.  For example, if you agree to terms that obligate you to
     collect a royalty for further conveying from those to whom you
     convey the Program, the only way you could satisfy both those
     terms and this License would be to refrain entirely from conveying
     the Program.

 13. Use with the GNU Affero General Public License.

     Notwithstanding any other provision of this License, you have
     permission to link or combine any covered work with a work licensed
     under version 3 of the GNU Affero General Public License into a
     single combined work, and to convey the resulting work.  The terms
     of this License will continue to apply to the part which is the
     covered work, but the special requirements of the GNU Affero
     General Public License, section 13, concerning interaction through
     a network will apply to the combination as such.

 14. Revised Versions of this License.

     The Free Software Foundation may publish revised and/or new
     versions of the GNU General Public License from time to time.
     Such new versions will be similar in spirit to the present
     version, but may differ in detail to address new problems or
     concerns.

     Each version is given a distinguishing version number.  If the
     Program specifies that a certain numbered version of the GNU
     General Public License "or any later version" applies to it, you
     have the option of following the terms and conditions either of
     that numbered version or of any later version published by the
     Free Software Foundation.  If the Program does not specify a
     version number of the GNU General Public License, you may choose
     any version ever published by the Free Software Foundation.

     If the Program specifies that a proxy can decide which future
     versions of the GNU General Public License can be used, that
     proxy's public statement of acceptance of a version permanently
     authorizes you to choose that version for the Program.

     Later license versions may give you additional or different
     permissions.  However, no additional obligations are imposed on any
     author or copyright holder as a result of your choosing to follow a
     later version.

 15. Disclaimer of Warranty.

     THERE IS NO WARRANTY FOR THE PROGRAM, TO THE EXTENT PERMITTED BY
     APPLICABLE LAW.  EXCEPT WHEN OTHERWISE STATED IN WRITING THE
     COPYRIGHT HOLDERS AND/OR OTHER PARTIES PROVIDE THE PROGRAM "AS IS"
     WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESSED OR IMPLIED,
     INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF
     MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE.  THE ENTIRE
     RISK AS TO THE QUALITY AND PERFORMANCE OF THE PROGRAM IS WITH YOU.
     SHOULD THE PROGRAM PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL
     NECESSARY SERVICING, REPAIR OR CORRECTION.

 16. Limitation of Liability.

     IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN
     WRITING WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MODIFIES
     AND/OR CONVEYS THE PROGRAM AS PERMITTED ABOVE, BE LIABLE TO YOU
     FOR DAMAGES, INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL OR
     CONSEQUENTIAL DAMAGES ARISING OUT OF THE USE OR INABILITY TO USE
     THE PROGRAM (INCLUDING BUT NOT LIMITED TO LOSS OF DATA OR DATA
     BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU OR THIRD
     PARTIES OR A FAILURE OF THE PROGRAM TO OPERATE WITH ANY OTHER
     PROGRAMS), EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF
     THE POSSIBILITY OF SUCH DAMAGES.

 17. Interpretation of Sections 15 and 16.

     If the disclaimer of warranty and limitation of liability provided
     above cannot be given local legal effect according to their terms,
     reviewing courts shall apply local law that most closely
     approximates an absolute waiver of all civil liability in
     connection with the Program, unless a warranty or assumption of
     liability accompanies a copy of the Program in return for a fee.

END OF TERMS AND CONDITIONS
===========================

How to Apply These Terms to Your New Programs
=============================================

If you develop a new program, and you want it to be of the greatest
possible use to the public, the best way to achieve this is to make it
free software which everyone can redistribute and change under these
terms.

   To do so, attach the following notices to the program.  It is safest
to attach them to the start of each source file to most effectively
state the exclusion of warranty; and each file should have at least the
"copyright" line and a pointer to where the full notice is found.

     ONE LINE TO GIVE THE PROGRAM'S NAME AND A BRIEF IDEA OF WHAT IT DOES.
     Copyright (C) YEAR NAME OF AUTHOR

     This program is free software: you can redistribute it and/or modify
     it under the terms of the GNU General Public License as published by
     the Free Software Foundation, either version 3 of the License, or (at
     your option) any later version.

     This program is distributed in the hope that it will be useful, but
     WITHOUT ANY WARRANTY; without even the implied warranty of
     MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
     General Public License for more details.

     You should have received a copy of the GNU General Public License
     along with this program.  If not, see `http://www.gnu.org/licenses/'.

   Also add information on how to contact you by electronic and paper
mail.

   If the program does terminal interaction, make it output a short
notice like this when it starts in an interactive mode:

     PROGRAM Copyright (C) YEAR NAME OF AUTHOR
     This program comes with ABSOLUTELY NO WARRANTY; for details type `show w'.
     This is free software, and you are welcome to redistribute it
     under certain conditions; type `show c' for details.

   The hypothetical commands `show w' and `show c' should show the
appropriate parts of the General Public License.  Of course, your
program's commands might be different; for a GUI interface, you would
use an "about box".

   You should also get your employer (if you work as a programmer) or
school, if any, to sign a "copyright disclaimer" for the program, if
necessary.  For more information on this, and how to apply and follow
the GNU GPL, see `http://www.gnu.org/licenses/'.

   The GNU General Public License does not permit incorporating your
program into proprietary programs.  If your program is a subroutine
library, you may consider it more useful to permit linking proprietary
applications with the library.  If this is what you want to do, use the
GNU Lesser General Public License instead of this License.  But first,
please read `http://www.gnu.org/philosophy/why-not-lgpl.html'.

GNU Free Documentation License
******************************

                      Version 1.2, November 2002

     Copyright (C) 2000,2001,2002 Free Software Foundation, Inc.
     51 Franklin St, Fifth Floor, Boston, MA  02110-1301, USA

     Everyone is permitted to copy and distribute verbatim copies
     of this license document, but changing it is not allowed.

  0. PREAMBLE

     The purpose of this License is to make a manual, textbook, or other
     functional and useful document "free" in the sense of freedom: to
     assure everyone the effective freedom to copy and redistribute it,
     with or without modifying it, either commercially or
     noncommercially.  Secondarily, this License preserves for the
     author and publisher a way to get credit for their work, while not
     being considered responsible for modifications made by others.

     This License is a kind of "copyleft", which means that derivative
     works of the document must themselves be free in the same sense.
     It complements the GNU General Public License, which is a copyleft
     license designed for free software.

     We have designed this License in order to use it for manuals for
     free software, because free software needs free documentation: a
     free program should come with manuals providing the same freedoms
     that the software does.  But this License is not limited to
     software manuals; it can be used for any textual work, regardless
     of subject matter or whether it is published as a printed book.
     We recommend this License principally for works whose purpose is
     instruction or reference.

  1. APPLICABILITY AND DEFINITIONS

     This License applies to any manual or other work, in any medium,
     that contains a notice placed by the copyright holder saying it
     can be distributed under the terms of this License.  Such a notice
     grants a world-wide, royalty-free license, unlimited in duration,
     to use that work under the conditions stated herein.  The
     "Document", below, refers to any such manual or work.  Any member
     of the public is a licensee, and is addressed as "you".  You
     accept the license if you copy, modify or distribute the work in a
     way requiring permission under copyright law.

     A "Modified Version" of the Document means any work containing the
     Document or a portion of it, either copied verbatim, or with
     modifications and/or translated into another language.

     A "Secondary Section" is a named appendix or a front-matter section
     of the Document that deals exclusively with the relationship of the
     publishers or authors of the Document to the Document's overall
     subject (or to related matters) and contains nothing that could
     fall directly within that overall subject.  (Thus, if the Document
     is in part a textbook of mathematics, a Secondary Section may not
     explain any mathematics.)  The relationship could be a matter of
     historical connection with the subject or with related matters, or
     of legal, commercial, philosophical, ethical or political position
     regarding them.

     The "Invariant Sections" are certain Secondary Sections whose
     titles are designated, as being those of Invariant Sections, in
     the notice that says that the Document is released under this
     License.  If a section does not fit the above definition of
     Secondary then it is not allowed to be designated as Invariant.
     The Document may contain zero Invariant Sections.  If the Document
     does not identify any Invariant Sections then there are none.

     The "Cover Texts" are certain short passages of text that are
     listed, as Front-Cover Texts or Back-Cover Texts, in the notice
     that says that the Document is released under this License.  A
     Front-Cover Text may be at most 5 words, and a Back-Cover Text may
     be at most 25 words.

     A "Transparent" copy of the Document means a machine-readable copy,
     represented in a format whose specification is available to the
     general public, that is suitable for revising the document
     straightforwardly with generic text editors or (for images
     composed of pixels) generic paint programs or (for drawings) some
     widely available drawing editor, and that is suitable for input to
     text formatters or for automatic translation to a variety of
     formats suitable for input to text formatters.  A copy made in an
     otherwise Transparent file format whose markup, or absence of
     markup, has been arranged to thwart or discourage subsequent
     modification by readers is not Transparent.  An image format is
     not Transparent if used for any substantial amount of text.  A
     copy that is not "Transparent" is called "Opaque".

     Examples of suitable formats for Transparent copies include plain
     ASCII without markup, Texinfo input format, LaTeX input format,
     SGML or XML using a publicly available DTD, and
     standard-conforming simple HTML, PostScript or PDF designed for
     human modification.  Examples of transparent image formats include
     PNG, XCF and JPG.  Opaque formats include proprietary formats that
     can be read and edited only by proprietary word processors, SGML or
     XML for which the DTD and/or processing tools are not generally
     available, and the machine-generated HTML, PostScript or PDF
     produced by some word processors for output purposes only.

     The "Title Page" means, for a printed book, the title page itself,
     plus such following pages as are needed to hold, legibly, the
     material this License requires to appear in the title page.  For
     works in formats which do not have any title page as such, "Title
     Page" means the text near the most prominent appearance of the
     work's title, preceding the beginning of the body of the text.

     A section "Entitled XYZ" means a named subunit of the Document
     whose title either is precisely XYZ or contains XYZ in parentheses
     following text that translates XYZ in another language.  (Here XYZ
     stands for a specific section name mentioned below, such as
     "Acknowledgements", "Dedications", "Endorsements", or "History".)
     To "Preserve the Title" of such a section when you modify the
     Document means that it remains a section "Entitled XYZ" according
     to this definition.

     The Document may include Warranty Disclaimers next to the notice
     which states that this License applies to the Document.  These
     Warranty Disclaimers are considered to be included by reference in
     this License, but only as regards disclaiming warranties: any other
     implication that these Warranty Disclaimers may have is void and
     has no effect on the meaning of this License.

  2. VERBATIM COPYING

     You may copy and distribute the Document in any medium, either
     commercially or noncommercially, provided that this License, the
     copyright notices, and the license notice saying this License
     applies to the Document are reproduced in all copies, and that you
     add no other conditions whatsoever to those of this License.  You
     may not use technical measures to obstruct or control the reading
     or further copying of the copies you make or distribute.  However,
     you may accept compensation in exchange for copies.  If you
     distribute a large enough number of copies you must also follow
     the conditions in section 3.

     You may also lend copies, under the same conditions stated above,
     and you may publicly display copies.

  3. COPYING IN QUANTITY

     If you publish printed copies (or copies in media that commonly
     have printed covers) of the Document, numbering more than 100, and
     the Document's license notice requires Cover Texts, you must
     enclose the copies in covers that carry, clearly and legibly, all
     these Cover Texts: Front-Cover Texts on the front cover, and
     Back-Cover Texts on the back cover.  Both covers must also clearly
     and legibly identify you as the publisher of these copies.  The
     front cover must present the full title with all words of the
     title equally prominent and visible.  You may add other material
     on the covers in addition.  Copying with changes limited to the
     covers, as long as they preserve the title of the Document and
     satisfy these conditions, can be treated as verbatim copying in
     other respects.

     If the required texts for either cover are too voluminous to fit
     legibly, you should put the first ones listed (as many as fit
     reasonably) on the actual cover, and continue the rest onto
     adjacent pages.

     If you publish or distribute Opaque copies of the Document
     numbering more than 100, you must either include a
     machine-readable Transparent copy along with each Opaque copy, or
     state in or with each Opaque copy a computer-network location from
     which the general network-using public has access to download
     using public-standard network protocols a complete Transparent
     copy of the Document, free of added material.  If you use the
     latter option, you must take reasonably prudent steps, when you
     begin distribution of Opaque copies in quantity, to ensure that
     this Transparent copy will remain thus accessible at the stated
     location until at least one year after the last time you
     distribute an Opaque copy (directly or through your agents or
     retailers) of that edition to the public.

     It is requested, but not required, that you contact the authors of
     the Document well before redistributing any large number of
     copies, to give them a chance to provide you with an updated
     version of the Document.

  4. MODIFICATIONS

     You may copy and distribute a Modified Version of the Document
     under the conditions of sections 2 and 3 above, provided that you
     release the Modified Version under precisely this License, with
     the Modified Version filling the role of the Document, thus
     licensing distribution and modification of the Modified Version to
     whoever possesses a copy of it.  In addition, you must do these
     things in the Modified Version:

       A. Use in the Title Page (and on the covers, if any) a title
          distinct from that of the Document, and from those of
          previous versions (which should, if there were any, be listed
          in the History section of the Document).  You may use the
          same title as a previous version if the original publisher of
          that version gives permission.

       B. List on the Title Page, as authors, one or more persons or
          entities responsible for authorship of the modifications in
          the Modified Version, together with at least five of the
          principal authors of the Document (all of its principal
          authors, if it has fewer than five), unless they release you
          from this requirement.

       C. State on the Title page the name of the publisher of the
          Modified Version, as the publisher.

       D. Preserve all the copyright notices of the Document.

       E. Add an appropriate copyright notice for your modifications
          adjacent to the other copyright notices.

       F. Include, immediately after the copyright notices, a license
          notice giving the public permission to use the Modified
          Version under the terms of this License, in the form shown in
          the Addendum below.

       G. Preserve in that license notice the full lists of Invariant
          Sections and required Cover Texts given in the Document's
          license notice.

       H. Include an unaltered copy of this License.

       I. Preserve the section Entitled "History", Preserve its Title,
          and add to it an item stating at least the title, year, new
          authors, and publisher of the Modified Version as given on
          the Title Page.  If there is no section Entitled "History" in
          the Document, create one stating the title, year, authors,
          and publisher of the Document as given on its Title Page,
          then add an item describing the Modified Version as stated in
          the previous sentence.

       J. Preserve the network location, if any, given in the Document
          for public access to a Transparent copy of the Document, and
          likewise the network locations given in the Document for
          previous versions it was based on.  These may be placed in
          the "History" section.  You may omit a network location for a
          work that was published at least four years before the
          Document itself, or if the original publisher of the version
          it refers to gives permission.

       K. For any section Entitled "Acknowledgements" or "Dedications",
          Preserve the Title of the section, and preserve in the
          section all the substance and tone of each of the contributor
          acknowledgements and/or dedications given therein.

       L. Preserve all the Invariant Sections of the Document,
          unaltered in their text and in their titles.  Section numbers
          or the equivalent are not considered part of the section
          titles.

       M. Delete any section Entitled "Endorsements".  Such a section
          may not be included in the Modified Version.

       N. Do not retitle any existing section to be Entitled
          "Endorsements" or to conflict in title with any Invariant
          Section.

       O. Preserve any Warranty Disclaimers.

     If the Modified Version includes new front-matter sections or
     appendices that qualify as Secondary Sections and contain no
     material copied from the Document, you may at your option
     designate some or all of these sections as invariant.  To do this,
     add their titles to the list of Invariant Sections in the Modified
     Version's license notice.  These titles must be distinct from any
     other section titles.

     You may add a section Entitled "Endorsements", provided it contains
     nothing but endorsements of your Modified Version by various
     parties--for example, statements of peer review or that the text
     has been approved by an organization as the authoritative
     definition of a standard.

     You may add a passage of up to five words as a Front-Cover Text,
     and a passage of up to 25 words as a Back-Cover Text, to the end
     of the list of Cover Texts in the Modified Version.  Only one
     passage of Front-Cover Text and one of Back-Cover Text may be
     added by (or through arrangements made by) any one entity.  If the
     Document already includes a cover text for the same cover,
     previously added by you or by arrangement made by the same entity
     you are acting on behalf of, you may not add another; but you may
     replace the old one, on explicit permission from the previous
     publisher that added the old one.

     The author(s) and publisher(s) of the Document do not by this
     License give permission to use their names for publicity for or to
     assert or imply endorsement of any Modified Version.

  5. COMBINING DOCUMENTS

     You may combine the Document with other documents released under
     this License, under the terms defined in section 4 above for
     modified versions, provided that you include in the combination
     all of the Invariant Sections of all of the original documents,
     unmodified, and list them all as Invariant Sections of your
     combined work in its license notice, and that you preserve all
     their Warranty Disclaimers.

     The combined work need only contain one copy of this License, and
     multiple identical Invariant Sections may be replaced with a single
     copy.  If there are multiple Invariant Sections with the same name
     but different contents, make the title of each such section unique
     by adding at the end of it, in parentheses, the name of the
     original author or publisher of that section if known, or else a
     unique number.  Make the same adjustment to the section titles in
     the list of Invariant Sections in the license notice of the
     combined work.

     In the combination, you must combine any sections Entitled
     "History" in the various original documents, forming one section
     Entitled "History"; likewise combine any sections Entitled
     "Acknowledgements", and any sections Entitled "Dedications".  You
     must delete all sections Entitled "Endorsements."

  6. COLLECTIONS OF DOCUMENTS

     You may make a collection consisting of the Document and other
     documents released under this License, and replace the individual
     copies of this License in the various documents with a single copy
     that is included in the collection, provided that you follow the
     rules of this License for verbatim copying of each of the
     documents in all other respects.

     You may extract a single document from such a collection, and
     distribute it individually under this License, provided you insert
     a copy of this License into the extracted document, and follow
     this License in all other respects regarding verbatim copying of
     that document.

  7. AGGREGATION WITH INDEPENDENT WORKS

     A compilation of the Document or its derivatives with other
     separate and independent documents or works, in or on a volume of
     a storage or distribution medium, is called an "aggregate" if the
     copyright resulting from the compilation is not used to limit the
     legal rights of the compilation's users beyond what the individual
     works permit.  When the Document is included in an aggregate, this
     License does not apply to the other works in the aggregate which
     are not themselves derivative works of the Document.

     If the Cover Text requirement of section 3 is applicable to these
     copies of the Document, then if the Document is less than one half
     of the entire aggregate, the Document's Cover Texts may be placed
     on covers that bracket the Document within the aggregate, or the
     electronic equivalent of covers if the Document is in electronic
     form.  Otherwise they must appear on printed covers that bracket
     the whole aggregate.

  8. TRANSLATION

     Translation is considered a kind of modification, so you may
     distribute translations of the Document under the terms of section
     4.  Replacing Invariant Sections with translations requires special
     permission from their copyright holders, but you may include
     translations of some or all Invariant Sections in addition to the
     original versions of these Invariant Sections.  You may include a
     translation of this License, and all the license notices in the
     Document, and any Warranty Disclaimers, provided that you also
     include the original English version of this License and the
     original versions of those notices and disclaimers.  In case of a
     disagreement between the translation and the original version of
     this License or a notice or disclaimer, the original version will
     prevail.

     If a section in the Document is Entitled "Acknowledgements",
     "Dedications", or "History", the requirement (section 4) to
     Preserve its Title (section 1) will typically require changing the
     actual title.

  9. TERMINATION

     You may not copy, modify, sublicense, or distribute the Document
     except as expressly provided for under this License.  Any other
     attempt to copy, modify, sublicense or distribute the Document is
     void, and will automatically terminate your rights under this
     License.  However, parties who have received copies, or rights,
     from you under this License will not have their licenses
     terminated so long as such parties remain in full compliance.

 10. FUTURE REVISIONS OF THIS LICENSE

     The Free Software Foundation may publish new, revised versions of
     the GNU Free Documentation License from time to time.  Such new
     versions will be similar in spirit to the present version, but may
     differ in detail to address new problems or concerns.  See
     `http://www.gnu.org/copyleft/'.

     Each version of the License is given a distinguishing version
     number.  If the Document specifies that a particular numbered
     version of this License "or any later version" applies to it, you
     have the option of following the terms and conditions either of
     that specified version or of any later version that has been
     published (not as a draft) by the Free Software Foundation.  If
     the Document does not specify a version number of this License,
     you may choose any version ever published (not as a draft) by the
     Free Software Foundation.

ADDENDUM: How to use this License for your documents
====================================================

To use this License in a document you have written, include a copy of
the License in the document and put the following copyright and license
notices just after the title page:

       Copyright (C)  YEAR  YOUR NAME.
       Permission is granted to copy, distribute and/or modify this document
       under the terms of the GNU Free Documentation License, Version 1.2
       or any later version published by the Free Software Foundation;
       with no Invariant Sections, no Front-Cover Texts, and no Back-Cover
       Texts.  A copy of the license is included in the section entitled ``GNU
       Free Documentation License''.

   If you have Invariant Sections, Front-Cover Texts and Back-Cover
Texts, replace the "with...Texts." line with this:

         with the Invariant Sections being LIST THEIR TITLES, with
         the Front-Cover Texts being LIST, and with the Back-Cover Texts
         being LIST.

   If you have Invariant Sections without Cover Texts, or some other
combination of the three, merge those two alternatives to suit the
situation.

   If your document contains nontrivial examples of program code, we
recommend releasing these examples in parallel under your choice of
free software license, such as the GNU General Public License, to
permit their use in free software.

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.