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

This document was generated by buildd user on December 8, 2011 using texi2html 1.82.