cprogs/summer.1

   1 .TH SUMMER "1" "December 2006" "Debian" "Chiark-utils-bin"
   2 .SH NAME
   3 summer \- print checksum and system metainformation for files
   4 .SH SYNOPSIS
   5 .B summer -ACDbfqtx
   6 .RI [\| startpoint ...]
   7 .br
   8 .SH DESCRIPTION
   9 .B summer
  10 prints the MD5 checksum of the contents, and the system
  11 metainformation (ownership, permissions, timestamps, etc.), for a
  12 file, or recursively for a whole directory tree.
  13
  14 Each command line argument should be a file or directory to be processed;
  15 if it is a directory then it will be processed and then its contents will
  16 also be processed, recursively. If no
  17 .IR startpoint s
  18 are specified on the command line then
  19 .B summer
  20 will read a list of newline-separated startpoints from standard input.
  21
  22 Since
  23 .B summer
  24 correctly handles devices, FIFOs and other non-regular files it is useful
  25 for generating and comparing summaries of arbitrary directory trees where
  26 md5sum alone would not be.
  27 .SH OUTPUT FORMAT
  28 .B summer
  29 prints one line of information for each filesystem object it processes.
  30 Each line has the following columns:
  31 .TS
  32 tab (@);
  33 l l.
  34 @MD5 checksum (in hex) or file type information
  35 @Size of file in bytes
  36 @File access rights (in octal)
  37 @User ID of owner (in decimal)
  38 @Group ID of owner (in decimal)
  39 @atime (time of last access, decimal time_t)
  40 @mtime (time of last modification)
  41 @ctime (time of last status change)
  42 @Filename
  43 .TE
  44
  45 For regular files, the first column is the md5sum. For directories, pipes,
  46 symlinks and sockets it is the literal string \fBdir\fR, \fBmountpoint\fR, \fBpipe\fR, \fBsymlink\fR or \fBsocket\fR
  47 as appropriate. For devices it begins with \fBc\fR for character or \fBb\fR for block
  48 devices, followed by the device number as a single 32 bit hex number and as
  49 four separate 8 bit decimal numbers (most significant first).
  50
  51 Note that any bytes in the filename other than printing 7-bit ASCII
  52 are escaped using
  53 .B \\\x\c
  54 .I NN
  55 syntax, where
  56 .I NN
  57 are two hex digits; backslashes are also escaped in this way.
  58 This makes the output unambiguous.  Filenames will be relative
  59 if the relevant
  60 .I startpoint
  61 was relative, and absolute if it was absolute.
  62
  63 For symlinks the filename column is followed by `\fB -> \fR' (note the
  64 spaces) and the target of the link, again escaped, as above.
  65 .SH OPTIONS
  66 .TP
  67 .B \-A
  68 Do not print the atime (time of last access). The atime column will be omitted.
  69 .TP
  70 .B \-C
  71 Do not print the ctime (time of last status change). The ctime column will be omitted.
  72 .TP
  73 .B \-M
  74 Do not print the mtime (time of last modification). The mtime column will be omitted.
  75 .TP
  76 .B \-D
  77 Do not print directory sizes. The size column for directories will read \fBdir\fR.
  78 .TP
  79 .B \-b
  80 Do not print mtime (time of last modification) for symbolic links. The mtime field
  81 for symbolic links will read \fBlink\fR.
  82 .TP
  83 .B \-B
  84 Do not print any times for special files, symlinks,
  85 sockets, or fifos.  The atime, mtime and ctime fields
  86 for these objects will read
  87 .BR char ", " block ", " link  ", " sock " or " pipe
  88 instead.
  89 .TP
  90 .B \-f
  91 Include information about errors encountered (for example, unreadable files)
  92 in the output, and continue processing. The default is to print error information
  93 to standard error and stop immediately an error is encountered.
  94 .TP
  95 .B \-x
  96 Do not cross mountpoints while recursing into subdirectories.
  97 Startpoints which are mountpoints \fIare\fR descended into.
  98 .TP
  99 .B \-q
 100 Suppress the progress information which
 101 .B summer
 102 normally prints to standard error.
 103 .TP
 104 .B \-t
 105 Set the field separator between the information and the filename to a
 106 tab character (default is space).
 107 .TP
 108 .B \-f
 109 Normally any errors (problems accessing files including nonexistent
 110 startpoings, and the like) are fatal; an error message is reported to
 111 stderr.
 112
 113 With
 114 .B -f
 115 errors are nonfatal and the problems are reported inline.  The
 116 filesystem object with the problem is reported in the normal way
 117 except that instead of the checksum, the string
 118 \fB\\[\fR\fIproblem\fR[\fB:\fR\ \fIdetails\fR]\fB]\fR
 119 appears.  Fields whose value could not be determined are printed
 120 as \fB?\fR.
 121 .TP
 122 .B \-h
 123 Print a brief usage message to stderr (and do nothing else, exiting nonzero).
 124 .SH PARSING THE OUTPUT
 125 If the first character in the line is \fB\\[\fR, then the first
 126 (checksum or type) field is everything until the first subsequent
 127 \fB]\fR; this may be of variable length and will be followed by one or
 128 more spaces.  Otherwise the first field has a fixed width: 64
 129 characters, the size of an MD5 checksum represented in hex, and is
 130 followed by a single space.
 131
 132 The metadata fields are space-separated but are also space-padded to a
 133 minimum width: 10 characters for sizes and times and ids; 4 characters
 134 for the mode.
 135
 136 The filename field, and optional link target information, are of
 137 variable length, but they are escaped so that they do not contain
 138 spaces.
 139 .SH AUTHOR
 140 .B summer
 141 is
 142 .br
 143 Copyright (C) 2003-2007 Ian Jackson <ian@chiark.greenend.org.uk>
 144
 145 This manpage was written by Peter Maydell
 146 and subsequently improved by Ian Jackson.  It is
 147 .br
 148 Copyright (C) 2006 Peter Maydell <pmaydell@chiark.greenend.org.uk>
 149 .br
 150 Copyright (C) 2007 Ian Jackson <ian@chiark.greenend.org.uk>
 151
 152 This is free software, distributed under the GNU General Public
 153 Licence, version 3 or (at your option) any later version; see
 154 /usr/share/doc/chiark-utils-bin/copyright or
 155 /usr/share/common-licenses/GPL-3
 156 for copying conditions.  There is NO
 157 warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.