1shar(1) User Commands shar(1)
2
6 shar - create a shell archive
7
9 shar [-flag [value]]... [--opt-name[[=| ]value]]... [file ...]
10 If no files are specified, the list of input files is read from a stan‐
12 dard input. Standard input must not be a terminal.
13
15 shar creates "shell archives" (or shar files) which are in text format
16 and can be emailed. These files may be unpacked later by executing
17 them with /bin/sh. The resulting archive is sent to standard out
18 unless the -o option is given. A wide range of features provide exten‐
19 sive flexibility in manufacturing shars and in specifying shar "smart‐
20 ness". Archives may be fairly simple (--vanilla-operation) or essen‐
21 tially a mailable tar archive. Options may be specified in any order
22 until a file argument is recognized. If the --intermix-type option has
23 been specified, more compression and encoding options will be recog‐
24 nized between the file arguments. Though this program supports uuen‐
25 code-d files, they are deprecated. If you are emailing files, please
26 consider mime-encoded files. If you do uuencode, base 64 is the pre‐
27 ferred encoding method.
28
30 specifying compression
31 -p, --intermix-type
32 specify compression for input files. This option must not
33 appear in combination with any of the following options:
34 vanilla-operation.
35 Allow positional parameter options. The compression method and
37 encoding method options may be intermixed with file names.
38 Files named after these options will be processed in the speci‐
39 fied way.
40 -C program, --compactor=program
42 specify compaction (compression) program. This option may
43 appear an unlimited number of times. This option must not
44 appear in combination with any of the following options:
45 vanilla-operation.
46 The gzip, bzip2 and compress compactor commands may be specified
48 by the program name as the option name, e.g. --gzip. Those
49 options, however, are being deprecated. There is also the xz
50 compactor now. Specify xz with -C xz or --compactor=xz.
51 Specifying the compactor "none" will then disable file compres‐
53 sion, even for non-text files. Any other compactor will force
54 uuencoding of files, and the recipient must have uudecode to
55 unpack the archive. (Compressed files are never processed as
56 plain text.)
57 Specifying the compactor compress is deprecated.
59 -g level, --level-of-compression=level
61 pass LEVEL for compression. This option takes an integer number
62 as its argument. The value of level is constrained to being:
63 in the range 1 through 9
64 The default level for this option is:
65 9
66 Some compression programs allow for a level of compression. The
68 default is 9, but this option allows you to specify something
69 else. This value is used by gzip, bzip2 and xz, but not com‐
70 press.
71 -j, --bzip2
73 bzip2 and uuencode files. This option may appear an unlimited
74 number of times.
75 bzip2 compress and uuencode all files prior to packing. The
77 recipient must have uudecode bzip2 in order to unpack.
78 NOTE: THIS OPTION IS DEPRECATED
80 -z, --gzip
82 gzip and uuencode files. This option may appear an unlimited
83 number of times.
84 gzip compress and uuencode all files prior to packing. The
86 recipient must have uudecode and gzip in order to unpack.
87 NOTE: THIS OPTION IS DEPRECATED
89 -Z, --compress
91 compress and uuencode files. This option may appear an unlim‐
92 ited number of times.
93 compress and uuencode all files prior to packing. The recipient
95 must have uudecode and compress in order to unpack.
96 NOTE: THIS OPTION IS DEPRECATED
98 --level-for-gzip
100 This is an alias for the --level-of-compression option.
101 NOTE: THIS OPTION IS DEPRECATED
103 -b bits, --bits-per-code=bits
105 pass bits (default 12) to compress. The default bits for this
106 option is:
107 12
108 This is the compression factor used by the compress program.
110 NOTE: THIS OPTION IS DEPRECATED
112 specifying file encoding methodology
114 Files may be stored in the shar either as plain text or uuencoded. By
115 default, the program selects which by examining the file. You may
116 force the selection for all files. In intermixed option/file mode,
117 this setting may be changed during processing.
118 -M, --mixed-uuencode
120 decide uuencoding for each file. This option is a member of the
121 mixed-uuencode class of options.
122 Automatically determine if the files are text or binary and ar‐
124 chive correctly. Files found to be binary are uuencoded prior
125 to packing. This is the default behavior for shar.
126 For a file to be considered a text file instead of a binary
128 file, all the following should be true:
129 The file does not contain any ASCII control character besides BS
131 (backspace), HT (horizontal tab), LF (new line) or FF (form
132 feed).
133 The file contains no character with its eighth-bit set.
135 The file contains no line beginning with the five letters "from
137 ", capitalized or not. (Mail handling programs will often gra‐
138 tuitously insert a > character before it.)
139 The file is either empty or ends with a LF (newline) byte.
141 No line in the file contains more than 200 characters. For
143 counting purpose, lines are separated by a LF (newline).
144 -B, --uuencode
146 treat all files as binary. This option is a member of the
147 mixed-uuencode class of options.
148 Use uuencode prior to packing all files. This increases the
150 size of the archive. The recipient must have uudecode in order
151 to unpack. Compressed files are always encoded.
152 -T, --text-files
154 treat all files as text. This option is a member of the mixed-
155 uuencode class of options.
156 If you have files with non-ascii bytes or text that some mail
158 handling programs do not like, you may find difficulties. How‐
159 ever, if you are using FTP or SSH/SCP, the non-conforming text
160 files should be okay.
161 specifying file selection and output modes
163 -o prefix, --output-prefix=prefix
164 print output to file PREFIX.nn.
165 Save the archive to files prefix.01 thru prefix.nn instead of
167 sending all output to standard out. Must be specified when the
168 --whole-size-limit or --split-size-limit options are specified.
169 When prefix contains a % character, prefix is then interpreted
171 as a sprintf format, which should be able to display a single
172 decimal number. When prefix does not contain such a % charac‐
173 ter, the string .%02d is internally appended.
174 -l size, --whole-size-limit=size
176 split archive, not files, to size. This option is a member of
177 the whole-size-limit class of options. This option must appear
178 in combination with the following options: output-prefix. This
179 option takes an integer number as its argument. The value of
180 size is constrained to being:
181 in the range 8 through 1023, or
182 in the range 8192 through 4194304
183 Limit the output file size to size bytes, but don't split input
185 files. If size is less than 1024, then it will be multiplied by
186 1024. The value may also be specified with a k, K, m or M suf‐
187 fix. The number is then multiplied by 1000, 1024, 1000000, or
188 1048576, respectively. 4M (4194304) is the maximum allowed.
189 Unlike the split-size-limit option, this allows the recipient of
191 the shell archives to be unpacked in any order.
192 -L size, --split-size-limit=size
194 split archive or files to size. This option is a member of the
195 whole-size-limit class of options. This option must appear in
196 combination with the following options: output-prefix. This
197 option takes an integer number as its argument. The value of
198 size is constrained to being:
199 in the range 8 through 1023, or
200 in the range 8192 through 4194304
201 Limit output file size to size bytes, splitting files if neces‐
203 sary. The allowed values are specified as with the --whole-
204 size-limit option.
205 The archive parts created with this option must be unpacked in
207 the correct order. If the recipient of the shell archives wants
208 to put all of them in a single email folder (file), they will
209 have to be saved in the correct order for unshar to unpack them
210 all at once (using one of the split archive options). see:
211 unshar Invocation.
212 -I file, --input-file-list=file
214 read file list from a file.
215 This option causes file to be reopened as standard input. If no
217 files are found on the input line, then standard input is read
218 for input file names. Use of this option will prohibit input
219 files from being listed on the command line.
220 Input must be in a form similar to that generated by find, one
222 filename per line. This switch is especially useful when the
223 command line will not hold the list of files to be archived.
224 If the --intermix-type option is specified on the command line,
226 then the compression options may be included in the standard
227 input on lines by themselves and no file name may begin with a
228 hyphen.
229 For example:
231 { echo --compact xz
232 find . -type f -print | sort
233 } | shar -S -p -L50K -o /somewhere/big
234 -S, --stdin-file-list
236 read file list from standard input.
237 This option is actually a no-op. It is a wrapper for --input-
239 file-list=-.
240 NOTE: THIS OPTION IS DEPRECATED
242 Controlling the shar headers
244 -n name, --archive-name=name
245 use name to document the archive.
246 Name of archive to be included in the subject header of the shar
248 files. See the --net-headers option.
249 -s who@where, --submitter=who@where
251 override the submitter name.
252 shar will normally determine the submitter name by querying the
254 system. Use this option if it is being done on behalf of
255 another.
256 -a, --net-headers
258 output Submitted-by: & Archive-name: headers. This option must
259 appear in combination with the following options: archive-name.
260 Adds specialized email headers:
262 Submitted-by: who@@where
263 Archive-name: name/part##
264 The who@@where is normally derived, but can be specified with
265 the --submitter option. The name must be provided with the
266 --archive-name option. If the archive name includes a slash (/)
267 character, then the /part## is omitted. Thus -n xyzzy produces:
268 xyzzy/part01
269 xyzzy/part02
270 while -n xyzzy/patch produces:
272 xyzzy/patch01
273 xyzzy/patch02
274 and -n xyzzy/patch01. produces:
276 xyzzy/patch01.01
277 xyzzy/patch01.02
278 -c, --cut-mark
280 start the shar with a cut line.
281 A line saying 'Cut here' is placed at the start of each output
283 file.
284 -t, --translate
286 translate messages in the script.
287 Translate messages in the script. If you have set the LANG
289 environment variable, messages printed by shar will be in the
290 specified language. The produced script will still be emitted
291 using messages in the lingua franca of the computer world: Eng‐
292 lish. This option will cause the script messages to appear in
293 the languages specified by the LANG environment variable set
294 when the script is produced.
295 Protecting against transmission issues:
297 --no-character-count
298 do not use `wc -c' to check size.
299 Do NOT check each file with 'wc -c' after unpack. The default
301 is to check.
302 -D, --no-md5-digest
304 do not use md5sum digest to verify.
305 Do not use md5sum digest to verify the unpacked files. The
307 default is to check.
308 -F, --force-prefix
310 apply the prefix character on every line.
311 Forces the prefix character to be prepended to every line, even
313 if not required. This option may slightly increase the size of
314 the archive, especially if --uuencode or a compression option is
315 used.
316 -d delim, --here-delimiter=delim
318 use delim to delimit the files. The default delim for this
319 option is:
320 SHAR_EOF
321 Use DELIM to delimit the files in the shar instead of SHAR_EOF.
323 This is for those who want to personalize their shar files. The
324 delimiter will always be prefixed and suffixed with underscores.
325 Producing different kinds of shars:
327 -V, --vanilla-operation
328 produce very simple shars.
329 This option produces vanilla shars which rely only upon the
331 existence of echo, test and sed in the unpacking environment.
332 It changes the default behavior from mixed mode (--mixed-uuen‐
334 code) to text mode (--text-files). Warnings are produced if
335 options are specified that will require decompression or decod‐
336 ing in the unpacking environment.
337 -P, --no-piping
339 use temporary files between programs.
340 In the shar file, use a temporary file to hold file contents
342 between unpacking stages instead of using pipes. This option is
343 mandatory when you know the unpacking will happen on systems
344 that do not support pipes.
345 -x, --no-check-existing
347 blindly overwrite existing files.
348 Create the archive so that when processed it will overwrite
350 existing files without checking first. If neither this option
351 nor the --query-user option is specified, the unpack will not
352 overwrite pre-existing files. In all cases, however, if --cut-
353 mark is passed as a parameter to the script when unpacking, then
354 existing files will be overwritten unconditionally.
355 sh shar-archive-file -c
357 -X, --query-user
359 ask user before overwriting files. This option must not appear
360 in combination with any of the following options: vanilla-opera‐
361 tion.
362 When unpacking, interactively ask the user if files should be
364 overwritten. Do not use for shars submitted to the net.
365 Use of this option produces shars which will cause problems with
367 some unshar-style procedures, particularily when used together
368 with vanilla mode (--vanilla-operation). Use this feature
369 mainly for archives to be passed among agreeable parties. Cer‐
370 tainly, -X is not for shell archives which are to be submitted
371 to Usenet or other public networks.
372 The problem is that unshar programs or procedures often feed
374 /bin/sh from its standard input, thus putting /bin/sh and the
375 shell archive script in competition for input lines. As an
376 attempt to alleviate this problem, shar will try to detect if
377 /dev/tty exists at the receiving site and will use it to read
378 user replies. But this does not work in all cases, it may hap‐
379 pen that the receiving user will have to avoid using unshar pro‐
380 grams or procedures, and call /bin/sh directly. In vanilla
381 mode, using /dev/tty is not even attempted.
382 -m, --no-timestamp
384 do not restore modification times.
385 Avoid generating 'touch' commands to restore the file modifica‐
387 tion dates when unpacking files from the archive.
388 When file modification times are not preserved, project build
390 programs like "make" will see built files older than the files
391 they get built from. This is why, when this option is not used,
392 a special effort is made to restore timestamps.
393 -Q, --quiet-unshar
395 avoid verbose messages at unshar time.
396 Verbose OFF. Disables the inclusion of comments to be output
398 when the archive is unpacked.
399 -f, --basename
401 restore in one directory, despite hierarchy.
402 Restore by the base file name only, rather than path. This
404 option causes only file names to be used, which is useful when
405 building a shar from several directories, or another directory.
406 Note that if a directory name is passed to shar, the substruc‐
407 ture of that directory will be restored whether this option is
408 specified or not.
409 Internationalization options:
411 --no-i18n
412 do not internationalize.
413 Do not produce internationalized shell archives, use default
415 English messages. By default, shar produces archives that will
416 try to output messages in the unpackers preferred language (as
417 determined by the LANG/LC_MESSAGES environmental variables) when
418 they are unpacked. If no message file for the unpackers lan‐
419 guage is found at unpack time, messages will be in English.
420 --print-text-domain-dir
422 print directory with shar messages.
423 Prints the directory shar looks in to find messages files for
425 different languages, then immediately exits.
426 user feedback/entertainment
428 -q, --quiet
429 do not output verbose messages.
430 omit progress messages.
432 --silent
434 This is an alias for the --quiet option.
435 -h, --help
437 Display usage information and exit.
438 -!, --more-help
440 Pass the extended usage information through a pager.
441 -R [rcfile], --save-opts[=rcfile]
443 Save the option state to rcfile. The default is the last con‐
444 figuration file listed in the OPTION PRESETS section, below.
445 -r rcfile, --load-opts=rcfile, --no-load-opts
447 Load options from rcfile. The no-load-opts form will disable
448 the loading of earlier RC/INI files. --no-load-opts is handled
449 early, out of order.
450 -v [{v|c|n}], --version[={v|c|n}]
452 Output version of program and exit. The default mode is `v', a
453 simple version. The `c' mode will print copyright information
454 and `n' will print the full copyright notice.
455
457 Any option that is not marked as not presettable may be preset by load‐
458 ing values from configuration ("RC" or ".INI") file(s). The file
459 "$HOME/.sharrc" will be used, if present.
460
462 No attempt is made to restore the protection and modification dates for
463 directories, even if this is done by default for files. Thus, if a
464 directory is given to shar, the protection and modification dates of
465 corresponding unpacked directory may not match those of the original.
466 If a directory is passed to shar, it may be scanned more than once, to
468 conserve memory. Therefore, do not change the directory contents while
469 shar is running.
470 Be careful that the output file(s) are not included in the inputs or
472 shar may loop until the disk fills up. Be particularly careful when a
473 directory is passed to shar that the output files are not in that
474 directory or a subdirectory of it.
475 Use of the compression and encoding options will slow the archive
477 process, perhaps considerably.
478 Use of the --query-user produces shars which will cause problems with
480 many unshar procedures. Use this feature only for archives to be
481 passed among agreeable parties. Certainly, query-user is NOT for shell
482 archives which are to be distributed across the net. The use of com‐
483 pression in net shars will cause you to be flamed off the earth. Not
484 using the --no-timestamp or --force-prefix options may also get you
485 occasional complaints. Put these options into your ~/.sharrc file.
486
488 See OPTION PRESETS for configuration files.
489
491 The first shows how to make a shell archive out of all C program
492 sources. The second produces a shell archive with all .c and .h files,
493 which unpacks silently. The third gives a shell archive of all uuen‐
494 coded .arc files, into numbered files starting from arc.sh.01. The
495 last example gives a shell archive which will use only the file names
496 at unpack time.
497 shar *.c > cprog.shar
499 shar -Q *.[ch] > cprog.shar
500 shar -B -l28 -oarc.sh *.arc
501 shar -f /lcl/src/u*.c > u.sh
502
504 One of the following exit values will be returned:
505 0 (EXIT_SUCCESS)
507 Successful program execution.
508 1 (EXIT_OPTION_ERROR)
510 The command options were misconfigured.
511 2 (EXIT_FILE_NOT_FOUND)
513 a specified input could not be found
514 3 (EXIT_CANNOT_OPENDIR)
516 open/close of specified directory failed
517 4 (EXIT_FAILED)
519 Resource limit/miscelleaneous shar command failure
520 63 (EXIT_BUG)
522 There is a shar command bug. Please report it.
523 66 (EX_NOINPUT)
525 A specified configuration file could not be loaded.
526 70 (EX_SOFTWARE)
528 libopts had an internal operational error. Please report it to
529 autogen-users@lists.sourceforge.net. Thank you.
530
532 unshar(1)
533
535 The shar and unshar programs is the collective work of many authors.
536 Many people contributed by reporting problems, suggesting various
537 improvements or submitting actual code. A list of these people is in
538 the THANKS file in the sharutils distribution.
539
541 Copyright (C) 1994-2013 Free Software Foundation, Inc. all rights
542 reserved. This program is released under the terms of the GNU General
543 Public License, version 3 or later.
544
546 Please put sharutils in the subject line for emailed bug reports. It
547 helps to spot the message.
548 Please send bug reports to: bug-gnu-utils@gnu.org
550
552 This manual page was AutoGen-erated from the shar option definitions.
553GNU sharutils (4.13.3) 06 Jan 2013 shar(1)