diff options
author | ru <ru@FreeBSD.org> | 2004-07-02 23:13:00 +0000 |
---|---|---|
committer | ru <ru@FreeBSD.org> | 2004-07-02 23:13:00 +0000 |
commit | 6294018a208cf7742b1c021a9b75c26962505571 (patch) | |
tree | 502f17eb951b74c914af346cd4dbff252350c082 /usr.sbin/ctm | |
parent | 3f44360851448f8816c22f6b72e8dd5c9924c27f (diff) | |
download | FreeBSD-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.1 | 72 | ||||
-rw-r--r-- | usr.sbin/ctm/ctm/ctm.5 | 6 | ||||
-rw-r--r-- | usr.sbin/ctm/ctm_rmail/ctm_rmail.1 | 72 |
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 |