FreeBSD Manual Pages
sccsfile(5) File Formats sccsfile(5) NAME sccsfile - format of an SCCS history file DESCRIPTION An SCCS file is an ASCII file consisting of six logical parts (SCCS v4 checksum, delta table, usernames, flags, comments, body) or eight logical parts (SCCS v6 checksum, delta table, usernames, v4 flags, v6 flags, v6 metadata, comments, body): checksum Character sum computed on the rest of the file, used for error detection. delta table Log containing version info and statistics about each delta. usernames Login names and/or group IDs of users who may add deltas. flags Definitions of internal keywords and configuration for user de- fined behavior (SCCS v4). v6 flags Optional further internal definitions. SCCS v6 only. v6 metadata Optional global metadata. SCCS v6 only. extensions This is the area where future versions of SCCS will add exten- sions. comments An arbitrary descriptive information block about the file. body the Actual text lines intermixed with control lines. This body is also known as interleaved deltas or the weave. Each section is described in detail below. This document describes the SCCS v4 history file format that has been in- troduced in February 1977 as well as the SCCS v6 enhancements that have been introduced in September 2011. Conventions Throughout an SCCS file there are lines which begin with the ASCII SOH (start of heading) character (octal 001). This character is hereafter re- ferred to as the control character, and will be represented as `^A'. If a line described below is not depicted as beginning with the control charac- ter, it cannot do so and still be within SCCS file format. Entries of the form ddddd represent a decimal number. In the statistics line from the delta table, this represents a five digit string (a number between 00000 and 99999). Other numbers are not artificially limited to a specific range. Serial numbers and SID number components may be any non negative number representable by a signed 32 bit integer. The usable range on a specific machine is however limited by the available virtual memory. This implementation needs virtual memory that is approx. 100 times the highest serial number from the file. If a SCCS history file contains one million deltas, this implementation needs 100 MBytes of vir- tual memory to process the deltas. Checksum The checksum is the first line of an SCCS file. The form of the line is: ^Ahddddd The value of the checksum is the low 16 bits from the signed sum of all characters, except those contained in the first line. When reading files, values computed as the unsigned sum of all characters are accepted too. The ^Ah provides a 16 bit magic number of (octal) 064001 in PDP-byteorder and 000550 in Motorola-byteorder ("\001\150"). SCCS v6 Checksum SCCS v6 introduces a different checksum line: ^AhV6,sum=ddddd The checksum line was changed in order to prevent historic SCCS implementa- tions from accidentally ignoring project-related (project-global) locks. It permits future versions to decide on different checksum algorithms without a need to again introduce a new history file format. In SCCS v6, the ^Ah magic is not directly followed by the checksum but by the letter V that is followed by the SCCS version number. The version num- ber is followed by a comma and the checksum algorithm name. The string sum is interpreted as the SCCS v4 checksum method. The SCCS v4 checksum entry must directly follow the SCCS version number. Further checksums may be added in the future, e.g.: ^AhV6,sum=ddddd,md5=hhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhh but the sum= entry is mandatory. SCCS v6 currently does not implement checksum algorithms other than sum. Other entries are currently ignored when reading and silently discarded when copying or modifying files. Delta Table The delta table consists of a variable number of entries of the form: ^As inserted/deleted/unchanged ^Ad type sid yr/mo/da hr:mi:se username serial-number \ predecessor-sn ^Ai include-list ^Ax exclude-list ^Ag ignored-list ^Am mr-number ... ^Ac comments ... ... ^Ae The lines with the entry type ^As, ^Ad and ^Ae are mandatory. The first line (^As) contains the number of lines inserted/deleted/un- changed respectively. The actual values for inserted/deleted/unchanged are five digit numbers. If an actual value is greater than 99999, then it is replaced by 99999. The second line (^Ad) contains the type of the delta in the second word: D for a normal delta R for a removed delta U for a delta that causes to unlink the g-file If this delta type is used for the initial release of a SCCS history file, the default SID is set to 1.0 to permit the first delta with data to have the typical 1.1. The delta table type is followed by the SCCS ID (SID) of the delta, the date and time of creation of the delta as local time, the user-name corre- sponding to the real user ID at the time the delta was created, and the se- rial numbers of the delta and its predecessor, respectively. The year is either represented by a two digit year in the range 69..99 for 1969..1999 or 00..68 for 2000..2068 or by a four digit year number. Year numbers before 1969 are currently not supported. Older SCCS versions may not be able to understand four digit year numbers. The user-name must not contain a space character, as space is the field separator in this file format. Since some non-POSIX platforms permit a space in the username, it is converted into a `_' by the SCCS software be- fore storing it in the history file. The ^Ai, ^Ax, and ^Ag lines contain the serial numbers of deltas included, excluded, and ignored, respectively. These lines do not always appear. The ^Am lines (optional) each contain one MR number associated with the delta. The ^Ac lines contain comments associated with the delta. If there is more than one comment line, each comment line appears after a separate ^Ac lead in. The ^Ae line ends the current delta table entry. SCCS v6 Delta Table SCCS v6 uses an enhanced delta table: ^As inserted/deleted/unchanged ^Ad type sid yr/mo/da hr:mi:se[.ss]+-hhmm username \ serial-number predecessor-sn ^Ai include-list ^Ax exclude-list ^Ag ignored-list ^Am mr-number ... ^AS sid-specific metadata ... ^Ac comments ... ... ^Ae The second line (^Ad) must have a four digit year number, may add sub-sec- ond time stamp granularity and must have a time zone offset. Optional sub-second time stamp granularity is introduced by a dot `.' and adds one to nine decimal digits that represent a fraction of a second up to nanosecond granularity. This number must be non-negative. The time zone offset starts with a `+' or a `-', the value 0000 starts with a `+', negative values start with a `-'. Positive values are east to GMT. The first two decimal digits represent the hour part of the GMT offset, the last two decimal digits represent the minute part of the GMT offset. A granularity less than a minute cannot be represented. The date and time part represents local time as in SCCS v4 entries, but the mandatory timezone offset makes the time unique. The time stamp: 2012/02/01 13:00:00+0100 represents 2012, the first of February 12:00 GMT which is 13:00 MET. The ^AS lines introduce SID specific SCCS v6 extensions. SID specific ex- tension lines are in name/value format and take the form: ^AS name optional value text The following name parameters are defined: p path Record the current path of the g-file relatively to the project's file set home directory. A path entry only ap- pears in case a rename or remove operation has been ap- plied to the file. The project set home is a directory that holds a directory .sccs for project specific SCCS metadata. The location of this directory .sccs is searched for by scanning the filesystem towards the root directory, starting from the current working directory. All files that belong to a project must be below the project's file set home direc- tory. See also the description for the same keyword in the sec- tion for global meta data, where the the initial file name is recorded. s nnnnn A SID specific additional checksum. The value of the checksum is the low 16 bits from the unsigned sum of all characters in the SID specific file content as retrieved by `get -e' (without keyword expansion). If the file is archived UU-encoded (see `e' flag), the checksum is com- puted on the UU-encoded text and not on the original file. The data format in the extended SCCS delta entry (^Ad) and the SCCS SID specific metadata (^AS) is not accepted by historic SCCS implementations. When converting a SCCS v6 history file back to a SCCS v4 history file, these entries are converted into special comment at the beginning of the comment section. While converting, a copy of the unmodified ^Ad entry is kept as ^Ac_d and ^AS is turned into ^Ac_S. User Names The list of user-names and/or numerical group IDs of users who may add deltas to the file, separated by NEWLINE characters. The lines containing these login names and/or numerical group IDs are surrounded by the bracket- ing lines ^Au and ^AU. An empty list allows anyone to make a delta. Flags Flags are keywords that are used internally (see sccs-admin(1) for more in- formation on their use). Each flag line takes the form: ^Af flag optional text Flags may be selected from the set of 26 lower case characters in the range `a'..`z'. Historical SCCS implementations will dump core in case a charac- ter outside the specified range appears as flag character. The following flags are defined in order of appearance: ^Af t type-of-program Defines the replacement for the %Y% ID keyword. ^Af v program-name Controls prompting for MR numbers in addition to comments. If the optional text is present, it de- fines an MR number validity checking program. The v flag and the z flag are mutually exclusive. ^Af i [value] Indicates that the `No id keywords' message is to generate an error that terminates the SCCS command. Otherwise, the message is treated as a warning only. If the parameter value to the `i' flag is not empty, then it holds a line fragment with keywords starting with a `%', e.g. `%Z%%M% %I% %E%' This line fragment needs to exactly match a part of a line in the file and to result in expanded key- words. Otherwise an attempt to check in a new delta will fail. The parameter to the `i' flag is a SUN extension. ^Af b Indicates that the -b option may be used with the SCCS get command to create a branch in the delta tree. ^Af m module-name Defines the first choice for the replacement text of the %M% ID keyword. ^Af f floor Defines the "floor" release, that is, the release below which no deltas may be added. ^Af c ceiling Defines the "ceiling" release, that is, the release above which no deltas may be added. ^Af d default-sid The d flag defines the default SID to be used when none is specified on an SCCS get command. ^Af n The n flag enables the SCCS delta command to insert a "null" delta (a delta that applies no changes) in those releases that are skipped when a delta is made in a new release (for example, when delta 5.1 is made after delta 2.7, releases 3 and 4 are skipped). ^Af j Enables concurrent get -e calls for editing on the same base SID of an SCCS file. This allows multi- ple concurrent updates to take place on the same version of the SCCS file. ^Af l lock-releases Defines a list of releases that are locked against editing. ^Af q user-defined Defines the replacement for the %Q% ID keyword. ^Af e 0|1 The e flag indicates whether a source file is en- coded or not. A 1 indicates that the file is en- coded. Source files need to be encoded when they contain control characters, or when they do not end with a NEWLINE. The e flag allows files that con- tain binary data to be checked in. ^Af z application The name of an application for the CMF enhance- ments. CMF enhancements are currently undocumented and it is not known how they are expected to work. The v flag and the z flag are mutually exclusive. ^Af s nnn The number of lines to be scanned for keyword ex- pansion. This flag is a SUN extension that does not exist in historic sccs implementations. ^Af x SCHILY|0 If the value of the `x' flag is set to `SCHILY', enable sccs extensions that are not implemented in classical sccs variants. If the `x' flag is en- abled, the keywords %d%, %e%, %g% and %h% are ex- panded even though not explicitly enabled by the `y' flag. This flag is a SCHILY extension that does not exist in historic sccs implementations. This version of SCCS implements read only compati- bility support for a SCO SCCS extension that sets the executable bit in the file permissions of a gotten file if the x-flag was set in the history file with no parameter. This version of SCCS does not allow to set this variant of the x-flag in the history file. If you like to get executable files from SCCS, set the executable bit in the file per- missions of the history file. If this version of SCCS is used to create the his- tory file and the executable bit was set in the original file, SCCS automatically sets the exe- cutable bit in the history file and thus retains the executable bit in the gotten file. ^Af y val ... The list of sccs keywords to be expanded. If the y-flag is missing in the sccs historyfile, all sccs keywords are expanded. If the flag is present but the list is empty, no keyword is expanded and no `No id keywords' message is generated. The value `*' controls the expansion of the %sccs.in- clude.filename% keyword. This flag is a SUN/SCHILY extension that does not exist in historic sccs implementations. SCCS v6 Flags SCCS v6 flags are additional keywords that are used internally (see sccs- admin(1) for more information on their use). Each flag line takes the form: ^AF flag optional text No SCCS v6 flags are currently defined. Historical SCCS implementations do not complain about SCCS v6 flags when reading SCCS history files and retain SCCS v6 flags when modifying history files. This is why SCCS v6 flags may be kept unmodified when converting a SCCS v6 history file back to a SCCS v4 history file. SCCS v6 Metadata SCCS v6 metadata is additional global metadata that is used internally (see sccs-admin(1) for more information on it's use). Each metadata line takes the form: ^AG keyword optional text The following keywords are defined: p path Record the initial path of the g-file relatively to the project's file set home directory. Once set up, this name must never change. See also the description for the project set home in the documentation for the same keyword in the section for SID specific meta data of the delta table. In case of a re- name, the new file name is recorded in in the SID specific meta data of the delta table. r random A unified pseudo random number (see also changeset(5)) that is used to help to identify single files across re- names during the lifetime of the sccs history. The pseudo random number is a hexadecimal string that rep- resents the microseconds since Jul 13 11:01:20 2012 GMT when initially creating the sccs history for a specific file. Including microseconds gives sufficient randomness to make clashes rare. With a 32 bit signed time_t, 52 bits in the pseudo random number are sufficient. With a 64 bit pseudo random num- ber, more than 500000 years are covered. The minimal length for the pseudo random number is thir- teen hexadecimal characters. If the number could be repre- sented with less digits, it is left filled with zeroes. This allows one to have a unique length for this number until Mar 31 10:55:07 2155 GMT. The random metadata is mandatory for SCCS v6 history files. The initial path tag may be recorded later but before the changeset file is created. The value for this metadata tags must not change. Historical SCCS implementations do not complain about SCCS v6 metadata when reading SCCS history files and retain SCCS v6 metadata when modifying his- tory files. This is why SCCS v6 metadata may be kept unmodified when con- verting a SCCS v6 history file back to a SCCS v4 history file. Extensions This is the area where future versions of SCCS will add extensions. SCCS reserves the area just before the comments section for extensions by only checking the content at this location for syntactic correctness. Un- known elements at this location are still copied and kept intact when the historyfile is modified. SCCS v6 already introduced SCCS v6 flags and global SCCS v6 metadata as extensions, so future extensions must appear past the SCCS v6 metadata. Comments Arbitrary text surrounded by the bracketing lines ^At and ^AT. The com- ments section typically will contain a description of the file's purpose. Body The body consists of text lines and control lines. Text lines do not begin with the control character, unless they are using SCCS v6 escape exten- sions. Control lines always begin with the control character. There are three kinds of control lines: insert, delete, and end, repre- sented by: ^AI ddddd ^AD ddddd ^AE ddddd respectively. The digit string is the serial number corresponding to the delta for the control line. An inserted block of lines looks this way: ^AI ddddd block of data ^AE ddddd A deleted block of lines looks this way: ^AD ddddd block of data ^AE ddddd The block of data may contain control lines with other serial numbers. SCCS v6 Body escape extensions There are two additional types of text lines with a control character at the beginning that represent features introduced by SCCS v6. These fea- tures are not understood by SCCS implementations that support the SCCS v4 history file format only. ^A^A A line in the interleaved delta block that begins with two con- trol characters represents a text line that begins at the sec- ond control character. ^AN A line in the interleaved delta block that begins with the ^AN sequence represents a text line that does not end with a new- line character. A line in the form ^AN^Atext is extracted as ^Atext without a need to add another quote. FILES ``g-file'' version retrieved by get d.file temporary file created by the delta(1) program with the content of the previous version, used to compute differences to the current version e.file temporary file to hold an uuencoded version of the g-file in case of an encoded history file. Used by admin(1) and delta(1). l.file file containing extracted delta table info o.file saved original version of the history file, created by scc- scvt(1). p.file permissions (lock) file for checked-out versions. The p.file has an arbitrary number of lines, each is related to a get -e call. Each line has the following structure: old-sid new-sid username date time \ [ -ii-arg ][ -xx-arg ][ -zz-arg ] The old-sid is the SID that was checked out with get -e, the new-sid is the SID that will be used for the new version when delta is called. The username is the user-name corresponding to the real user ID at the time get -e was called. The date and time fields are in the same format as used in the delta table of the s.file as described in sccsfile(5) for SCCS v4. In or- der to grant POSIX compatibility, a two digit year is used be- tween 1969 and 2068. For years outside that range, a four digit year is used. The following fields are only present when one or more of the -i -x or -z options have been specified on the command line, they refer to the list of included and excluded deltas or to the CMR list from the NSE enhancements. q.file temporary copy of the p.file; renamed to the p.file after com- pletion s.file SCCS history file, see sccsfile(5). SCCS/s.file history file in SCCS subdirectory x.file temporary copy of the s.file; renamed to the s.file after com- pletion. Used by admin(1), cdc(1), delta(1), rmdel(1), and sccscvt(1). z.file temporary lock file contains the binary process id in host byte order followed by the host name projecthome/.sccs/SCCS/s.changeset The project specific changeset file is in the directory .sccs in the project set home directory. Only the s.changeset file is present, a related g-file does not exist. dump.core If the file dump.core exists in the current directory and a fa- tal signal is received, a coredump is initiated via abort(3). /usr/ccs/include/ If the environment SCCS_INCLUDEPATH does not exist, include files for the %sccs.include.filename% keyword directive are searched in this directory. SEE ALSO sccs(1), sccs-admin(1), sccs-cdc(1), sccs-comb(1), sccs-cvt(1), sccs-delta(1), sccs-get(1), sccs-help(1), sccs-log(1), sccs-prs(1), sccs-prt(1), sccs-rmdel(1), sccs-sact(1), sccs-sccsdiff(1), sccs-unget(1), sccs-val(1), bdiff(1), diff(1), what(1), sccschangeset(5). NOTES The following SCCS programs write or modify SCCS history files and create lock files for the SCCS history files: admin(1) create and administer SCCS history files cdc(1) change the delta commentary of an SCCS delta delta(1) make a delta to an SCCS file rmdel(1) remove a delta from an SCCS file sccscvt(1) convert history files between SCCS v4 and SCCS v6 The following SCCS programs do not write or modify SCCS history files but create lock files for SCCS history files since they modify p.files: get(1) when using the option -e to check out a file for editing unget(1) undo a previous get of an SCCS file BUGS SCCS v4 uses local time without a timezone offset. If a delta is created less than an hour after switching from DST to non-DST, it may look as if the clock is going backwards. SCCS v6 fixes this problem by introducing a mandatory timezone offset. Mail bugs and suggestions to schilytools@mlists.in-berlin.de or open a ticket at https://codeberg.org/schilytools/schilytools/issues. The mailing list archive may be found at: https://mlists.in-berlin.de/mailman/listinfo/schilytools-mlists.in-berlin.de. AUTHORS The SCCS suite was originally written by Marc J. Rochkind at Bell Labs in 1972. Release 4.0 of SCCS, introducing new versions of the programs ad- min(1), get(1), prt(1), and delta(1) was published on February 18, 1977; it introduced the new text based SCCS v4 history file format (previous SCCS releases used a binary history file format). The SCCS suite was later maintained by various people at AT&T and Sun Microsystems. Since 2006, the SCCS suite has been maintained by Joerg Schilling and the schilytools project authors. SunOS 5.11 2022/10/06 sccsfile(5)
NAME | DESCRIPTION | FILES | SEE ALSO | NOTES | BUGS | AUTHORS
Want to link to this manual page? Use this URL:
<https://man.freebsd.org/cgi/man.cgi?query=sccsfile&sektion=5&manpath=FreeBSD+Ports+15.1.quarterly>