Added a man page for the ctm(1) command, as well as a format description

for the CTM deltas.

Largely based on Poul-Henning's README, and the source code.

3 files changed, 355 insertions, 2 deletions

diff --git a/usr.sbin/ctm/ctm/Makefile b/usr.sbin/ctm/ctm/Makefile
index 3d77453..eac2620 100644
--- a/usr.sbin/ctm/ctm/Makefile
+++ b/usr.sbin/ctm/ctm/Makefile
@@ -6,7 +6,7 @@
 # this stuff is worth it, you can buy me a beer in return.   Poul-Henning Kamp
 # ----------------------------------------------------------------------------
 #
-# $Id: Makefile,v 1.6 1994/10/24 20:09:18 phk Exp $
+# $Id: Makefile,v 1.7 1995/03/04 20:36:44 phk Exp $
 #
 
 PROG=		ctm
@@ -15,7 +15,8 @@ SRCS=   	ctm.c ctm_input.c ctm_pass1.c ctm_pass2.c ctm_pass3.c \
 		ctm_syntax.c ctm_ed.c
 LDADD+=		-lmd
 DPADD+=		${LIBMD}
-NOMAN=		1
+MAN1=		ctm.1
+MAN5=		ctm.5
 CFLAGS+=	-Wall -g
 
 .if exists(${.CURDIR}/../../Makefile.inc)
