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 extensive
flexibility in manufacturing shars and in specifying shar "smartness".
Archives may be "vanilla" or comprehensive.
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 immediately 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 producing 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 specified 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 /somewhere/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.
-t --translate
Translate messages in the script. If you have set the LANG
environment variable, messages printed by shar will be in the
specified language. The produced script will still be emitted
using messages in the lingua franca of the computer world:
English. This option will cause the script messages to appear
in the languages specified by the LANG environment variable set
when the script is produced.
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 personalize 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 environment. In addition, "if
test" must also be supported 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 neither -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 unconditionally.
-X --query-user
When unpacking, interactively ask the user if files should be
overwritten. (DO NOT USE FOR SHARS SUBMITTED 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 directories, or another directory. Note that if a
directory name is passed to shar, the substructure of that
directory will be restored whether -f is specified 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, messages 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 created when
unpacking. Thus, if a directory is given to shar, the protection and
modification dates of corresponding unpacked directory may not match
those of the original.
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 particularly careful when a
directory is passed to shar that the output files are not in that
directory (or a subdirectory 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 problems, suggesting various
improvements or submitting actual code. A list of these people is in
the THANKS file in the sharutils distribution.
REPORTING BUGS
Report bugs to <bug-gnu-utils@gnu.org>. Please put sharutils or
uuencode in the subject line. It helps to spot the message.
July 1, 2005