1SHAR(1)                     General Commands Manual                    SHAR(1)
2
3
4

NAME

6       shar - create shell archives
7

SYNOPSIS

9       shar [ options ] file ...
10       shar -S [ options ]
11

DESCRIPTION

13       Shar  creates "shell archives" (or shar files) which are in text format
14       and can be mailed.  These files may be unpacked later by executing them
15       with /bin/sh.  The resulting archive is sent to standard out unless the
16       -o option is given.  A wide range of features provide extensive  flexi‐
17       bility  in manufacturing shars and in specifying shar "smartness".  Ar‐
18       chives may be "vanilla" or comprehensive.
19

OPTIONS

21       Options have a one letter version starting with -  or  a  long  version
22       starting  with  --.   The exception is --help, --version, --no-i18n and
23       --print-text-domain-dir which does not have short versions.   Mandatory
24       arguments to long options are mandatory for short options too.  Options
25       can be given in any order.  Some options depend on each other:
26            The -o option is required if the -l or -L option is used.
27            The -n option is required if the -a option is used.
28            See -V below.
29
30   Giving feedback:
31       --help Print a help summary on standard output, then immediately exits.
32
33       --version
34              Print the version number of the program on standard output, then
35              immediately exits.
36
37       -q --quiet --silent
38              Do  not  output  verbose messages locally when producing the ar‐
39              chive.
40
41   Selecting files:
42       -p  --intermix-type
43              Allow positional parameter options.  The options -B, -T, -z  and
44              -Z may be embedded, and files to the right of the option will be
45              processed in the specified mode.
46
47       -S  --stdin-file-list
48              Read list of files to be packed from the standard  input  rather
49              than  from the command line.  Input must be in a form similar to
50              that generated by the find command, one filename per line.  This
51              switch  is especially useful when the command line will not hold
52              the list of files to be packed.  For example:
53
54              find . -type f -print | \
55                sort | \
56                shar -S -Z -L50 -o /somewhere/big
57
58              If -p is specified on the command line, then the options -B, -T,
59              -z and -Z may be included in the standard input (on a line sepa‐
60              rate from filenames).  The maximum number of lines  of  standard
61              input, file names and options, may not exceed 1024.
62
63   Splitting output:
64       -o XXX  --output-prefix=XXX
65              Save  the archive to files XXX.01 thru XXX.nn instead of sending
66              it to standard out.  Must be used when the -l or the -L switches
67              are used.
68
69       -l XX  --whole-size-limit=XX
70              Limit  the  output  file size to XXk bytes but don't split input
71              files.
72
73       -L XX  --split-size-limit=XX
74              Limit output file size to XXk bytes and split  files  if  neces‐
75              sary.   The  archive  parts  created  with  this  option must be
76              unpacked in correct order.
77
78   Controlling the shar headers:
79       -n name  --archive-name=name
80              Name of archive to be included in the header of the shar  files.
81              See the -a switch.
82
83       -s who@where  --submitter=who@where
84              Override automatically determined submitter name.
85
86       -a  --net-headers
87              Allows automatic generation of headers:
88                   Submitted-by: who@where
89                   Archive-name: <name>/part##
90              The <name> must be given with the -n switch.  If name includes a
91              '/' "/part" isn't used.  Thus:
92                 -n xyzzy                      produces:
93                                               xyzzy/part01
94                                               xyzzy/part02
95
96                 -n xyzzy/patch                produces:
97                                               xyzzy/patch01
98                                               xyzzy/patch02
99
100                 -n xyzzy/patch01.             produces:
101                                               xyzzy/patch01.01
102                                               xyzzy/patch01.02
103
104              The who@where can be explicitly stated with the -s switch if the
105              default  isn't  appropriate.   Who@where is essentially built as
106              `whoami`@`uname`.
107
108       -c  --cut-mark
109              Start the shar with a cut line.  A line  saying  'Cut  here'  is
110              placed at the start of each output file.
111
112       -t  --translate
113              Translate  messages  in  the  script.   If you have set the LANG
114              environment variable, messages printed by shar will  be  in  the
115              specified  language.   The produced script will still be emitted
116              using messages in the lingua franca of the computer world:  Eng‐
117              lish.   This  option will cause the script messages to appear in
118              the languages specified by the  LANG  environment  variable  set
119              when the script is produced.
120
121   Selecting how files are stocked:
122       -M  --mixed-uuencode
123              Mixed  mode.   Determine if the files are text or binary and ar‐
124              chive correctly (default).  Files found to be binary  are  uude‐
125              coded  prior  to  packing (USE OF UUENCODE IS NOT APPRECIATED BY
126              MANY ON THE NET).
127
128       -T  --text-files
129              Treat all files as text.
130
131       -B  --uuencode
132              Treat all files as binary, use uuencode prior to packing.   This
133              increases  the  size  of  the  archive.  The recipient must have
134              uudecode in order to unpack.  (USE OF UUENCODE IS  NOT  APPRECI‐
135              ATED BY MANY ON THE NET).
136
137       -z  --gzip
138              Gzip  and  uuencode  all  files prior to packing.  The recipient
139              must have uudecode and gzip in order to unpack (USE OF  UUENCODE
140              AND GZIP IS NOT APPRECIATED BY MANY ON THE NET).
141
142       -g LEVEL  --level-for-gzip=LEVEL
143              When  doing  compression,  use  '-LEVEL' as a parameter to gzip.
144              Default is 9.  The -g option turns on the -z option by default.
145
146       -Z  --compress
147              Compress and uuencode all files prior to packing.  The recipient
148              must have uudecode and compress in order to unpack (USE OF UUEN‐
149              CODE AND COMPRESS IS  NOT  APPRECIATED  BY  MANY  ON  THE  NET).
150              Option -C is synonymous to -Z, but is being deprecated.
151
152       -b BITS  --bits-per-code=BITS
153              When doing compression, use '-bBITS' as a parameter to compress.
154              The -B option turns on the -Z option by default.  Default  value
155              is 12.
156
157   Protecting against transmission errors:
158       -w  --no-character-count
159              Do  NOT  check each file with 'wc -c' after unpack.  The default
160              is to check.
161
162       -D  --no-md5-digest
163              Do NOT use 'md5sum' digest to verify  the  unpacked  files.  The
164              default is to check.
165
166       -F  --force-prefix
167              Forces  the  prefix character (normally 'X' unless the parameter
168              to the -d option starts with 'X') to be prepended to every  line
169              even  if  not  required.   This option may slightly increase the
170              size of the archive, especially if -B or -Z is used.
171
172       -d XXX  --here-delimiter=XXX
173              Use XXX to delimit the files in the shar  instead  of  SHAR_EOF.
174              This is for those who want to personalize their shar files.
175
176   Producing different kinds of shars:
177       -V  --vanilla-operation
178              Produce  "vanilla"  shars  which rely only upon the existence of
179              sed and echo in the unsharing  environment.   In  addition,  "if
180              test"  must also be supported unless the -x option is used.  The
181              -V silently disables options offensive to the "network cop"  (or
182              "brown  shirt"),  but  does warn you if it is specified with -B,
183              -z, -Z, -p or -M (any of which does or might  require  uudecode,
184              gzip or compress in the unsharing environment).
185
186       -P  --no-piping
187              Use temporary files instead of pipes in the shar file.
188
189       -x  --no-check-existing
190              Overwrite existing files without checking.  If neither -x nor -X
191              is specified, the unpack will check for and not overwrite exist‐
192              ing  files  when  unpacking  the  archive.  If -c is passed as a
193              parameter to the script when unpacking:
194
195                 sh archive -c
196
197              then existing files will be overwritten unconditionally.
198
199       -X  --query-user
200              When unpacking, interactively ask the user if  files  should  be
201              overwritten.  (DO NOT USE FOR SHARS SUBMITTED TO THE NET).
202
203       -m  --no-timestamp
204              Avoid  generating 'touch' commands to restore the file modifica‐
205              tion dates when unpacking files from the archive.
206
207       -Q  --quiet-unshar
208              Verbose OFF.  Disables the inclusion of comments  to  be  output
209              when the archive is unpacked.
210
211       -f  --basename
212              Restore  by filename only, rather than path.  This option causes
213              only file names to be used, which is useful when building a shar
214              from  several directories, or another directory.  Note that if a
215              directory name is passed  to  shar,  the  substructure  of  that
216              directory will be restored whether -f is specified or not.
217
218   Internationalization:
219       --no-i18n
220              Do  not  produce  internationalized  shell archives, use default
221              english messages.  By default, shar produces archives that  will
222              try  to  output messages in the unpackers preferred language (as
223              determined by the LANG/LC_MESSAGES environmental variables) when
224              they  are  unpacked.   If no message file for the unpackers lan‐
225              guage is found at unpack time, messages will be in english.
226
227       --print-text-domain-dir
228              Prints the directory shar looks in to find  messages  files  for
229              different languages, then immediately exits.
230

