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.
- -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.