SHAR(1)
NAME
shar - create shell archives
SYNOPSIS
shar [ options ] file ...
shar -S [ options ]
DESCRIPTION
Shar creates "shell archives" (or shar files) which are in
text format and can be mailed. These files may be
unpacked later by executing them with /bin/sh. The
resulting archive is sent to standard out unless the -o
option is given. A wide range of features provide exten-
sive flexibility in manufacturing shars and in specifying
shar "smartness". Archives may be "vanilla" or comprehen-
sive.
OPTIONS
Options have a one letter version starting with - or a
long version starting with --. The exception is --help,
--version, --no-i18n and --print-text-domain-dir which
does not have short versions. Mandatory arguments to long
options are mandatory for short options too. Options can
be given in any order. Some options depend on each other:
The -o option is required if the -l or -L option is used.
The -n option is required if the -a option is used.
See -V below.
Giving feedback:
--help Print a help summary on standard output, then imme-
diately exits.
--version
Print the version number of the program on standard
output, then immediately exits.
-q --quiet --silent
Do not output verbose messages locally when produc-
ing the archive.
Selecting files:
-p --intermix-type
Allow positional parameter options. The options
-B, -T, -z and -Z may be embedded, and files to the
right of the option will be processed in the speci-
fied mode.
-S --stdin-file-list
Read list of files to be packed from the standard
input rather than from the command line. Input
must be in a form similar to that generated by the
find command, one filename per line. This switch
is especially useful when the command line will not
hold the list of files to be packed. For example:
find . -type f -print | sort | shar -S -Z -L50 -o /tmp/big
If -p is specified on the command line, then the
options -B, -T, -z and -Z may be included in the
standard input (on a line separate from filenames).
The maximum number of lines of standard input, file
names and options, may not exceed 1024.
Splitting output:
-o XXX --output-prefix=XXX
Save the archive to files XXX.01 thru XXX.nn
instead of sending it to standard out. Must be
used when the -l or the -L switches are used.
-l XX --whole-size-limit=XX
Limit the output file size to XXk bytes but don't
split input files.
-L XX --split-size-limit=XX
Limit output file size to XXk bytes and split files
if necessary. The archive parts created with this
option must be unpacked in correct order.
Controlling the shar headers:
-n name --archive-name=name
Name of archive to be included in the header of the
shar files. See the -a switch.
-s who@where --submitter=who@where
Override automatically determined submitter name.
-a --net-headers
Allows automatic generation of headers:
Submitted-by: who@where
Archive-name: <name>/part##
The <name> must be given with the -n switch. If
name includes a '/' "/part" isn't used. Thus:
-n xyzzy produces:
xyzzy/part01
xyzzy/part02
-n xyzzy/patch produces:
xyzzy/patch01
xyzzy/patch02
-n xyzzy/patch01. produces:
xyzzy/patch01.01
xyzzy/patch01.02
The who@where can be explicitly stated with the -s
switch if the default isn't appropriate. Who@where
is essentially built as `whoami`@`uname`.
-c --cut-mark
Start the shar with a cut line. A line saying 'Cut
here' is placed at the start of each output file.
Selecting how files are stocked:
-M --mixed-uuencode
Mixed mode. Determine if the files are text or
binary and archive correctly (default). Files
found to be binary are uudecoded prior to packing
(USE OF UUENCODE IS NOT APPRECIATED BY MANY ON THE
NET).
-T --text-files
Treat all files as text.
-B --uuencode
Treat all files as binary, use uuencode prior to
packing. This increases the size of the archive.
The recipient must have uudecode in order to
unpack. (USE OF UUENCODE IS NOT APPRECIATED BY
MANY ON THE NET).
-z --gzip
Gzip and uuencode all files prior to packing. The
recipient must have uudecode and gzip in order to
unpack (USE OF UUENCODE AND GZIP IS NOT APPRECIATED
BY MANY ON THE NET).
-g LEVEL --level-for-gzip=LEVEL
When doing compression, use '-LEVEL' as a parameter
to gzip. Default is 9. The -g option turns on the
-z option by default.
-Z --compress
Compress and uuencode all files prior to packing.
The recipient must have uudecode and compress in
order to unpack (USE OF UUENCODE AND COMPRESS IS
NOT APPRECIATED BY MANY ON THE NET). Option -C is
synonymous to -Z, but is being deprecated.
-b BITS --bits-per-code=BITS
When doing compression, use '-bBITS' as a parameter
to compress. The -B option turns on the -Z option
by default. Default value is 12.
Protecting against transmission errors:
-w --no-character-count
Do NOT check each file with 'wc -c' after unpack.
The default is to check.
-D --no-md5-digest
Do NOT use 'md5sum' digest to verify the unpacked
files. The default is to check.
-F --force-prefix
Forces the prefix character (normally 'X' unless
the parameter to the -d option starts with 'X') to
be prepended to every line even if not required.
This option may slightly increase the size of the
archive, especially if -B or -Z is used.
-d XXX --here-delimiter=XXX
Use XXX to delimit the files in the shar instead of
SHAR_EOF. This is for those who want to personal-
ize their shar files.
Producing different kinds of shars:
-V --vanilla-operation
Produce "vanilla" shars which rely only upon the
existence of sed and echo in the unsharing environ-
ment. In addition, "if test" must also be sup-
ported unless the -x option is used. The -V
silently disables options offensive to the "network
cop" (or "brown shirt"), but does warn you if it is
specified with -B, -z, -Z, -p or -M (any of which
does or might require uudecode, gzip or compress in
the unsharing environment).
-P --no-piping
Use temporary files instead of pipes in the shar
file.
-x --no-check-existing
Overwrite existing files without checking. If nei-
ther -x nor -X is specified, the unpack will check
for and not overwrite existing files when unpacking
the archive. If -c is passed as a parameter to the
script when unpacking:
sh archive -c
then existing files will be overwritten uncondi-
tionally.
-X --query-user
When unpacking, interactively ask the user if files
should be overwritten. (DO NOT USE FOR SHARS SUB-
MITTED TO THE NET).
-m --no-timestamp
Avoid generating 'touch' commands to restore the
file modification dates when unpacking files from
the archive.
-Q --quiet-unshar
Verbose OFF. Disables the inclusion of comments to
be output when the archive is unpacked.
-f --basename
Restore by filename only, rather than path. This
option causes only file names to be used, which is
useful when building a shar from several directo-
ries, or another directory. Note that if a direc-
tory name is passed to shar, the substructure of
that directory will be restored whether -f is spec-
ified or not.
Internationalization:
--no-i18n
Do not produce internationalized shell archives,
use default english messages. By default, shar
produces archives that will try to output messages
in the unpackers preferred language (as determined
by the LANG/LC_MESSAGES environmental variables)
when they are unpacked. If no message file for the
unpackers language is found at unpack time, mes-
sages will be in english.
--print-text-domain-dir
Prints the directory shar looks in to find messages
files for different languages, then immediately
exits.
EXAMPLES
shar *.c > cprog.shar # all C prog sources
shar -Q *.[ch] > cprog.shar # non-verbose, .c and .h files
shar -B -l28 -oarc.sh *.arc # all binary .arc files, into
# files arc.sh.01 thru arc.sh.NN
shar -f /lcl/src/u*.c > u.sh # use only the filenames
WARNINGS
No chmod or touch is ever generated for directories cre-
ated when unpacking. Thus, if a directory is given to
shar, the protection and modification dates of correspond-
ing unpacked directory may not match those of the origi-
nal.
If a directory is passed to shar, it may be scanned more
than once. Therefore, one should be careful not change
the directory while shar is running.
Be careful that the output file(s) are not included in the
inputs or shar may loop until the disk fills up. Be par-
ticularly careful when a directory is passed to shar that
the output files are not in that directory (or a subdirec-
tory of that directory).
Use of the -B, -z or -Z, and especially -M, may slow the
archive process considerably, depending on the number of
files.
Use of -X produces shars which WILL cause problems with
many unshar procedures. Use this feature only for
archives to be passed among agreeable parties. Certainly,
-X is NOT for shell archives which are to be submitted to
Usenet. Usage of -B, -z or -Z in net shars will cause you
to be flamed off the earth. Not using -m or not using -F
may also get you occasional complaints.
SEE ALSO
unshar(1)
DIAGNOSTICS
Error messages for illegal or incompatible options, for
non-regular, missing or inaccessible files or for
(unlikely) memory allocation failure.
AUTHORS
The shar and unshar programs is the collective work of
many authors. Many people contributed by reporting prob-
lems, suggesting various improvements or submitting actual
code. A list of these people is in the THANKS file in the
sharutils distribution.