1SHAR(1) General Commands Manual SHAR(1)
2
6 shar - create shell archives
7
9 shar [ options ] file ...
10 shar -S [ options ]
11
13 Shar creates "shell archives" (or shar files) which are in text format
14 and can be mailed. These files may be unpacked later by executing them
15 with /bin/sh. The resulting archive is sent to standard out unless the
16 -o option is given. A wide range of features provide extensive flexi‐
17 bility in manufacturing shars and in specifying shar "smartness". Ar‐
18 chives may be "vanilla" or comprehensive.
19
21 Options have a one letter version starting with - or a long version
22 starting with --. The exception is --help, --version, --no-i18n and
23 --print-text-domain-dir which does not have short versions. Mandatory
24 arguments to long options are mandatory for short options too. Options
25 can be given in any order. Some options depend on each other:
26 The -o option is required if the -l or -L option is used.
27 The -n option is required if the -a option is used.
28 See -V below.
29 Giving feedback:
31 --help Print a help summary on standard output, then immediately exits.
32 --version
34 Print the version number of the program on standard output, then
35 immediately exits.
36 -q --quiet --silent
38 Do not output verbose messages locally when producing the ar‐
39 chive.
40 Selecting files:
42 -p --intermix-type
43 Allow positional parameter options. The options -B, -T, -z and
44 -Z may be embedded, and files to the right of the option will be
45 processed in the specified mode.
46 -S --stdin-file-list
48 Read list of files to be packed from the standard input rather
49 than from the command line. Input must be in a form similar to
50 that generated by the find command, one filename per line. This
51 switch is especially useful when the command line will not hold
52 the list of files to be packed. For example:
53 find . -type f -print | \
55 sort | \
56 shar -S -Z -L50 -o /somewhere/big
57 If -p is specified on the command line, then the options -B, -T,
59 -z and -Z may be included in the standard input (on a line sepa‐
60 rate from filenames). The maximum number of lines of standard
61 input, file names and options, may not exceed 1024.
62 Splitting output:
64 -o XXX --output-prefix=XXX
65 Save the archive to files XXX.01 thru XXX.nn instead of sending
66 it to standard out. Must be used when the -l or the -L switches
67 are used.
68 -l XX --whole-size-limit=XX
70 Limit the output file size to XXk bytes but don't split input
71 files.
72 -L XX --split-size-limit=XX
74 Limit output file size to XXk bytes and split files if neces‐
75 sary. The archive parts created with this option must be
76 unpacked in correct order.
77 Controlling the shar headers:
79 -n name --archive-name=name
80 Name of archive to be included in the header of the shar files.
81 See the -a switch.
82 -s who@where --submitter=who@where
84 Override automatically determined submitter name.
85 -a --net-headers
87 Allows automatic generation of headers:
88 Submitted-by: who@where
89 Archive-name: <name>/part##
90 The <name> must be given with the -n switch. If name includes a
91 '/' "/part" isn't used. Thus:
92 -n xyzzy produces:
93 xyzzy/part01
94 xyzzy/part02
95 -n xyzzy/patch produces:
97 xyzzy/patch01
98 xyzzy/patch02
99 -n xyzzy/patch01. produces:
101 xyzzy/patch01.01
102 xyzzy/patch01.02
103 The who@where can be explicitly stated with the -s switch if the
105 default isn't appropriate. Who@where is essentially built as
106 `whoami`@`uname`.
107 -c --cut-mark
109 Start the shar with a cut line. A line saying 'Cut here' is
110 placed at the start of each output file.
111 -t --translate
113 Translate messages in the script. If you have set the LANG
114 environment variable, messages printed by shar will be in the
115 specified language. The produced script will still be emitted
116 using messages in the lingua franca of the computer world: Eng‐
117 lish. This option will cause the script messages to appear in
118 the languages specified by the LANG environment variable set
119 when the script is produced.
120 Selecting how files are stocked:
122 -M --mixed-uuencode
123 Mixed mode. Determine if the files are text or binary and ar‐
124 chive correctly (default). Files found to be binary are uude‐
125 coded prior to packing (USE OF UUENCODE IS NOT APPRECIATED BY
126 MANY ON THE NET).
127 -T --text-files
129 Treat all files as text.
130 -B --uuencode
132 Treat all files as binary, use uuencode prior to packing. This
133 increases the size of the archive. The recipient must have
134 uudecode in order to unpack. (USE OF UUENCODE IS NOT APPRECI‐
135 ATED BY MANY ON THE NET).
136 -z --gzip
138 Gzip and uuencode all files prior to packing. The recipient
139 must have uudecode and gzip in order to unpack (USE OF UUENCODE
140 AND GZIP IS NOT APPRECIATED BY MANY ON THE NET).
141 -g LEVEL --level-for-gzip=LEVEL
143 When doing compression, use '-LEVEL' as a parameter to gzip.
144 Default is 9. The -g option turns on the -z option by default.
145 -Z --compress
147 Compress and uuencode all files prior to packing. The recipient
148 must have uudecode and compress in order to unpack (USE OF UUEN‐
149 CODE AND COMPRESS IS NOT APPRECIATED BY MANY ON THE NET).
150 Option -C is synonymous to -Z, but is being deprecated.
151 -b BITS --bits-per-code=BITS
153 When doing compression, use '-bBITS' as a parameter to compress.
154 The -B option turns on the -Z option by default. Default value
155 is 12.
156 Protecting against transmission errors:
158 -w --no-character-count
159 Do NOT check each file with 'wc -c' after unpack. The default
160 is to check.
161 -D --no-md5-digest
163 Do NOT use 'md5sum' digest to verify the unpacked files. The
164 default is to check.
165 -F --force-prefix
167 Forces the prefix character (normally 'X' unless the parameter
168 to the -d option starts with 'X') to be prepended to every line
169 even if not required. This option may slightly increase the
170 size of the archive, especially if -B or -Z is used.
171 -d XXX --here-delimiter=XXX
173 Use XXX to delimit the files in the shar instead of SHAR_EOF.
174 This is for those who want to personalize their shar files.
175 Producing different kinds of shars:
177 -V --vanilla-operation
178 Produce "vanilla" shars which rely only upon the existence of
179 sed and echo in the unsharing environment. In addition, "if
180 test" must also be supported unless the -x option is used. The
181 -V silently disables options offensive to the "network cop" (or
182 "brown shirt"), but does warn you if it is specified with -B,
183 -z, -Z, -p or -M (any of which does or might require uudecode,
184 gzip or compress in the unsharing environment).
185 -P --no-piping
187 Use temporary files instead of pipes in the shar file.
188 -x --no-check-existing
190 Overwrite existing files without checking. If neither -x nor -X
191 is specified, the unpack will check for and not overwrite exist‐
192 ing files when unpacking the archive. If -c is passed as a
193 parameter to the script when unpacking:
194 sh archive -c
196 then existing files will be overwritten unconditionally.
198 -X --query-user
200 When unpacking, interactively ask the user if files should be
201 overwritten. (DO NOT USE FOR SHARS SUBMITTED TO THE NET).
202 -m --no-timestamp
204 Avoid generating 'touch' commands to restore the file modifica‐
205 tion dates when unpacking files from the archive.
206 -Q --quiet-unshar
208 Verbose OFF. Disables the inclusion of comments to be output
209 when the archive is unpacked.
210 -f --basename
212 Restore by filename only, rather than path. This option causes
213 only file names to be used, which is useful when building a shar
214 from several directories, or another directory. Note that if a
215 directory name is passed to shar, the substructure of that
216 directory will be restored whether -f is specified or not.
217 Internationalization:
219 --no-i18n
220 Do not produce internationalized shell archives, use default
221 English messages. By default, shar produces archives that will
222 try to output messages in the unpackers preferred language (as
223 determined by the LANG/LC_MESSAGES environmental variables) when
224 they are unpacked. If no message file for the unpackers lan‐
225 guage is found at unpack time, messages will be in English.
226 --print-text-domain-dir
228 Prints the directory shar looks in to find messages files for
229 different languages, then immediately exits.
230
232 shar *.c > cprog.shar # all C prog sources
233 shar -Q *.[ch] > cprog.shar # non-verbose, .c and .h files
234 shar -B -l28 -oarc.sh *.arc # all binary .arc files, into
235 # files arc.sh.01 thru arc.sh.NN
236 shar -f /lcl/src/u*.c > u.sh # use only the filenames
237
239 No chmod or touch is ever generated for directories created when
240 unpacking. Thus, if a directory is given to shar, the protection and
241 modification dates of corresponding unpacked directory may not match
242 those of the original.
243 If a directory is passed to shar, it may be scanned more than once.
245 Therefore, one should be careful not change the directory while shar is
246 running.
247 Be careful that the output file(s) are not included in the inputs or
249 shar may loop until the disk fills up. Be particularly careful when a
250 directory is passed to shar that the output files are not in that
251 directory (or a subdirectory of that directory).
252 Use of the -B, -z or -Z, and especially -M, may slow the archive
254 process considerably, depending on the number of files.
255 Use of -X produces shars which WILL cause problems with many unshar
257 procedures. Use this feature only for archives to be passed among
258 agreeable parties. Certainly, -X is NOT for shell archives which are
259 to be submitted to Usenet. Usage of -B, -z or -Z in net shars will
260 cause you to be flamed off the earth. Not using -m or not using -F may
261 also get you occasional complaints.
262
264 unshar(1)
265
267 Error messages for illegal or incompatible options, for non-regular,
268 missing or inaccessible files or for (unlikely) memory allocation fail‐
269 ure.
270
272 The shar and unshar programs is the collective work of many authors.
273 Many people contributed by reporting problems, suggesting various
274 improvements or submitting actual code. A list of these people is in
275 the THANKS file in the sharutils distribution.
276
278 Report bugs to <bug-gnu-utils@gnu.org>. Please put sharutils or uuen‐
279 code in the subject line. It helps to spot the message.
280 July 1, 2005 SHAR(1)