summaryrefslogtreecommitdiffstats
path: root/usr.sbin/ctm
diff options
context:
space:
mode:
authorru <ru@FreeBSD.org>2004-07-02 23:13:00 +0000
committerru <ru@FreeBSD.org>2004-07-02 23:13:00 +0000
commit6294018a208cf7742b1c021a9b75c26962505571 (patch)
tree502f17eb951b74c914af346cd4dbff252350c082 /usr.sbin/ctm
parent3f44360851448f8816c22f6b72e8dd5c9924c27f (diff)
downloadFreeBSD-src-6294018a208cf7742b1c021a9b75c26962505571.zip
FreeBSD-src-6294018a208cf7742b1c021a9b75c26962505571.tar.gz
Mechanically kill hard sentence breaks.
Diffstat (limited to 'usr.sbin/ctm')
-rw-r--r--usr.sbin/ctm/ctm/ctm.172
-rw-r--r--usr.sbin/ctm/ctm/ctm.56
-rw-r--r--usr.sbin/ctm/ctm_rmail/ctm_rmail.172
3 files changed, 100 insertions, 50 deletions
diff --git a/usr.sbin/ctm/ctm/ctm.1 b/usr.sbin/ctm/ctm/ctm.1
index cdc75ab..f8ee9d7 100644
--- a/usr.sbin/ctm/ctm/ctm.1
+++ b/usr.sbin/ctm/ctm/ctm.1
@@ -42,21 +42,27 @@ The
utility is now meant to be the definitive way to make and apply a delta between
two versions of a directory tree.
.Pp
-There are two parts to this, making the delta and applying it. These are two
+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
-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
+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
+since it will not have to make a temporary copy of your file.
+You can
specify multiple deltas at one time, they will be processed one at a
-time. Deltas that are already applied will be ignored.
+time.
+Deltas that are already applied will be ignored.
.Pp
The
.Nm
-command runs in a number of passes. It will process the entire
+command runs in a number of passes.
+It will process the entire
input file in each pass, before commencing with the next pass.
.Pp
Before working on a file
@@ -68,13 +74,16 @@ If this file exists,
.Nm
works on it instead.
.Pp
-Pass 1 will verify that the input file is OK. The syntax, the data
-and the global MD5 checksum will be checked. If any of these fail,
+Pass 1 will verify that the input file is OK.
+The syntax, the data
+and the global MD5 checksum will be checked.
+If any of these fail,
.Nm
will simply reject the input file.
.Pp
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
+the CTM delta.
+This is done by looking for files and directories which
should/should not exist and by checking the MD5 checksums of files.
.Pp
If a
@@ -86,7 +95,8 @@ option, all files that would be modified by this
invocation are backed up
to this file using the archiver command specified by the
.Fl t
-option. The default archiver command is
+option.
+The default archiver command is
.Nm "tar -rf %s -T -" .
.Pp
Pass 3 will actually apply the delta.
@@ -103,7 +113,8 @@ The
.Fl e
and
.Fl x
-options are applied in order of appearance on the command line. The last
+options are applied in order of appearance on the command line.
+The last
filter that matched a given file name determines whether the file would be
operated on or left alone by
.Nm .
@@ -111,7 +122,8 @@ operated on or left alone by
The
.Nm
utility
-will extract the file hierarchy below its working directory. Absolute
+will extract the file hierarchy below its working directory.
+Absolute
filenames or filenames containing references through
.Sq Pa .\&
and
@@ -137,10 +149,13 @@ Check it out, don't do anything.
.It Fl e Ar regular_expression
Match each name in the CTM file against
.Ar regular_expression ,
-and if it matches process the file, otherwise leave it alone. There may be
-any number of these options. Use of this option disables the
+and if it matches process the file, otherwise leave it alone.
+There may be
+any number of these options.
+Use of this option disables the
.Pa .ctm_status
-sequence number checks. For example, the expression
+sequence number checks.
+For example, the expression
.Ic ^usr.sbin/ctm
for example, will select the
.Pa usr.sbin/ctm
@@ -153,16 +168,19 @@ option.
Force.
.It Fl k
Keep files and directories and don't remove them even if the CTM file
-specifies they are to be removed. If the
+specifies they are to be removed.
+If the
.Fl B
option is specified, these files and directories will not be backed up.
.It Fl l
List files that would be modified by this invocation of CTM and the
-actions that would be performed on them. Use of the
+actions that would be performed on them.
+Use of the
.Fl l
option disables the
.Pa .ctm_status
-checks and integrity checks on the source tree being operated on. The
+checks and integrity checks on the source tree being operated on.
+The
.Fl l
option can be combined with the
.Fl e
@@ -179,7 +197,8 @@ instead of the default archiver
.Nm tar .
This option takes effect only if a backup file had been specified using the
.Fl B
-option. A %s in the tar command will be replaced by the name of the backup
+option.
+A %s in the tar command will be replaced by the name of the backup
file.
.It Fl T Ar tmpdir
Put temporary files under
@@ -196,8 +215,10 @@ is the level of verbosity.
.It Fl x Ar regular_expression
Match each name in the CTM file against
.Ar regular_expression
-and if it matches, leave the file alone. There may be any number of these
-options. Use of this option disables the
+and if it matches, leave the file alone.
+There may be any number of these
+options.
+Use of this option disables the
.Pa .ctm_status
sequence number checks.
.Pp
@@ -247,7 +268,8 @@ The same effect may be achieved with the
flag.
.Sh FILES
.Pa .ctm_status
-contains the sequence number of the last CTM delta applied. Changing
+contains the sequence number of the last CTM delta applied.
+Changing
or removing this file will greatly confuse
.Nm .
.Pp
@@ -256,7 +278,8 @@ Using the
and
.Fl x
options can update a partial subset of the source tree and causes sources
-to be in an inconsistent state. It is assumed that you know what you are
+to be in an inconsistent state.
+It is assumed that you know what you are
doing when you use these options.
.Sh EXAMPLES
.Bd -literal
@@ -270,7 +293,8 @@ cd ~/lib-srcs
/usr/sbin/ctm -e '^lib' ~ctm/src-cur*
.Ed
.Sh DIAGNOSTICS
-Numerous messages, hopefully self-explanatory. The
+Numerous messages, hopefully self-explanatory.
+The
.Dq noise level
can be adjusted with the
.Fl q ,
diff --git a/usr.sbin/ctm/ctm/ctm.5 b/usr.sbin/ctm/ctm/ctm.5
index 6165c2e..10b0304 100644
--- a/usr.sbin/ctm/ctm/ctm.5
+++ b/usr.sbin/ctm/ctm/ctm.5
@@ -23,7 +23,8 @@ The
.Nm
transfers data in a specific file format, called a CTM delta.
.Pp
-CTM deltas consist of control lines and data chunks. Each control
+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 ends with a '\en'
@@ -38,7 +39,8 @@ newline is not part of the chunk and isn't included in the count.
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
+This is the overall begin of a CTM delta file.
+The
.Ar version
field must match the program version
(currently 2.0).
diff --git a/usr.sbin/ctm/ctm_rmail/ctm_rmail.1 b/usr.sbin/ctm/ctm_rmail/ctm_rmail.1
index 3943fd2..ed32729 100644
--- a/usr.sbin/ctm/ctm_rmail/ctm_rmail.1
+++ b/usr.sbin/ctm/ctm_rmail/ctm_rmail.1
@@ -49,7 +49,8 @@ The
.Nm ctm_smail
utility is given a compressed
.Xr ctm
-delta, and a mailing list to send it to. It splits the delta into manageable
+delta, and a mailing list to send it to.
+It splits the delta into manageable
pieces, encodes them as mail messages and sends them to the mailing list
(optionally queued to spread the mail load).
Each recipient uses
@@ -59,7 +60,8 @@ optionally call
.Xr ctm
to apply it to the source tree.
At the moment,
-several source trees are distributed, and by several sites. These include
+several source trees are distributed, and by several sites.
+These include
the
.Fx Ns -current
source and CVS trees, distributed by
@@ -77,16 +79,22 @@ are time stamped and written to the file
.It Fl m Ar maxmsgsize
Limit the maximum size mail message that
.Nm ctm_smail
-is allowed to send. It is approximate since mail headers and other niceties
-are not counted in this limit. If not specified, it will default to 64000
+is allowed to send.
+It is approximate since mail headers and other niceties
+are not counted in this limit.
+If not specified, it will default to 64000
bytes, leaving room for 1535 bytes of headers before the rumoured 64k mail
limit.
.It Fl c Ar maxctmsize
-Limit the maximum size delta that will be sent. Deltas bigger that this
+Limit the maximum size delta that will be sent.
+Deltas bigger that this
limit will cause an apology mail message to be sent to the mailing list.
-This is to prevent massive changes overwhelming users' mail boxes. Note that
-this is the size before encoding. Encoding causes a 4/3 size increase before
-mail headers are added. If not specified, there is no limit.
+This is to prevent massive changes overwhelming users' mail boxes.
+Note that
+this is the size before encoding.
+Encoding causes a 4/3 size increase before
+mail headers are added.
+If not specified, there is no limit.
.It Fl q Ar queue-dir
Instead of mailing the delta pieces now, store them in the given directory
to be mailed later using
@@ -115,7 +123,8 @@ are time stamped and written to the file
.It Fl n Ar numchunks
Limit the number of mail messages that
.Nm ctm_dequeue
-will send per run. By default,
+will send per run.
+By default,
.Nm ctm_dequeue
will send one mail message per run.
.El
@@ -125,7 +134,8 @@ is the directory containing the mail messages stored by
.Nm ctm_smail .
Up to
.Ar numchunks
-mail messages will be sent in each run. The recipient mailing list is already
+mail messages will be sent in each run.
+The recipient mailing list is already
encoded in the queued files.
.Pp
It is safe to run
@@ -135,7 +145,8 @@ while
is adding entries to the queue, or even to run
.Nm ctm_smail
multiple times concurrently, but a separate queue directory should be used
-for each tree being distributed. This is because entries are served in
+for each tree being distributed.
+This is because entries are served in
alphabetical order, and one tree will be unfairly serviced before any others,
based on the delta names, not delta creation times.
.Pp
@@ -149,8 +160,10 @@ error diagnostics and informational messages (other than command line errors)
are time stamped and written to the file
.Em log .
.It Fl p Ar piecedir
-Collect pieces of deltas in this directory. Each piece corresponds to a
-single mail message. Pieces are removed when complete deltas are built.
+Collect pieces of deltas in this directory.
+Each piece corresponds to a
+single mail message.
+Pieces are removed when complete deltas are built.
If this flag is not given, no input files will be read, but completed
deltas may still be applied with
.Xr ctm
@@ -158,11 +171,14 @@ if the
.Fl b
flag is given.
.It Fl d Ar deltadir
-Collect completed deltas in this directory. Deltas are built from one or
+Collect completed deltas in this directory.
+Deltas are built from one or
more pieces when all pieces are present.
.It Fl b Ar basedir
-Apply any completed deltas to this source tree. If this flag is not given,
-deltas will be stored, but not applied. The user may then apply the deltas
+Apply any completed deltas to this source tree.
+If this flag is not given,
+deltas will be stored, but not applied.
+The user may then apply the deltas
manually, or by using
.Nm ctm_rmail
without the
@@ -217,7 +233,8 @@ Pass the
flag to the
.Xr ctm
command when applying the complete deltas, causing a more informative
-output. All
+output.
+All
.Xr ctm
output appears in the
.Nm ctm_rmail
@@ -226,7 +243,8 @@ log file.
.Pp
The file arguments (or
.Em stdin ,
-if there are none) are scanned for delta pieces. Multiple delta pieces
+if there are none) are scanned for delta pieces.
+Multiple delta pieces
can be read from a single file, so an entire maildrop can be scanned
and processed with a single command.
.Pp
@@ -235,7 +253,8 @@ It is safe to invoke
multiple times concurrently (with different input files),
as might happen when
.Xr sendmail
-is delivering mail asynchronously. This is because locking is used to
+is delivering mail asynchronously.
+This is because locking is used to
keep things orderly.
.Sh FILE FORMAT
Following are the important parts of an actual (very small) delta piece:
@@ -255,7 +274,8 @@ CTM_MAIL END 61065
The subject of the message always begins with
.Dq ctm-mail
followed by the name of the delta, which piece this is, and how many total
-pieces there are. The data are bracketed by
+pieces there are.
+The data are bracketed by
.Dq CTM_MAIL BEGIN
and
.Dq CTM_MAIL END
@@ -429,7 +449,8 @@ The
.Nm ctm_rmail
utility is expected to be called from a mail transfer program, and thus signals
failure only when the input mail message should be bounced (preferably into
-your regular maildrop, not back to the sender). In short, failure to
+your regular maildrop, not back to the sender).
+In short, failure to
apply a completed delta with
.Xr ctm
is not considered an error important enough to bounce the mail, and
@@ -471,14 +492,17 @@ will report:
ctm_rmail: message contains no delta
.Ed
.Pp
-and return an exit status of 1. You can use this to redirect wayward messages
+and return an exit status of 1.
+You can use this to redirect wayward messages
back into your real mailbox if your mail filter goes wonky.
.Pp
These messages go to
.Em stderr
-or to the log file. Messages from
+or to the log file.
+Messages from
.Xr ctm 1
-turn up here too. Error messages should be self explanatory.
+turn up here too.
+Error messages should be self explanatory.
.Sh SEE ALSO
.Xr ctm 1 ,
.Xr ctm 5
OpenPOWER on IntegriCloud