Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
sccsfile(4)			 File Formats			   sccsfile(4)

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 logi-
       cal  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
		   defined 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 ex-
		   tensions.

       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
       introduced 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
       referred	 to as the control character, and will be represented as `^A'.
       If a line described below is not	depicted as beginning with the control
       character, it cannot do so and still be within SCCS file	format.

       Entries	of  the	form ddddd represent a decimal number.	In the statis-
       tics 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 inte-
       ger.

       The usable range	on a specific machine is however limited by the	avail-
       able  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 virtual 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 ac-
       cepted 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	imple-
       mentations from accidentally ignoring project-related  (project-global)
       locks. It permits future	versions to decide on different	checksum algo-
       rithms 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 ver-
       sion number 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 ig-
       nored 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  per-
		     mit 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
       corresponding  to  the  real user ID at the time	the delta was created,
       and the serial 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  ver-
       sions 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
       before storing it in the	history	file.

       The ^Ai,	^Ax, and ^Ag lines contain the serial numbers  of  deltas  in-
       cluded, 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-
       second 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 sec-
       ond 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
       extension 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 appears in	case a rename or remove	operation  has
			been applied to	the file.

			The  project  set home is a directory that holds a di-
			rectory	.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 directory.

			See  also  the description for the same	keyword	in the
			section	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 re-
			trieved	by `get	-e' (without keyword  expansion).   If
			the  file  is  archived	UU-encoded (see	`e' flag), the
			checksum is computed 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  implementa-
       tions.	When  converting a SCCS	v6 history file	back to	a SCCS v4 his-
       tory file, these	entries	are converted into special comment at the  be-
       ginning of the comment section. While converting, a copy	of the unmodi-
       fied ^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 contain-
       ing these login names and/or numerical group IDs	are surrounded by  the
       bracketing  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
       information 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 character 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  defines an MR number	validity checking pro-
			       gram.

			       The v flag and the z flag are  mutually	exclu-
			       sive.

       ^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 key-
			       words 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 ex-
			       panded keywords.	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 re-
			       lease below which no deltas may be added.

       ^Af c ceiling	       Defines the "ceiling" release, that is, the re-
			       lease 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 ex-
			       ample, 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
			       multiple	 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
			       encoded or not. A 1 indicates that the file  is
			       encoded.	  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 contain binary data  to  be  checked
			       in.

       ^Af z application       The name	of an application for the CMF enhance-
			       ments.  CMF enhancements	are currently  undocu-
			       mented  and  it	is  not	known how they are ex-
			       pected to work.

			       The v flag and the z flag are  mutually	exclu-
			       sive.

       ^Af s nnn	       The  number  of lines to	be scanned for keyword
			       expansion.

			       This flag is a SUN extension that does not  ex-
			       ist 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 enabled, the	keywords %d%, %e%, %g%
			       and %h% are expanded 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 com-
			       patibility support for  a  SCO  SCCS  extension
			       that  sets  the executable bit in the file per-
			       missions	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	permissions of
			       the history file.

			       If this version of SCCS is used to  create  the
			       history	file and the executable	bit was	set in
			       the original file, SCCS automatically sets  the
			       executable bit in the history file and thus re-
			       tains 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	expan-
			       sion of the %sccs.include.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 rename, 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(4))
			that  is  used to help to identify single files	across
			renames	during the lifetime of the sccs	history.

			The pseudo random number is a hexadecimal string  that
			represents	  the	     microseconds	 since
			Jul 13 11:01:20	2012 GMT when initially	 creating  the
			sccs history for a specific file.  Including microsec-
			onds 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 number, more than 500000	years are covered.

			The minimal length for the  pseudo  random  number  is
			thirteen  hexadecimal  characters. If the number could
			be represented with less digits,  it  is  left	filled
			with  zeroes.  This allows 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 cre-
       ated.  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 modi-
       fying history files.  This is why SCCS v6 metadata may be kept  unmodi-
       fied  when  converting 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 correct-
       ness. Unknown elements at this location are still copied	and  kept  in-
       tact  when  the	historyfile  is	 modified.  SCCS v6 already introduced
       SCCS v6 flags and global	SCCS v6	metadata as extensions,	so future  ex-
       tensions	must appear past the SCCS v6 metadata.

   Comments
       Arbitrary  text	surrounded  by	the bracketing lines ^At and ^AT.  The
       comments	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
       extensions. 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
       features	 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
		   control  characters	represents  a text line	that begins at
		   the second 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 newline character.	 A line	in the form ^AN^Atext  is  ex-
		   tracted 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  differ-
		   ences 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 ver-
		   sion	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 sccs-
		   file(4) for SCCS v4.	 In order to grant  POSIX  compatibil-
		   ity,	 a  two	 digit year is used between 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
		   completion

       s.file	   SCCS	history	file, see sccsfile(4).

       SCCS/s.file history file	in SCCS	subdirectory

       x.file	   temporary  copy  of the s.file; renamed to the s.file after
		   completion.	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  ex-
		   ist.

       dump.core   If the file dump.core exists	in the current directory and a
		   fatal 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(4).

NOTES
       The following SCCS programs write or modify SCCS	history	files and cre-
       ate 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 cre-
       ated 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.

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
       admin(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 Microsys-
       tems.  Since 2006, the SCCS suite is maintained by Joerg	Schilling.

SunOS 5.11			  2020/06/16			   sccsfile(4)

NAME | DESCRIPTION | FILES | SEE ALSO | NOTES | BUGS | AUTHORS

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=sccsfile&sektion=5&manpath=FreeBSD+13.0-RELEASE+and+Ports>

home | help