Copyright (C) 1994 Free Software Foundation, Inc.
Permission is granted to make and distribute verbatim copies of this manual provided the copyright notice and this permission notice are preserved on all copies.
Permission is granted to copy and distribute modified versions of this manual under the conditions for verbatim copying, provided that the entire resulting derived work is distributed under the terms of a permission notice identical to this one.
Permission is granted to copy and distribute translations of this manual into another language, under the above conditions for modified versions, except that this permission notice may be stated in a translation approved by the Foundation.
shar makes so-called shell archives out of many files,
preparing them for transmission by electronic mail services.
A shell archive is a collection of files that can be unpacked by
/bin/sh. A wide range of features provide extensive flexibility
in manufacturing shars and in specifying shar smartness. For
shar may compress files, uuencode binary files, split
long files and construct multi-part mailings, ensure correct unsharing
order, and provide simplistic checksums. See section Invoking the
unshar scans a set of mail messages looking for the start
of shell archives. It will automatically strip off the mail headers
and other introductory text. The archive bodies are then unpacked by
a copy of the shell.
unshar may also process files containing
concatenated shell archives. See section Invoking the
shar has a long history. All along this long road, numerous
users contributed various improvements. The file `THANKS', from
shar distribution, contain all names still having
valid email addresses, as far as we know.
Please help me getting the history straight, for the following
information is approximative. James Gosling wrote the public domain
shar 1.x. William Davidsen rewrote it as
Warren Tucker brought modifications and called it
Richard Gumpertz maintained it until 1990. Pinard,
from the public domain
shar 3.49, made
GNU shar 4.x,
in 1994. Some modules and other code sections were freely borrowed
from other GNU distributions, bringing this
shar under the
terms of the GNU General Public License.
Your feedback helps us to make a better and more portable product. Mail suggestions and bug reports (including documentation errors) for these programs to `email@example.com'.
The format of the
shar command is one of:
shar [ option ] ... file ... shar -S [ option ] ...
In the first form, the file list is given as command arguments. In the
second form, the file list is read from standard input. The resulting
archive is sent to standard output unless the
-o option is given.
Options can be given in any order. Some options depend on each other:
-o option is required if the
is used. The
-n option is required if the
is used. Also see
Some options are special purpose:
shartime. Messages are usually issued on standard error to let the user follow the progress, while making the archives. This option inhibits these messages.
-Zmay be embedded, and files to the right of the option will be processed in the specified mode. Without the
-poption, embedded options would be interpreted as file names. See section Selecting how files are stocked for more information on these options.
find . -type f -print | shar -S -o /tmp/big.sharIf
-pis specified on the command line, then the options
-Zmay be included in the standard input (on a line separate from file names). The maximum number of lines of standard input, file names and options, may not exceed 1024.
-Lswitches are used. When prefix contains any `%' character, prefix is then interpreted as a
sprintfformat, which should be able to display a single decimal number. When prefix does not contain such a `%' character, the string `.%02d' is internally appended.
unshar, used with option
-e, to unpack them all at once. See section Invoking the
unsharprogram. For people used to saving all the shell archives into a single mail folder, care must be taken to save them in the appropriate order. For those having the appropriate tools (like Masanobu Umeda's
rmailsortpackage for GNU Emacs), shell archives can be saved in any order, then sorted by increasing date (or send time) before massive unpacking.
-aswitch further down.
-soption allows for overriding the email address for the submitter, for when the default is not appropriate. The automatically determined address looks like `username@hostname'.
Submitted-by: address Archive-name: name/partnnThe name must be given with the
-nswitch. If name includes a `/', then `/part' isn't used. Thus `-n xyzzy' produces:
xyzzy/part01 xyzzy/part02while `-n xyzzy/patch' produces:
xyzzy/patch01 xyzzy/patch02and `-n xyzzy/patch01.' produces:
uuencodeprior to packing. This increases the size of the archive. The recipient must have
uudecodein order to unpack.
uuencodeis not appreciated by many on the net, because people like to readily see, by mere inspection of a shell archive, what it is about.
uuencodeon all files prior to packing. The recipient must have
-d) in order to unpack. Usage of
-zin net shars will cause you to be flamed off the earth.
-levelas a parameter to
-goption turns on the
-zoption by default. The default value is 9, that is, maximum compression.
uuencodeon all files prior to packing. The recipient must have
-d) in order to unpack. Option
-Cis a synonymous for
-Z, but is deprecated. Usage of
-Zin net shars will cause you to be flamed off the earth.
-bxas a parameter to
-Boption turns on the
-Zoption by default. The default value is 12, foreseeing the memory limitations of some
compressprograms on smallish systems, at
Transmission of shell archives is not always free of errors. So one
should make consistency checks on the receiving site. A very simple
(and unreliable) method is running the UNIX
wc tool on the output
file. This can report the number of characters in the file.
As one can guess this does not catch all errors. Especially changing of
a character value does not change the computed check sum. To achieve
this goal better method were invented and standardized. One very strong
is MD5 (MD = message digests). This is standardized in RFC 1321. The
produced shell scripts do not force the
md5sum program to be
installed on the system. This is necessary because it is not yet part
of every UNIX. The program is however not necessary for producing the
-Zis used. Normally, the prefix character is `X'. If the parameter to the
-doption starts with `X', then the prefix character becomes `Y'.
sedin the unpacking environment. The
-Vdisables options offensive to the network cop (or brown shirt). It also changes the default from mixed mode
-Mto text mode
-T. Warnings are produced if option
-Mis specified (any of which does or might require
compressin the unpacking environment).
uudecode, instead of using pipes. This option is mandatory when you know the unpacking
uudecodeis unwilling to merely read its standard input. Richard Marks wrote what is certainly the most (in)famous of these, for MSDOS :-). (Here is a side note from the maintainer. Why isnt't this option the default? In the past history of
shar, it was decided that piping was better, surely because it is less demanding on disk space, and people seem to be happy with this. Besides, I think that the
uudecodefrom Richard Marks, on MSDOS, is wrong in refusing to handle
stdin. So far that I remember, he has the strong opinion that a program without any parameters should give its
--helpoutput. Besides that, should I say, his
uudecodeprograms are full-featured, one of the most complete set I ever saw. But Richard will not release his sources, he wants to stay in control.)
-Xis specified, when unpacking itself, the shell archive will check for and not overwrite existing files (unless
-cis passed as a parameter to the script when unpacking).
-Xproduces shars which will cause problems with some
unshar-style procedures, particularily when used together with vanilla mode (
-V). Use this feature mainly for archives to be passed among agreeable parties. Certainly,
-Xis not for shell archives which are to be submitted to Usenet or other public networks. The problem is that
unsharprograms or procedures often feed `/bin/sh' from its standard input, thus putting `/bin/sh' and the shell archive script in competition for input lines. As an attempt to alleviate this problem,
sharwill try to detect if `/dev/tty' exists at the receiving site and will use it to read user replies. But this does not work in all cases, it may happen that the receiving user will have to avoid using
unsharprograms or procedures, and call
/bin/shdirectly. In vanilla mode, using `/dev/tty' is not even attempted.
touchcommands to restore the file modification dates when unpacking files from the archive. When the timestamp relationship is not preserved, some files like `configure' or `*.info' may be uselessly remade after unpacking. This is why, when this option is not used, a special effort is made to restore timestamps,
unshartime. Disables the inclusion of comments to be output when the archive is unpacked.
shar, the substructure of that directory will be restored whether
-fis specified or not.
The format of the
unshar command is:
unshar [ option ] ... [ file ... ]
Each file is processed in turn, as a shell archive or a collection of shell archives. If no files are given, then standard input is processed instead.
shar3.40 and newer) accepts a
-cargument to indicate that existing files should be overwritten. The option
-fis provided for a more unique interface. Many programs (such as
mv) use this option to trigger the very same action.
unsharisolates each different shell archive from the others which have been put in the same file, unpacking each in turn, from the beginning of the file towards its end. Its proper operation relies on the fact that many shar files are terminated by a `exit 0' at the beginning of a line. Option
-eis internally equivalent to
-E "exit 0".
-e, but it allows you to specify the string that separates archives if `exit 0' isn't appropriate. For example, noticing that most `.signatures' have a `--' on a line right before them, one can sometimes use `--split-at=--' for splitting shell archives which lack the `exit 0' line at end. The signature will then be skipped altogether with the headers of the following message.
Here is a place-holder for many considerations which do not fit elsewhere, while not worth a section for themselves.
Be careful that the output file(s) are not included in the inputs
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).
When a directory is passed to
shar, it may be scanned more
than once, to conserve memory. Therefore, one should be careful to
not change the directory contents while
shar is running.
No attempt is made to restore the protection and modification dates
for directories, even if this is done by default for files. Thus, if
a directory is given to
shar, the protection and modification
dates of corresponding unpacked directory may not match those of
Use of the
-B options will slow down the archive
process. Use of the
-Z options may slow the
archive process considerably.
Let us conclude by a showing a few examples of
shar *.c > cprog.shar shar -Q *.[ch] > cprog.shar shar -B -l28 -oarc.sh. *.arc shar -f /lcl/src/u*.c > u.sh
The first shows how to make a shell archive out of all C program sources. The second produces a shell archive with all `.c' and `.h' files, which unpacks silently. The third gives a shell archive of all uuencoded `.arc' files, into files `arc.sh.01' through to `arc.sh.nnn'. The last example gives a shell archive which will use only the file names at unpack time.
This document was generated on 7 November 1998 using the texi2html translator version 1.52.