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