EXAMPLES

232       shar *.c > cprog.shar                # all C prog sources
233       shar -Q *.[ch] > cprog.shar          # non-verbose, .c and .h files
234       shar -B -l28 -oarc.sh *.arc          # all binary .arc files, into
235                                            # files arc.sh.01 thru arc.sh.NN
236       shar -f /lcl/src/u*.c > u.sh         # use only the filenames
237

WARNINGS

239       No  chmod  or  touch  is  ever  generated  for directories created when
240       unpacking.  Thus, if a directory is given to shar, the  protection  and
241       modification  dates  of  corresponding unpacked directory may not match
242       those of the original.
243
244       If a directory is passed to shar, it may be  scanned  more  than  once.
245       Therefore, one should be careful not change the directory while shar is
246       running.
247
248       Be careful that the output file(s) are not included in  the  inputs  or
249       shar  may loop until the disk fills up.  Be particularly careful when a
250       directory is passed to shar that the  output  files  are  not  in  that
251       directory (or a subdirectory of that directory).
252
253       Use  of  the  -B,  -z  or  -Z,  and especially -M, may slow the archive
254       process considerably, depending on the number of files.
255
256       Use of -X produces shars which WILL cause  problems  with  many  unshar
257       procedures.   Use  this  feature  only  for archives to be passed among
258       agreeable parties.  Certainly, -X is NOT for shell archives  which  are
259       to  be  submitted  to  Usenet.  Usage of -B, -z or -Z in net shars will
260       cause you to be flamed off the earth.  Not using -m or not using -F may
261       also get you occasional complaints.
262

SEE ALSO

264       unshar(1)
265

DIAGNOSTICS

267       Error  messages  for  illegal or incompatible options, for non-regular,
268       missing or inaccessible files or for (unlikely) memory allocation fail‐
269       ure.
270

AUTHORS

272       The  shar  and  unshar programs is the collective work of many authors.
273       Many people  contributed  by  reporting  problems,  suggesting  various
274       improvements  or  submitting actual code.  A list of these people is in
275       the THANKS file in the sharutils distribution.
276

REPORTING BUGS

278       Report bugs to <bug-gnu-utils@gnu.org>.  Please put sharutils or  uuen‐
279       code in the subject line.  It helps to spot the message.
280
281
282
283                                 July 1, 2005                          SHAR(1)
Impressum