manual/GNU_sharutils/original/man1/shar.1

   1 .TH SHAR 1 "September 10, 1995"
   2 .SH NAME
   3 shar \- create shell archives
   4 .SH SYNOPSIS
   5 .nf
   6 shar [ options ] file ...
   7 shar \-S [ options ]
   8 .fi
   9 .SH DESCRIPTION
  10 Shar
  11 creates "shell archives" (or shar files) which are in text format
  12 and can be mailed.  These files may be unpacked later by executing them
  13 with /bin/sh.  The resulting archive is sent to standard out unless the
  14 \f2\-o\f1 option is given.  A wide range of features provide extensive
  15 flexibility in manufacturing shars and in specifying shar "smartness".
  16 Archives may be "vanilla" or comprehensive.
  17 .SH OPTIONS
  18 .PP
  19 Options have a one letter version starting with \- or a long version starting
  20 with \-\-.  The exception is \f2\-\-help\f1, \f2\-\-version\f1,
  21 \f2\-\-no-i18n\f1 and \f2\-\-print-text-domain-dir\f1 which does not
  22 have short versions.
  23 Mandatory arguments to long options are mandatory for short options too.
  24 Options can be given in any order.  Some options depend on each other:
  25 .nf
  26         The \f2\-o\f1 option is required if the \f2\-l\f1 or \f2\-L\f1 option is used.
  27         The \f2\-n\f1 option is required if the \f2\-a\f1 option is used.
  28         See \f2\-V\f1 below.
  29 .fi
  30 .SS "Giving feedback:"
  31 .IP "\f2\-\-help\f1"
  32 Print a help summary on standard output, then immediately exits.
  33 .IP "\f2\-\-version\f1"
  34 Print the version number of the program on standard output,
  35 then immediately exits.
  36 .IP "\f2\-q\f1 \f2\-\-quiet\f1 \f2\-\-silent\f1"
  37 Do not output verbose messages locally when producing the archive.
  38 .SS "Selecting files:"
  39 .IP "\f2\-p\f1  \f2\-\-intermix-type\f1"
  40 Allow positional parameter options.  The options \f2\-B\f1, \f2\-T\f1,
  41 \f2-z\f1 and \f2\-Z\f1 may be embedded, and files to the right of the
  42 option will be processed in the specified mode.
  43 .IP "\f2\-S\f1  \f2\-\-stdin-file-list\f1"
  44 Read list of files to be packed from the standard input rather
  45 than from the command line.  Input must be in a form similar to
  46 that generated by the find command, one filename per line.  This
  47 switch is especially useful when the command line will not hold
  48 the list of files to be packed.  For example:
  49 .nf
  50
  51 find . \-type f \-print | sort | shar \-S \-Z \-L50 \-o /tmp/big
  52
  53 .fi
  54 If \f2\-p\f1 is specified on the command line, then the options
  55 \f2\-B\f1, \f2\-T\f1, \f2\-z\f1 and \f2\-Z\f1 may be
  56 included in the standard input (on a line separate from filenames).
  57 The maximum number of lines of standard input, file names and
  58 options, may not exceed 1024.
  59 .SS "Splitting output:"
  60 .IP "\f2\-o\f1 XXX  \f2\-\-output-prefix=\f1XXX"
  61 Save the archive to files XXX.01 thru XXX.nn instead of sending it to
  62 standard out.
  63 Must be used when the \f2\-l\f1 or the \f2\-L\f1 switches are used.
  64 .IP "\f2\-l\f1 XX  \f2\-\-whole-size-limit=\f1XX"
  65 Limit the output file size to XXk bytes but don't split input files.
  66 .IP "\f2\-L\f1 XX  \f2\-\-split-size-limit=\f1XX"
  67 Limit output file size to XXk bytes and split files if necessary.  The archive
  68 parts created with this option must be unpacked in correct order.
  69 .SS "Controlling the shar headers:"
  70 .IP "\f2\-n\f1 name  \f2\-\-archive-name=\f1name"
  71 Name of archive to be included in the header of the shar files.
  72 See the \f2\-a\f1 switch.
  73 .IP "\f2\-s\f1 who@where  \f2\-\-submitter=\f1who@where"
  74 Override automatically determined submitter name.
  75 .IP "\f2\-a\f1  \f2\-\-net-headers\f1"
  76 Allows automatic generation of headers:
  77 .nf
  78         Submitted-by: who@where
  79         Archive-name: <name>/part##
  80 .fi
  81 The <name> must be given with the \f2\-n\f1 switch.
  82 If name includes a '/' "/part" isn't used.  Thus:
  83 .RS 10m
  84 .nf
  85 .ta 30n
  86 \-n xyzzy       produces:
  87         xyzzy/part01
  88         xyzzy/part02
  89
  90 \-n xyzzy/patch produces:
  91         xyzzy/patch01
  92         xyzzy/patch02
  93
  94 \-n xyzzy/patch01.      produces:
  95         xyzzy/patch01.01
  96         xyzzy/patch01.02
  97 .RE
  98 .fi
  99 .IP ""
 100 The who@where can be
 101 explicitly stated with the \f2\-s\f1 switch if the default isn't appropriate.
 102 Who@where is essentially built as `whoami`@`uname`.
 103 .IP "\f2\-c\f1  \f2\-\-cut-mark\f1"
 104 Start the shar with a cut line.  A line saying 'Cut here' is placed at the
 105 start of each output file.
 106 .SS "Selecting how files are stocked:"
 107 .IP "\f2\-M\f1  \f2\-\-mixed-uuencode\f1"
 108 Mixed mode.  Determine if the files are text or binary and archive
 109 correctly (default).  Files found to be binary are uudecoded prior to packing
 110 (USE OF UUENCODE IS NOT APPRECIATED BY MANY ON THE NET).
 111 .IP "\f2\-T\f1  \f2\-\-text-files\f1"
 112 Treat all files as text.
 113 .IP "\f2\-B\f1  \f2\-\-uuencode\f1"
 114 Treat all files as binary, use uuencode prior to packing.  This increases the
 115 size of the archive.  The recipient must have uudecode in order to unpack.
 116 (USE OF UUENCODE IS NOT APPRECIATED BY MANY ON THE NET).
 117 .IP "\f2\-z\f1  \f2\-\-gzip\f1"
 118 Gzip and uuencode all files prior to packing.  The recipient must have
 119 uudecode and gzip in order to unpack
 120 (USE OF UUENCODE AND GZIP IS NOT APPRECIATED BY MANY ON THE NET).
 121 .IP "\f2\-g\f1 LEVEL  \f2\-\-level-for-gzip=\f1LEVEL"
 122 When doing compression, use '\-LEVEL' as a parameter to gzip.  Default is 9.
 123 The \f2\-g\f1 option turns on the \f2\-z\f1 option by default.
 124 .IP "\f2\-Z\f1  \f2\-\-compress\f1"
 125 Compress and uuencode all files prior to packing.  The recipient must have
 126 uudecode and compress in order to unpack
 127 (USE OF UUENCODE AND COMPRESS IS NOT APPRECIATED BY MANY ON THE NET).
 128 Option \f2\-C\f1 is synonymous to \f2\-Z\f1, but is being deprecated.
 129 .IP "\f2\-b\f1 BITS  \f2\-\-bits-per-code=\f1BITS"
 130 When doing compression, use '\-bBITS' as a parameter to compress.
 131 The \f2\-B\f1 option turns on the \f2\-Z\f1 option by default.  Default value
 132 is 12.
 133 .SS "Protecting against transmission errors:"
 134 .IP "\f2\-w\f1  \f2\-\-no-character-count\f1"
 135 Do NOT check each file with 'wc \-c' after unpack.  The default is to check.
 136 .IP "\f2\-D\f1  \f2\-\-no-md5-digest\f1"
 137 Do NOT use 'md5sum' digest to verify the unpacked files. The default is to
 138 check.
 139 .IP "\f2\-F\f1  \f2\-\-force-prefix\f1"
 140 Forces the prefix character (normally 'X' unless the parameter to the \f2\-d\f1
 141 option starts with 'X') to be prepended to every line even if
 142 not required.  This option may slightly increase the size of the archive,
 143 especially if \f2\-B\f1 or \f2\-Z\f1 is used.
 144 .IP "\f2\-d\f1 XXX  \f2\-\-here-delimiter=\f1XXX"
 145 Use XXX to delimit the files in the shar instead of SHAR_EOF.
 146 This is for those who want to personalize their shar files.
 147 .SS "Producing different kinds of shars:"
 148 .IP "\f2\-V\f1  \f2\-\-vanilla-operation\f1"
 149 Produce "vanilla" shars which rely only upon the existence of sed and
 150 echo in the unsharing environment.  In addition, "if test" must also
 151 be supported unless the \f2\-x\f1 option is used.  The \f2\-V\f1 silently
 152 disables options offensive to the "network cop" (or "brown shirt"),
 153 but does warn you if it is specified with \f2\-B\f1, \f2-z\f1,
 154 \f2\-Z\f1, \f2\-p\f1 or \f2\-M\f1 (any of which does or might
 155 require uudecode, gzip or compress in the unsharing environment).
 156 .IP "\f2\-P\f1  \f2\-\-no-piping\f1"
 157 Use temporary files instead of pipes in the shar file.
 158 .IP "\f2\-x\f1  \f2\-\-no-check-existing\f1"
 159 Overwrite existing files without checking.
 160 If neither \f2\-x\f1 nor \f2\-X\f1 is specified, the unpack will
 161 check for and not overwrite existing files when unpacking the archive.
 162 If \f2\-c\f1 is passed as a parameter to the script when unpacking:
 163
 164 .RS 10m
 165 sh archive -c
 166 .RE
 167 .IP ""
 168 then existing files will be overwritten unconditionally.
 169 .IP "\f2\-X\f1  \f2\-\-query-user\f1"
 170 When unpacking, interactively ask the user if files should be overwritten.
 171 (DO NOT USE FOR SHARS SUBMITTED TO THE NET).
 172 .IP "\f2\-m\f1  \f2\-\-no-timestamp\f1"
 173 Avoid generating 'touch' commands to restore the file modification
 174 dates when unpacking files from the archive.
 175 .IP "\f2\-Q\f1  \f2\-\-quiet-unshar\f1"
 176 Verbose OFF.  Disables the inclusion of comments to be output when the archive
 177 is unpacked.
 178 .IP "\f2\-f\f1  \f2\-\-basename\f1"
 179 Restore by filename only, rather than path.  This option causes only file
 180 names to be used, which is useful when building a shar from several
 181 directories, or another directory.  Note that if a directory name is passed
 182 to shar, the substructure of that directory will be restored whether \f2\-f\f1
 183 is specified or not.
 184 .SS "Internationalization:"
 185 .IP "\f2\-\-no-i18n\f1"
 186 Do not produce internationalized shell archives, use default english messages.
 187 By default, shar produces archives that will try to output messages in
 188 the unpackers preferred language (as determined by the LANG/LC_MESSAGES
 189 environmental variables) when they are unpacked.
 190 If no message file for the unpackers language is found at unpack time,
 191 messages will be in english.
 192 .IP "\f2\-\-print-text-domain-dir\f1"
 193 Prints the directory shar looks in to find messages files for different
 194 languages, then immediately exits.
 195 .SH EXAMPLES
 196 .nf
 197 .ta 37n
 198 shar *.c > cprog.shar   # all C prog sources
 199 shar \-Q *.[ch] > cprog.shar    # non-verbose, .c and .h files
 200 shar \-B \-l28 \-oarc.sh *.arc  # all binary .arc files, into
 201         # files arc.sh.01 thru arc.sh.NN
 202 shar \-f /lcl/src/u*.c > u.sh   # use only the filenames
 203 .ta
 204 .fi
 205 .SH WARNINGS
 206 .PP
 207 No chmod or touch is ever generated for directories created when unpacking.
 208 Thus, if a directory is given to shar, the protection and
 209 modification dates of corresponding unpacked directory
 210 may not match those of the original.
 211 .PP
 212 If a directory is passed to shar, it may be scanned more than once.  Therefore,
 213 one should be careful not change the directory while shar is running.
 214 .PP
 215 Be careful that the output file(s) are not included in the inputs or shar
 216 may loop until the disk fills up.  Be particularly careful when a directory
 217 is passed to shar that the output files are not in that directory
 218 (or a subdirectory of that directory).
 219 .PP
 220 Use of the \f2\-B\f1, \f2\-z\f1 or \f2\-Z\f1, and especially
 221 \f2\-M\f1, may slow the archive process considerably, depending on
 222 the number of files.
 223 .PP
 224 Use of \f2\-X\f1 produces shars which \f2WILL\f1 cause problems
 225 with many unshar procedures.  Use this feature only for archives
 226 to be passed among agreeable parties.  Certainly, \f2\-X\f1 is NOT
 227 for shell archives which are to be submitted to Usenet.  Usage of
 228 \f2\-B\f1, \f2\-z\f1 or \f2\-Z\f1 in net shars will cause you to
 229 be flamed off the earth.  Not using \f2\-m\f1 or not using \f2\-F\f1
 230 may also get you occasional complaints.
 231 .SH SEE ALSO
 232 .PP
 233 unshar(1)
 234 .SH DIAGNOSTICS
 235 .PP
 236 Error messages for illegal or incompatible options,
 237 for non-regular, missing or inaccessible files or for (unlikely)
 238 memory allocation failure.
 239 .SH AUTHORS
 240 The shar and unshar programs is the collective work of many authors.
 241 Many people contributed by reporting problems, suggesting
 242 various improvements or submitting actual code.  A list of
 243 these people is in the THANKS file in the sharutils distribution.