Debian Codegraph @

upstream/debian-unstable/man1/unzipsfx.1

raw
1 .\" Copyright (c) 1990-2009 Info-ZIP. All rights reserved.
2 .\"
3 .\" See the accompanying file LICENSE, version 2009-Jan-02 or later
4 .\" (the contents of which are also included in unzip.h) for terms of use.
5 .\" If, for some reason, all these files are missing, the Info-ZIP license
6 .\" also may be found at: ftp://ftp.info-zip.org/pub/infozip/license.html
7 .\"
8 .\" unzipsfx.1 by Greg Roelofs
9 .\"
10 .\" =========================================================================
11 .\" define .EX/.EE (for multiline user-command examples; normal Courier font)
12 .de EX
13 .in +4n
14 .nf
15 .ft CW
16 ..
17 .de EE
18 .ft R
19 .fi
20 .in -4n
21 ..
22 .\" =========================================================================
23 .TH UNZIPSFX 1 "20 April 2009 (v6.0)" "Info-ZIP"
24 .SH NAME
25 unzipsfx \- self-extracting stub for prepending to ZIP archives
26 .PD
27 .SH SYNOPSIS
28 \fB<name of unzipsfx+archive combo>\fP [\fB\-cfptuz\fP[\fBajnoqsCLV$\fP]]
29 [\fIfile(s)\fP\ .\|.\|. [\fB\-x\fP\ \fIxfile(s)\fP\ .\|.\|.]]
30 .PD
31 .\" =========================================================================
32 .SH DESCRIPTION
33 \fIunzipsfx\fP is a modified version of \fIunzip\fP(1) designed to be
34 prepended to existing ZIP archives in order to form self-extracting archives.
35 Instead of taking its first non-flag argument to be the zipfile(s) to be
36 extracted, \fIunzipsfx\fP seeks itself under the name by which it was invoked
37 and tests or extracts the contents of the appended archive. Because the
38 executable stub adds bulk to the archive (the whole purpose of which is to
39 be as small as possible), a number of the less-vital capabilities in regular
40 \fIunzip\fP have been removed. Among these are the usage (or help) screen,
41 the listing and diagnostic functions (\fB\-l\fP and \fB\-v\fP), the ability
42 to decompress older compression formats (the ``reduce,'' ``shrink'' and
43 ``implode'' methods). The ability to extract to a directory other than
44 the current one can be selected as a compile-time option, which is now enabled
45 by default since UnZipSFX version 5.5. Similarly, decryption is supported as
46 a compile-time option but should be avoided unless the attached archive
47 contains encrypted files. Starting with release 5.5, another compile-time
48 option adds a simple ``run command after extraction'' feature. This feature
49 is currently incompatible with the ``extract to different directory''
50 feature and remains disabled by default.
51 .PP
52 \fBNote that
53 self-extracting archives made with\fP \fIunzipsfx\fP \fBare no more (or less)
54 portable across different operating systems than is
55 the\fP \fIunzip\fP \fBexecutable itself.\fP In general a self-extracting
56 archive made on
57 a particular Unix system, for example, will only self-extract under the same
58 flavor of Unix. Regular \fIunzip\fP may still be used to extract the
59 embedded archive as with any normal zipfile, although it will generate
60 a harmless warning about extra bytes at the beginning of the zipfile.
61 \fIDespite this\fP, however, the self-extracting archive is technically
62 \fInot\fP a valid ZIP archive, and PKUNZIP may be unable to test or extract
63 it. This limitation is due to the simplistic manner in which the archive
64 is created; the internal directory structure is not updated to reflect the
65 extra bytes prepended to the original zipfile.
66 .PD
67 .\" =========================================================================
68 .SH ARGUMENTS
69 .IP [\fIfile(s)\fP]
70 An optional list of archive members to be processed.
71 Regular expressions (wildcards) similar to those in Unix \fIegrep\fP(1)
72 may be used to match multiple members. These wildcards may contain:
73 .RS
74 .IP *
75 matches a sequence of 0 or more characters
76 .IP ?
77 matches exactly 1 character
78 .IP [.\|.\|.]
79 matches any single character found inside the brackets; ranges are specified
80 by a beginning character, a hyphen, and an ending character. If an exclamation
81 point or a caret (`!' or `^') follows the left bracket, then the range of
82 characters within the brackets is complemented (that is, anything \fIexcept\fP
83 the characters inside the brackets is considered a match).
84 .RE
85 .IP
86 (Be sure to quote any character that might otherwise be interpreted or
87 modified by the operating system, particularly under Unix and VMS.)
88 .IP [\fB\-x\fP\ \fIxfile(s)\fP]
89 An optional list of archive members to be excluded from processing.
90 Since wildcard characters match directory separators (`/'), this option
91 may be used to exclude any files that are in subdirectories. For
92 example, ``\fCfoosfx *.[ch] -x */*\fR'' would extract all C source files
93 in the main directory, but none in any subdirectories. Without the \fB\-x\fP
94 option, all C source files in all directories within the zipfile would be
95 extracted.
96 .PP
97 If \fIunzipsfx\fP is compiled with SFX_EXDIR defined, the following option
98 is also enabled:
99 .IP [\fB\-d\fP\ \fIexdir\fP]
100 An optional directory to which to extract files. By default, all files
101 and subdirectories are recreated in the current directory; the \fB\-d\fP
102 option allows extraction in an arbitrary directory (always assuming one
103 has permission to write to the directory). The option and directory may
104 be concatenated without any white space between them, but note that this
105 may cause normal shell behavior to be suppressed. In particular,
106 ``\fC\-d\ ~\fR'' (tilde) is expanded by Unix C shells into the name
107 of the user's home directory, but ``\fC\-d~\fR'' is treated as a
108 literal subdirectory ``\fB~\fP'' of the current directory.
109 .PD
110 .\" =========================================================================
111 .SH OPTIONS
112 \fIunzipsfx\fP supports the following \fIunzip\fP(1) options: \fB\-c\fP
113 and \fB\-p\fP (extract to standard output/screen), \fB\-f\fP and \fB\-u\fP
114 (freshen and update existing files upon extraction), \fB\-t\fP (test
115 archive) and \fB\-z\fP (print archive comment). All normal listing options
116 (\fB\-l\fP, \fB\-v\fP and \fB\-Z\fP) have been removed, but the testing
117 option (\fB\-t\fP) may be used as a ``poor man's'' listing. Alternatively,
118 those creating self-extracting archives may wish to include a short listing
119 in the zipfile comment.
120 .PP
121 See \fIunzip\fP(1) for a more complete description of these options.
122 .PD
123 .\" =========================================================================
124 .SH MODIFIERS
125 \fIunzipsfx\fP currently supports all \fIunzip\fP(1) modifiers: \fB\-a\fP
126 (convert text files), \fB\-n\fP (never overwrite), \fB\-o\fP (overwrite
127 without prompting), \fB\-q\fP (operate quietly), \fB\-C\fP (match names
128 case-insensitively), \fB\-L\fP (convert uppercase-OS names to lowercase),
129 \fB\-j\fP (junk paths) and \fB\-V\fP (retain version numbers); plus the
130 following operating-system specific options: \fB\-X\fP (restore VMS
131 owner/protection info), \fB\-s\fP (convert spaces in filenames to underscores
132 [DOS, OS/2, NT]) and \fB\-$\fP (restore volume label [DOS, OS/2, NT, Amiga]).
133 .PP
134 (Support for regular ASCII text-conversion may be removed in future versions,
135 since it is simple enough for the archive's creator to ensure that text
136 files have the appropriate format for the local OS. EBCDIC conversion will
137 of course continue to be supported since the zipfile format implies ASCII
138 storage of text files.)
139 .PP
140 See \fIunzip\fP(1) for a more complete description of these modifiers.
141 .PD
142 .\" =========================================================================
143 .SH "ENVIRONMENT OPTIONS"
144 \fIunzipsfx\fP uses the same environment variables as \fIunzip\fP(1) does,
145 although this is likely to be an issue only for the person creating and
146 testing the self-extracting archive. See \fIunzip\fP(1) for details.
147 .PD
148 .\" =========================================================================
149 .SH DECRYPTION
150 Decryption is supported exactly as in \fIunzip\fP(1); that is, interactively
151 with a non-echoing prompt for the password(s). See \fIunzip\fP(1) for
152 details. Once again, note that if the archive has no encrypted files there
153 is no reason to use a version of \fIunzipsfx\fP with decryption support;
154 that only adds to the size of the archive.
155 .PD
156 .\" =========================================================================
157 .SH AUTORUN COMMAND
158 When \fIunzipsfx\fP was compiled with CHEAP_SFX_AUTORUN defined, a simple
159 ``command autorun'' feature is supported. You may enter a command into the
160 Zip archive comment, using the following format:
161 .PP
162 .EX
163 $AUTORUN$>[command line string]
164 .EE
165 .PP
166 When \fIunzipsfx\fP recognizes the ``$AUTORUN$>'' token at the beginning
167 of the Zip archive comment, the remainder of the first line of the comment
168 (until the first newline character) is passed as a shell command to the
169 operating system using the C rtl ``system'' function. Before executing
170 the command, \fIunzipsfx\fP displays the command on the console and prompts
171 the user for confirmation. When the user has switched off prompting by
172 specifying the \fB-q\fP option, autorun commands are never executed.
173 .PP
174 In case the archive comment contains additional lines of text, the remainder
175 of the archive comment following the first line is displayed normally, unless
176 quiet operation was requested by supplying a \fB-q\fP option.
177 .PD
178 .\" =========================================================================
179 .SH EXAMPLES
180 To create a self-extracting archive \fIletters\fP from a regular zipfile
181 \fIletters.zip\fP and change the new archive's permissions to be
182 world-executable under Unix:
183 .PP
184 .EX
185 cat unzipsfx letters.zip > letters
186 chmod 755 letters
187 zip -A letters
188 .EE
189 .PP
190 To create the same archive under MS-DOS, OS/2 or NT (note the use of the
191 \fB/b\fP [binary] option to the \fIcopy\fP command):
192 .PP
193 .EX
194 copy /b unzipsfx.exe+letters.zip letters.exe
195 zip -A letters.exe
196 .EE
197 .PP
198 Under VMS:
199 .PP
200 .EX
201 copy unzipsfx.exe,letters.zip letters.exe
202 letters == "$currentdisk:[currentdir]letters.exe"
203 zip -A letters.exe
204 .EE
205 .PP
206 (The VMS \fIappend\fP command may also be used. The second command installs
207 the new program as a ``foreign command'' capable of taking arguments. The
208 third line assumes that Zip is already installed as a foreign command.)
209 Under AmigaDOS:
210 .PP
211 .EX
212 MakeSFX letters letters.zip UnZipSFX
213 .EE
214 .PP
215 (MakeSFX is included with the UnZip source distribution and with Amiga
216 binary distributions. ``\fCzip -A\fR'' doesn't work on Amiga self-extracting
217 archives.)
218 To test (or list) the newly created self-extracting archive:
219 .PP
220 .EX
221 letters \-t
222 .EE
223 .PP
224 To test \fIletters\fP quietly, printing only a summary message indicating
225 whether the archive is OK or not:
226 .PP
227 .EX
228 letters \-tqq
229 .EE
230 .PP
231 To extract the complete contents into the current directory, recreating all
232 files and subdirectories as necessary:
233 .PP
234 .EX
235 letters
236 .EE
237 .PP
238 To extract all \fC*.txt\fR files (in Unix quote the `*'):
239 .PP
240 .EX
241 letters *.txt
242 .EE
243 .PP
244 To extract everything \fIexcept\fP the \fC*.txt\fR files:
245 .PP
246 .EX
247 letters -x *.txt
248 .EE
249 .PP
250 To extract only the README file to standard output (the screen):
251 .PP
252 .EX
253 letters -c README
254 .EE
255 .PP
256 To print only the zipfile comment:
257 .PP
258 .EX
259 letters \-z
260 .EE
261 .PD
262 .\" =========================================================================
263 .SH LIMITATIONS
264 The principle and fundamental limitation of \fIunzipsfx\fP is that it is
265 not portable across architectures or operating systems, and therefore
266 neither are the resulting archives. For some architectures there is
267 limited portability, however (e.g., between some flavors of Intel-based Unix).
268 .PP
269 Another problem with the current implementation is that any archive
270 with ``junk'' prepended to the beginning technically is no longer a zipfile
271 (unless \fIzip\fP(1) is used to adjust the zipfile offsets appropriately,
272 as noted above). \fIunzip\fP(1) takes note of the prepended bytes
273 and ignores them since some file-transfer protocols, notably MacBinary, are
274 also known to prepend junk. But PKWARE's archiver suite may not be able to
275 deal with the modified archive unless its offsets have been adjusted.
276 .PP
277 \fIunzipsfx\fP has no knowledge of the user's PATH, so in general an archive
278 must either be in the current directory when it is invoked, or else a full
279 or relative path must be given. If a user attempts to extract the archive
280 from a directory in the PATH other than the current one, \fIunzipsfx\fP will
281 print a warning to the effect, ``can't find myself.'' This is always true
282 under Unix and may be true in some cases under MS-DOS, depending on the
283 compiler used (Microsoft C fully qualifies the program name, but other
284 compilers may not). Under OS/2 and NT there are operating-system calls
285 available that provide the full path name, so the archive may be invoked
286 from anywhere in the user's path. The situation is not known for AmigaDOS,
287 Atari TOS, MacOS, etc.
288 .PP
289 As noted above, a number of the normal \fIunzip\fP(1) functions have
290 been removed in order to make \fIunzipsfx\fP smaller: usage and diagnostic
291 info, listing functions and extraction to other directories. Also, only
292 stored and deflated files are supported. The latter limitation is mainly
293 relevant to those who create SFX archives, however.
294 .PP
295 VMS users must know how to set up self-extracting archives as foreign
296 commands in order to use any of \fIunzipsfx\fP's options. This is not
297 necessary for simple extraction, but the command to do so then becomes,
298 e.g., ``\fCrun letters\fR'' (to continue the examples given above).
299 .PP
300 \fIunzipsfx\fP on the Amiga requires the use of a special program, MakeSFX,
301 in order to create working self-extracting archives; simple concatenation
302 does not work. (For technically oriented users, the attached archive is
303 defined as a ``debug hunk.'') There may be compatibility problems between
304 the ROM levels of older Amigas and newer ones.
305 .PP
306 All current bugs in \fIunzip\fP(1) exist in \fIunzipsfx\fP as well.
307 .PD
308 .\" =========================================================================
309 .SH DIAGNOSTICS
310 \fIunzipsfx\fP's exit status (error level) is identical to that of
311 \fIunzip\fP(1); see the corresponding man page.
312 .PD
313 .\" =========================================================================
314 .SH "SEE ALSO"
315 \fIfunzip\fP(1), \fIunzip\fP(1), \fIzip\fP(1), \fIzipcloak\fP(1),
316 \fIzipgrep\fP(1), \fIzipinfo\fP(1), \fIzipnote\fP(1), \fIzipsplit\fP(1)
317 .PD
318 .PD
319 .\" =========================================================================
320 .SH URL
321 The Info-ZIP home page is currently at
322 .EX
323 \fChttp://www.info-zip.org/pub/infozip/\fR
324 .EE
325 or
326 .EX
327 \fCftp://ftp.info-zip.org/pub/infozip/\fR .
328 .EE
329 .PD
330 .\" =========================================================================
331 .SH AUTHORS
332 Greg Roelofs was responsible for the basic modifications to UnZip necessary
333 to create UnZipSFX. See \fIunzip\fP(1) for the current list of Zip-Bugs
334 authors, or the file CONTRIBS in the UnZip source distribution for the
335 full list of Info-ZIP contributors.
336 .PD