diff --git a/usr.sbin/ctm/ctm/ctm.1 b/usr.sbin/ctm/ctm/ctm.1
new file mode 100644
index 0000000..9deeb85
--- /dev/null
+++ b/usr.sbin/ctm/ctm/ctm.1
@@ -0,0 +1,146 @@
+.\"----------------------------------------------------------------------------
+.\""THE BEER-WARE LICENSE" (Revision 42): 
+.\"<joerg@freebsd.org> wrote this file.  As long as you retain this notice you
+.\"can do whatever you want with this stuff. If we meet some day, and you think
+.\"this stuff is worth it, you can buy me a beer in return.   Poul-Henning Kamp
+.\"----------------------------------------------------------------------------
+.\"
+.\" This manual page is partially obtained from Poul-Hennings CTM README
+.\" file.
+.\"
+.\" CTM and ctm(1) by <phk@login.dknet.dk>
+.\"
+.\" $Id$
+.\"
+.Dd Mar 25, 1995
+.Os
+.Dt CTM 1
+.Sh NAME
+.Nm ctm
+.Nd source code mirror program
+.Sh SYNOPSIS
+.Nm ctm
+.Op Fl cFpPqv
+.Op Fl T Ar tmpdir
+.Ar file Op ...
+.Sh DESCRIPTION
+.Nm Ctm
+was originally
+.Dq Cvs Through eMail ,
+but has since changed scope to be much more general.
+
+.Nm Ctm
+is now meant to be the definitive way to make and apply a delta between
+two versions of a directory tree.
+
+There are two parts to this, making the delta and applying it.  These are two
+entirely different things.
+
+.Ss Usage
+
+To apply a CTM delta, you pass it to the
+.Nm ctm
+command.  You can pass a CTM delta on stdin, or you can give the
+filename as an argument.  If you do the latter, you make life a lot
+easier for your self, since the program can accept gzip'ed files and
+since it will not have to make a temporary copy of your file.  You can
+specify multiple deltas at one time, they will be proccessed one at a
+time.  Deltas that are already applied will be ignored.
+
+The
+.Nm ctm
+command runs in a number of passes.  It will process the entire
+input file in each pass, before commencing with the next pass.
+
+Pass 1 will validate that the input file is OK.  The syntax, the data
+and the global MD5 checksum will be checked.  If any of these fail,
+.Nm ctm
+will never be able to do anything with the file, so it will simply
+reject it.
+
+Pass 2 will validate that the directory tree is in the state expected by
+the CTM delta.  This is done by looking for files and directories which
+should/should not exists and by checking the MD5 checksums of files.  
+
+Pass 3 will actually apply the delta.
+
+.Nm Ctm
+will extract the file hierarchy below its working directory.  Absolute
+filenames or filenames containing references through
+.Sq \&.
+and
+.Sq \&.\&.
+are explicitly prohibited as a security measure.
+
+.Ss Options
+
+.Bl -tag -width indent -compact
+
+.It Fl c
+Check it out, don't do anything.
+
+.It Fl F
+Force.
+
+.It Fl p
+Less paranoid.
+
+.It Fl P
+Paranoid.
+
+.It Fl q
+Tell us less.
+
+.It Fl T Ar tmpdir
+Put temporary files under
+.Ar tmpdir .
+
+.It Fl v
+Tell us more.
+
+.El
+
+
+.Sh FILES
+
+.Pa .ctm_status
+contains the sequence number of the last CTM delta applied.  Changing
+or removing this file will greatly confuse
+.Nm ctm .
+
+.Sh EXAMPLES
+
+.Bd -literal
+
+cd ~cvs
+/usr/sbin/ctm ~ctm/cvs-*
+
+.Ed
+
+.Sh DIAGNOSTICS
+
+Numerous messages, hopefully self-explaining.  The
+.Dq noise level
+can be adjusted with the
+.Fl q
+and
+.Fl v
+options.
+
+.Sh SEE ALSO
+
+.Xr ctm 5
+.Pq yet to be written .
+
+.Sh HISTORY
+
+The
+.Nm ctm
+command appeared in FreeBSD 2.1.
+
+.Sh AUTHORS
+
+The CTM system has been designed and implemented by
+Poul-Henning Kamp
+.Aq phk@FreeBSD.org .
+
diff --git a/usr.sbin/ctm/ctm/ctm.5 b/usr.sbin/ctm/ctm/ctm.5
new file mode 100644
index 0000000..a3bd0e0
--- /dev/null
+++ b/usr.sbin/ctm/ctm/ctm.5
@@ -0,0 +1,206 @@
+.\"----------------------------------------------------------------------------
+.\""THE BEER-WARE LICENSE" (Revision 42): 
+.\"<joerg@freebsd.org> wrote this file.  As long as you retain this notice you
+.\"can do whatever you want with this stuff. If we meet some day, and you think
+.\"this stuff is worth it, you can buy me a beer in return.   Poul-Henning Kamp
+.\"----------------------------------------------------------------------------
+.\"
+.\" This manual page is partially obtained from Poul-Hennings CTM README
+.\" file.
+.\"
+.\" CTM and ctm(1) by <phk@login.dknet.dk>
+.\"
+.\" $Id$
+.\"
+.Dd March 25, 1995
+.Os
+.Dt CTM 5
+.Sh NAME
+.Nm ctm
+.Nd source code mirror system
+
+.Sh DESCRIPTION
+The
+.Nm ctm
+system uses a specific file format, called a CTM delta.
+
+CTM deltas consist of control lines and data chunks.  Each control
+line starts with the letters
+.Dq CTM ,
+followed by a CTM statement and control data, and continues up to
+the end of line.
+
+The CTM statements are as follows.
+
+.Bl -tag -width indent
+
+.It _BEGIN Ar version name number timestamp prefix
+
+This is the overall begin of a CTM delta file.  The
+.Ar version
+field must match the program version
+.Pq currently 2.0 .
+.Ar Name
+is the name and
+.Ar number
+the sequence number of the CTM service, it is matched against the file
+.Pa .ctm_status
+to see if the delta has already been applied.
+.Ar Timestamp
+contains the year, month, day, hour, minute, and second of the
+time of delta creation for reference
+.Po
+followed by the letter
+.Sq Z
+meaning this is a UTC timestamp
+.Pc .
+The
+.Ar prefix
+field is currently always
+.Sq \&. .
+
+.It _END Ar md5
+
+This statement ends the CTM delta, the global
+.Ar md5
+checksum is matched against the entire delta to ensure it has been
+transfered correctly.
+
+.It \&FM Ar name uid gid mode md5 count
+
+Make the file
+.Ar name ,
+the original file had the uid
+.Ar uid
+.Pq numerical, decimal ,
+the gid
+.Ar gid
+.Pq numerical, decimal ,
+mode
+.Ar mode
+.Pq numerical, octal ,
+and the MD5 checksum
+.Ar md5 .
+
+The following
+.Ar count
+bytes data are the contents of the new file.
+
+.It \&FS Ar name uid gid mode md5before md5after count
+
+Substitute the contents of file
+.Ar name ,
+the original file had the new uid
+.Ar uid
+.Pq numerical, decimal ,
+the new gid
+.Ar gid
+.Pq numerical, decimal ,
+new mode
+.Ar mode
+.Pq numerical, octal ,
+the old MD5 checksum
+.Ar md5before ,
+and the new MD5 checksum
+.Ar md5after .
+
+The following
+.Ar count
+bytes data are the contents of the new file.
+
+File substitution is used if the commands to edit a file would exceed
+the total file length, so substituting it is more efficient.
+
+
+.It \&FN Ar name uid gid mode md5before md5after count
+
+Edit the file
+.Ar name .
+The arguments are as above, but the data sections contains an
+.Xr ed 1
+like script to edit the file contents.
+
+.It \&FR Ar name md5
+
+Remove the file
+.Ar name ,
+which must match the MD5 checksum
+.Ar md5 .
+
+
+.It \&AS Ar name uid gid mode
+
+The original file
+.Ar name
+changed its owner to
+.Ar uid ,
+its group to
+.Ar gid ,
+and/or its mode to
+.Ar mode .
+
+
+.It \&DM Ar name uid gid mode
+
+The directory
+.Ar name
+is to be created, it had originally the owner
+.Ar uid ,
+group
+.Ar gid ,
+and mode
+.Ar mode .
+
+
+.It \&DR name
+
+The directory
+.Ar name
+is to be removed.
+
+
+.El
+
+.Sh EXAMPLES
+
+In the following example, long lines have been folded to make them
+printable
+.Pq marked by backslashes .
+
+.Bd -literal
+
+CTM_BEGIN 2.0 cvs-cur 485 19950324214652Z .
+CTMFR src/sys/gnu/i386/isa/scd.c,v 5225f13aa3c7e458f9dd0d4bb637b18d
+CTMFR src/sys/gnu/i386/isa/scdreg.h,v e5af42b8a06f2c8030b93a7d71afb223
+CTMDM src/sys/gnu/i386/isa/Attic 0 552 775
+CTMFS .ctm_status 545 552 664 d9ccd2a84a9dbb8db56ba85663adebf0 \\
+e2a10c6f66428981782a0a18a789ee2e 12
+cvs-cur 485
+
+CTMFN CVSROOT/commitlogs/gnu 545 552 664 \\
+5d7bc3549140d860bd9641b5782c002d 7fb04ed84b48160c9b8eea84b4c0b6e3 394
+a6936 21
+ache        95/03/24 09:59:50
+
+  Modified:    gnu/lib/libdialog kernel.c prgbox.c
+  Log:
+[...]
+CTM_END 74ddd298d76215ae45a077a4b6a74e9c
+
+.Ed
+
+.Sh SEE ALSO
+
+.Xr ctm 1 ;
+.Xr ed 1 .
+
+.Sh HISTORY
+
+The CTM system has been made publically available in FreeBSD 2.1.
+
+.Sh AUTHORS
+
+The CTM system has been designed and implemented by
+Poul-Henning Kamp
+.Aq phk@FreeBSD.org .
+