This is cssc.info, produced by makeinfo version 4.1 from cssc.texi. INFO-DIR-SECTION Miscellaneous START-INFO-DIR-ENTRY * cssc: (cssc). The GNU work-alike replacement for SCCS. END-INFO-DIR-ENTRY This file documents the the GNU `cssc' package for working with SCCS files. Copyright (C) 1997,1998,1999,2000,2001,2002 Free Software Foundation, Inc. Permission is granted to make and distribute verbatim copies of this manual provided the copyright notice and this permission notice are preserved on all copies. Permission is granted to copy and distribute modified versions of this manual under the conditions for verbatim copying, provided that the entire resulting derived work is distributed under the terms of a permission notice identical to this one. Permission is granted to copy and distribute translations of this manual into another language, under the above conditions for modified versions, except that this permission notice may be stated in a translation approved by the Foundation.  File: cssc.info, Node: prt output, Prev: prt options, Up: prt `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 (*note 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 (*note 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.  File: cssc.info, Node: rmdel, Next: sact, Prev: prt, Up: Invoking Programs `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.  File: cssc.info, Node: sact, Next: sccs, Prev: rmdel, Up: Invoking Programs `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.  File: cssc.info, Node: sccs, Next: sccsdiff, Prev: sact, Up: Invoking Programs `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. *Note 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 *Note 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/'.  File: cssc.info, Node: sccsdiff, Next: unget, Prev: sccs, Up: Invoking Programs `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' (*note 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.  File: cssc.info, Node: unget, Next: val, Prev: sccsdiff, Up: Invoking Programs `unget' ======= The `unget' command is used to reverse the effect of `get -e'. Typically you might do this when you embark on an edit of a file, and it all goes horribly wrong. Using `unget' allows you to revert to a previously-known state. In fact, if you have exercised some care in checking in new revisions, perhaps using a test suite, then `unget' can be used to return you to the last working version. Options for `unget' ------------------- `-n' Do not delete the g-file which you were editing `-s' Operate silently `-rSID' When joint editing is enabled (*note 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.  File: cssc.info, Node: val, Next: what, Prev: unget, Up: Invoking Programs `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 *note Why val doesn't solve the whole problem: Paranoia.). 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 * Menu: * Options for val:: Full list of options * Validation Warnings:: Some potential problems result in warnings * Return Value:: What val's return value means * Paranoia:: Why your file might still be corrupt  File: cssc.info, Node: Options for val, Next: Validation Warnings, Up: val 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. *Note 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. *Note Flags::, for a description of the SCCS file flags.  File: cssc.info, Node: Validation Warnings, Next: Return Value, Prev: Options for val, Up: val 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. 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.  File: cssc.info, Node: Return Value, Next: Paranoia, Prev: Validation Warnings, Up: val 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 *Note 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.  File: cssc.info, Node: Paranoia, Prev: Return Value, Up: val 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.  File: cssc.info, Node: what, Prev: val, Up: Invoking Programs `what' ====== The `what' program is designed to search in files for the recognition string `@(#)'. All the strings it finds matching this are printed on standard output. The exit status of `what' if zero is a matching string as found, and 1 otherwise. Options for `what' ------------------ `what [-s] [-V] file [file ...]' `-s' Exit successfully after finding the first string. `-V' Show version information for `what'. Example ------- While the file is being edited (either at first or after `get -e'):- #ifndef CONFIG_NO_SCCS_IDS static const char sccs_id[] = "%W%"; #endif When the file is checked out for compiling (with `get'):- #ifndef CONFIG_NO_SCCS_IDS static const char sccs_id[] = "@(#)foo.c 1.3"; #endif After compiling:- $ what foo foo: foo.c 1.3 If the executable is linked from several source files, you will get a line of output for each string containing the identification string `@(#)'. This is useful for finding out exactly what code went into an executable. This technique also works on object files, archive libraries, text files, and in fact any sorts of files at all. Unlike the `strings' command, there is no way to make `what' operate on standard input. The data would need to be written to a file first. The rationale for the preprocessor construct `CONFIG_NO_SCCS_IDS' is that sometimes compilers or lint-pickers complain that the variable SCCS_ID is unused, and defining `CONFIG_NO_SCCS_IDS' will remove these IDs and thus silence the warnings.  File: cssc.info, Node: Filenames, Next: File Format, Prev: Invoking Programs, Up: Top Filenames ********* Temporary files are used during normal operation of CSSC (and SCCS). Many of these are given fixed names. The prefixes for the various files used by CSSC are listed in the table below. `s.' The history file itself. `p.' The file containing the list of edit locks. `z.' The lock file used to arbitrate access to the history file. The running CSSC (or SCCS) program puts its PID into this file. Some versions of SCCS (but _not_ CSSC) will break the lock after 60 seconds if the specified PID is not running on the local machine. In order to work more reliably over networked filesystems, CSSC will not do this; stale lock files would have to be removed manually. `x.' Temporary file into which is written the new s-file. Once processing is complete, the old s-file is replaced by the x-file. `q.' Temporary file into which is written the new p-file `d.' Temporary file used by delta; contains the gotten body of the previous version (which we run diff against). This filename is used by SCCS in the same situation, but according to the SCCS manual pages, it puts the output of `diff' in this file instead. `u.' Encoded version of the gotten file; created by delta. All of the temporary files in the above table are created in the same directory as the s-file, rather than in the current working directory. Since these filenames are always fixed, it is important that the permissions on the directory containing the SCCS file be secure; otherwise you have a security vulnerability where a malicious user can cause you to accidentally over-write files you own or have access to, but they do not. If you are the super-user, they can use this feature to overwrite any file on the system.  File: cssc.info, Node: File Format, Next: Interoperability, Prev: Filenames, Up: Top 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. * Menu: * File Format Overview:: An overview of the file format * The Header:: Format of the header of SCCS files * The Body:: Format of the body of SCCS files  File: cssc.info, Node: File Format Overview, Next: The Header, Up: File Format 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.  File: cssc.info, Node: The Header, Next: The Body, Prev: File Format Overview, Up: File Format The Header ========== There are several parts to the SCCS file header:- * Menu: * Checksum Line:: * Delta Table:: * Authorised User List:: * Global Flags Section:: * File Description:: * Example Header::  File: cssc.info, Node: Checksum Line, Next: Delta Table, Up: The Header Checksum -------- The first line of an SCCS file contains the checksum, preceded by `^Ah'. The checksum is in decimal and is generated by adding together the values of all the characters in the file, and taking the result modulo 65536. A checksum line might look like this:- ^Ah36650 On systems whose C implementation considers the `char' type to be unsigned, characters with their highest bit set appear to be considered positive, and on machines with a signed `char' type, these characters appear to be considered negative. This seems to mean that these two types of machines will not agree on the correctness of an SCCS file's checksum.  File: cssc.info, Node: Delta Table, Next: Authorised User List, Prev: Checksum Line, Up: The Header 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 (*note 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 (*note 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 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. The comment block, and in fact the whole delta table entry, is terminated by a control line of the form ^Ae CSSC is currently slightly incorrect in this area. If the comment is suppressed with the `-y' option, it emits no `^Ac' lines at all. 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  File: cssc.info, Node: Authorised User List, Next: Global Flags Section, Prev: Delta Table, Up: The Header Authorised User List -------------------- Next, there is the list of authorised users, intorduced 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.  File: cssc.info, Node: Global Flags Section, Next: File Description, Prev: Authorised User List, Up: The Header 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 *Note Flags:: for information about the other possible flag letters and their meanings. See *Note Interoperability:: for information about sharing SCCS files with other implementations of SCCS.  File: cssc.info, Node: File Description, Next: Example Header, Prev: Global Flags Section, Up: The Header 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.  File: cssc.info, Node: Example Header, Prev: File Description, Up: The Header 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  File: cssc.info, Node: The Body, Prev: The Header, Up: File Format 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 () know.  File: cssc.info, Node: Interoperability, Next: Environment, Prev: File Format, Up: Top 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. * Menu: * Binary File Support:: Enabling or disabling support for binary files. * Maximum Line Length:: Limiting the length of lines in the SCCS file. * Limitations of diff:: Diff has limits too, on many non-GNU systems. * Configuration:: Viewing the current configuration. * Bug-for-Bug:: We go to great lengths to be compatible * Incompatibilities:: Sometimes we cannot be fully compatible * SCCS Version Differences:: Versions of SCCS behave inconsistently  File: cssc.info, Node: Binary File Support, Next: Maximum Line Length, Up: Interoperability 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 (*note 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 *Note Environment::. If you use CSSC with support for encoded SCCS files turned off, encoded files will still be handled; CSSC will just refuse to create a new one. This provides as great a degree of interoperability with other implementations of SCCS as possible.  File: cssc.info, Node: Maximum Line Length, Next: Limitations of diff, Prev: Binary File Support, Up: Interoperability 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 (*note 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 *Note Environment::. To determine the current setting of the line length limit, run `admin -V' and read the output. If (and only if) you have configured CSSC with such a maximum line length limitation, the lengths of input lines are checked as they are being read. When CSSC is adding a new delta to an existing file, if it finds an input line which is longer than N characters, it will fail with an explanatory message (the alternative would be that an SCCS file would be generated that could not be read by other implementations of SCCS having a lower line length limit). When CSSC is creating a new SCCS file in response to the `admin -i' command, one of two things will happen when an over-length line is found. If binary file support is enabled, the SCCS file will automatically be created as an encoded file. Otherwise, `admin' will fail with an explanatory message. When the CSSC tools are reading a history file, the lines in the SCCS file are not subject to the limits described above; that is, CSSC imposes these limits on lines it puts _into_ the SCCS file, but not on lines it reads _from_ the SCCS file. This means that the CSSC `get' utility will cope with arbitrarily long lines in the SCCS file, even if CSSC has been configured in sauch a way that `delta' would not put such long lines into the history file.  File: cssc.info, Node: Limitations of diff, Next: Configuration, Prev: Maximum Line Length, Up: Interoperability 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 (*note 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. *Note Configuration:: explains how you can determine which diff command is used by CSSC.  File: cssc.info, Node: Configuration, Next: Bug-for-Bug, Prev: Limitations of diff, Up: Interoperability 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".  File: cssc.info, Node: Bug-for-Bug, Next: Incompatibilities, Prev: Configuration, Up: Interoperability 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 not that these bugs only affect _some_ other versions of SCCS - if they affected all versions, they'd be the correct behaviour of CSSC too! * 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. *Note 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. *Note 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".  File: cssc.info, Node: Incompatibilities, Next: SCCS Version Differences, Prev: Bug-for-Bug, Up: Interoperability 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: cssc.info, Node: SCCS Version Differences, Prev: Incompatibilities, Up: Interoperability SCCS Version Differences ======================== This section outlines some of the ways in which various versions of SCCS differ from each other and therefore sometimes from CSSC. Binary file support and line lengths ------------------------------------ The various versions of SCCS differ in their level of support for binary files (*note Binary File Support::), and in the maximum line length that they will support (*note Maximum Line Length::. sccsdiff -------- There are some small variations in the way that the several versions of `sccsdiff' behave. These are outlined in the table below :- Solaris 8 Prints a separator line between the `diff' output for each s-file. This separator is output before the first set of diff output, even if only one s-file has been named on the command line. Solaris 2.6 and many other versions of Unix Does not print a separator. admin ----- There are a few differences in the behaviour of the `admin' command across the various SCCS Implementations :- The `-n' option Some versions of Dynix do not allow the use of the `-n' option without the `-i' option. A workaround is to use `-n -i/dev/null' instead. Binary file support Most implementations of SCCS do not support the encoding of binary files, either automatically or by the use of the `-b' option to `admin'. See *Note Binary File Support::, for more information. Initial delta The `-r' option is used to specify the release of the initial delta. Some implementations of SCCS allow this to use used to specify more components of a SID than just the release number. The CSSC version of `admin' allows this usage but issues a warning message. If the `-r' option is used to specify a non-trunk SID (that is, a SID with more than two components), this is allowed but some of the other tools in the CSSC suite will not work correctly on the resulting file. prt --- If the "encoded" flag is set, some versions of `prt' (but not the CSSC version) omit a newline in the output and so the next thing follows immediately on the same line.  File: cssc.info, Node: Environment, Next: Incomplete, Prev: Interoperability, Up: Top Environment Variables ********************* Several environment variables control the behaviour of CSSC. This section explains what these variables are and how they work. * Menu: * Child Processes:: CSSC tools run other programs occasionally. * Configuration Variables:: Variables that turn features on or off. * Other Variables:: Miscellaneous other variables you might use.  File: cssc.info, Node: Child Processes, Next: Configuration Variables, Up: Environment 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. *Note 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. *Note 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.  File: cssc.info, Node: Configuration Variables, Next: Other Variables, Prev: Child Processes, Up: Environment Configuration Variables ======================= When "configure" is run, some default behaviours are set. These can be overridden with the use of environment variables as described below. CSSC_BINARY_SUPPORT ------------------- The `CSSC_BINARY_SUPPORT' environment variable controls whether CSSC will create "encoded" SCCS files. The three valid values for this variable are as follows :- `enabled' CSSC will create encoded SCCS files if required `disabled' CSSC will not create encoded SCCS files unset The default behaviour is used; this default will be the same as for one of `enabled' or `disabled'. The default is set by passing either `--enable-binary' or `--disable-binary' to "configure" when CSSC is compiled. If this option was not specified, the default value is `enabled'. For more information see *Note Interoperability::. This variable is unset by the `sccs' driver program, if it is installed set-user-id or set-group-id. CSSC_MAX_LINE_LENGTH -------------------- The `CSSC_MAX_LINE_LENGTH' environment variable controls the maximum length of lines that CSSC will allow to go into an SCCS file. This variable should be set to a decimal integer. The default behaviour of CSSC when this variable is unset is described in *Note Interoperability::. This variable is unset by the `sccs' driver program, if it is installed set-user-id or set-group-id.  File: cssc.info, Node: Other Variables, Prev: Configuration Variables, Up: Environment Other Variables =============== USER ---- If "configure" detects that UIDs are not supported on the system you are running on (that is, you are compiling on a system that doesn't look at all like Unix) then the environment variable USER is used to determine the invoking user's name. This is then the name which is used in the p-file and in the delta information for new deltas. This username is also compared against the list of authorised users by `delta'. Of course, this doesn't provide much security but in the absence of user ID support, CSSC can't tell who users really are anyway. The behaviour of CSSC with respect to this option is not sensitive to whether or not programs are installed set-user-id, because this variable is only consulted on systems where set-user-id is not supported. This may be a problem on systems where it is possible to grant enhanced privileges to a program, but which do not look like Unix to the "configure" program. CSSC_SHOW_SEQSTATE ------------------ If set, the environment variable `CSSC_SHOW_SEQSTATE' will cause CSSC to emit debugging information about the delta table to stderr. This is only of use when debugging CSSC. PROJECTDIR ---------- The `PROJECTDIR' environment variable is used only by the `sccs' driver program. This variable is ignored if the the `sccs' program is installed with the set-user-ID bit set. See *Note Known Problems::, for other remarks concerning setuid execution. The `PROJECTDIR' variable is used to locate the SCCS history file corresponding to a filename given on the command line. If the value of `PROJECTDIR' starts with a `/', it is used as an absolute directory name. If `PROJECTDIR' does not start with a slash, it is assumed to be the name of a user, and SCCS files are assumed to be in the subdirectory "src" or "source" beneath their home directory. PATH ---- Normally, the `sccs' driver program locates the other tools by searching the directories specified in `PATH', but if it is running set-user-id or set-group-id, a compiled-in value is used instead. By default, this value is is `/usr/sccs'. If SCCS is not privileged, it will fall back on the compiled-in value in order to find the other tools if they are not found in any of the directories in `$PATH'. In normal operation, `sccs diffs' will use the system `diff' command by searching the `PATH' environment variable. This doesn't happen if it is running set-user-id or set-group-id. LD_LIBRARY_PATH --------------- None of the programs in the CSSC suite take any specific action regarding the `LD_LIBRARY_PATH' environment variable, but your system libraries may take notice of it (or decide not to do so, for example when a program is running set-user-id or set-group-id). TMPDIR ------ The `sccsdiff' program ignores the setting of the `TMPDIR' environment variable. Temporary files with predictable names are created in the `/tmp' directory. *Note Known Problems::. Locale variables ---------------- The `sccs' driver program uses the `setlocale' function, whose behaviour depends on several implementation-dependent environment variables. If you are using the GNU C library, these variables are `LC_COLLATE', `LC_CTYPE', `LC_MESSAGES', `LC_MONETARY', `LC_NUMERIC', `LC_TIME', and `LANG'. The `setlocale' function is not called if SCCS is running set-user-id or set-group-id.  File: cssc.info, Node: Incomplete, Next: Year 2000 Issues, Prev: Environment, Up: Top Missing Features and other Problems *********************************** * Menu: * Missing Features:: Some features of SCCS are not provided. * Known Problems:: Known problems with CSSC. * Unemulated Features:: Problems with SCCS that CSSC doesn't share.