Debian Codegraph @

vms/VMS_ZIP.RNH

raw
1 .!
2 .! File: ZIP.RNH
3 .!
4 .! Author: Hunter Goatley
5 .!
6 .! Date: October 22, 1991
7 .!
8 .! Description:
9 .!
10 .! RUNOFF source file for portable ZIP on-line help for VMS.
11 .! Adapted from MANUAL, distributed with ZIP.
12 .!
13 .! To build: $ RUNOFF ZIP.RNH
14 .! $ LIBR/HELP/INSERT libr ZIP
15 .!
16 .! Modification history:
17 .!
18 .! Hunter Goatley 22-OCT-1991 20:45
19 .! Genesis.
20 .! Jean-loup Gailly 25 March 92
21 .! Adaptation to zip 1.6.
22 .! Igor Mandrichenko 9-JUN-1992
23 .! Added explanation of -V option.
24 .! Jean-loup Gailly 14 June 92
25 .! Adaptation to zip 1.8.
26 .! Jean-loup Gailly 20 Aug 92
27 .! Adaptation to zip 1.9.
28 .! Jean-loup Gailly 31 Aug 93
29 .! Adaptation to zip 2.0.
30 .! Christian Spieler 20 Sep 93
31 .! Adaptation to zip 2.0 and OpenVMS completed.
32 .! Christian Spieler 05 Dec 95
33 .! Adaptation to zip 2.1, new options.
34 .! Christian Spieler 20 Jan 96
35 .! Changed -L and -v descriptions.
36 .! Christian Spieler 11 Feb 96
37 .! Added -X option.
38 .! Onno van der Linden,
39 .! Christian Spieler 13 Mar 96
40 .! Removed -ee option.
41 .! Christian Spieler 09 Feb 96
42 .! Updated copyright notice, Zip version.
43 .! Christian Spieler 21 Jul 97
44 .! Added -P, -R, -i@, -x@ and -tt options, modified for Zip 2.2.
45 .! Christian Spieler 14 Oct 97
46 .! unified spelling of "Info-ZIP", final cleanups for 2.2.
47 .! Steven Schweda 10 May 2007
48 .! General update for version 3.0.
49 .! Ed Gordon 12 May 2007
50 .! Minor updates for version 3.0.
51 .!
52 .noflags
53 .lm4 .rm72
54 .indent -4
55 1 ZIP
56 .br
57 Zip is a compression and file packaging utility for several operating
58 systems, including UNIX, VMS, MSDOS, OS/2, Windows 9x/NT/XP, Minix, Atari,
59 Macintosh, Amiga, and Acorn RISC OS. It is analogous to a combination of
60 tar and compress and is compatible with PKZIP (Phil Katz's ZIP) for
61 MSDOS systems.
62 .sk
63 Zip is useful for packaging a set of files for distribution, for
64 archiving files, and for saving disk space by temporarily compressing
65 unused files or directories. A companion program, UnZip, unpacks Zip
66 archives.
67 .sk
68 For brief help on Zip or UnZip, run the program without specifying any
69 parameters on the command line.
70 .sk
71 This description covers the Zip program which uses a UNIX-style command
72 line. A separate program is available which provides a VMS-style CLI
73 command line, and it has its own documentation. Refer to the Zip
74 installation instructions for details.
75 .sk
76 Format
77 .sk;.lm+2;.literal
78 ZIP [-options] archive inpath inpath ...
79 .end literal;.lm-2
80 .!------------------------------------------------------------------------------
81 .indent -4
82 2 Basic_Usage
83 .br
84 Format
85 .sk;.lm+2;.literal
86 ZIP [-options] archive inpath inpath ...
87 .end literal;.lm-2
88 .sk
89 The default action of Zip is to add or replace entries in "archive" from
90 the list of "inpath" file specifications, which can include directories
91 and file names with VMS-style wildcards, or the special name -@ to read
92 file specifications from SYS$INPUT (stdin).
93 .sk
94 With SET PROCESS /PARSE_STYLE = EXTENDED (available on recent non-VAX
95 systems), Zip preserves the case of the command line. Otherwise, mixed-
96 or upper-case options and arguments must be quoted. For example,
97 "-V". Examples in this document generally do not show this quotation,
98 so VAX and /PARSE_STYLE = TRADITIONAL users (that is, troglodytes) will
99 need to add quotation where needed when working with these examples.
100 .sk
101 General
102 .sk
103 Zip reads one or more files, compresses the data (normally), and stores
104 the compressed information into a single Zip archive file, along with
105 information about each file (name, path, date and time of last
106 modification, protection, and check information to verify file
107 integrity). On a VMS system, Zip can also save VMS/RMS file attributes,
108 allowing UnZip to restore the files without loss of important file
109 attributes. Zip can pack an entire directory structure into a Zip
110 archive with a single command.
111 .sk
112 Compression
113 .sk
114 Compression ratios of 2:1 to 3:1 are common for text files. Zip has one
115 standard compression method ("deflate") and can also store files without
116 compression. Zip (and UnZip) may be built with optional support for the
117 bzip2 compression method. Then, the user may select bzip2 compression
118 instead of the default "deflate" method. Zip automatically chooses
119 simple storage over compression for a file, if the specified compression
120 method does not actually compress the data in that file.
121 .sk
122 Compatibility
123 .sk
124 Zip and UnZip can work with archives produced by PKZIP (supporting most
125 PKZIP features up to PKZIP version 4.6), and PKZIP and PKUNZIP can work
126 with archives produced by Zip (with some exceptions, notably streamed
127 archives, but recent changes in the .ZIP file standard may facilitate
128 better compatibility). Zip version 3.0 is compatible with PKZIP 2.04
129 and also supports the Zip64 extensions of PKZIP 4.5 which allows
130 archives as well as files to exceed the previous 2 GB limit (4 GB in
131 some cases). Zip also supports bzip2 compression if the bzip2 library
132 is included when Zip is built. Note that PKUNZIP 1.10 cannot extract
133 files produced by PKZIP 2.04 or Zip 3.0. You must use PKUNZIP 2.04g or
134 UnZip 5.0p1 (or later versions) to extract them.
135 .sk
136 Large Archives and Zip64
137 .sk
138 Where the operating system and C run-time support allow, Zip 3.0 and
139 UnZip 6.0 (and later versions) support large files (input and archive),
140 using the Zip64 extensions to the original .ZIP file format. On VMS,
141 this genarally means non-VAX systems with VMS V7.2 or later (perhaps
142 requiring a C RTL ECO before VMS V7.3-2).
143 .sk
144 Zip automatically uses the Zip64 extensions when a file larger than 2 GB
145 is added to an archive, an archive containing a Zip64 entry is updated
146 (if the resulting archive still needs Zip64), the size of the archive
147 will exceed 4 GB, or when the number of entries in the archive will
148 exceed about 64K. Zip64 is also used for archives streamed to a
149 non-seekable output device. You must use a 4.5 compatible UnZip to
150 extract files using the Zip64 extensions such as UnZip 6.0 or later.
151 .sk
152 In addition, streamed archives, entries encrypted with standard
153 encryption, or split archives created with the pause option may not be
154 compatible with PKZIP as data descriptors are used, and PKZIP at the
155 time of this writing does not support data descriptors (but recent
156 changes in the PKWare published .ZIP file standard now include some
157 support for the data descriptor format Zip uses).
158 .!------------------------------------------------------------------------------
159 .indent -4
160 2 More_Usage
161 .br
162 Here is a very simple example of Zip use:
163 .sk;.indent 10;
164 $ zip stuff.zip *.*
165 .sk
166 This will create the Zip archive "stuff.zip" (assuming it does not
167 already exist) and put all the (non-directory) files (";0") from the
168 current default directory into "stuff.zip" in a compressed form. The
169 archive is opened using a default file specification of
170 "SYS$DISK:[].zip", so specifying "stuff" as the archive name would also
171 create (or use an existing) "stuff.zip", but specifying "stuff.other"
172 would give you that name. In general, Zip doesn't care about the type
173 in the file specification, but for split archives (archives split over
174 multiple files), the user should normally specify a type-less name,
175 because Zip will normally generate sequentially numbered types ".z01",
176 ".z02", and so on for the early splits, and then the required ".zip" for
177 the last split. These file types are required by the Zip standard for
178 split archives.
179 .sk
180 Standard VMS wildcard expansion ($SEARCH) is used to interpret the
181 "inpath" file and directory specifications, like the "*.*" in this
182 example.
183 .sk
184 On VMS, the most natural way to archive an entire directory tree is to
185 use a directory-depth wildcard ("[...]"). For example:
186 .sk;.indent 10
187 zip foo [...]*.*
188 .sk
189 This will create the file "foo.zip" containing all the files (";0") and
190 directories in and below the current default directory. A more
191 UNIX-like way to do this would be to use the -r (--recurse-paths)
192 option:
193 .sk;.indent 10
194 $ zip -r foo *.*
195 .sk
196 Zip avoids including its own output files when selecting files to
197 include in the archive, so it should be safe, as in this case, to create
198 the archive in the same drectory as the input files.
199 .sk
200 One or more specific files, directories, or subdirectories may also be
201 specified:
202 .lm +10;.literal
203 zip foo.zip readme.txt [www...]*.* [.ftp...]*.* -
204 [.src]*.h [.src]*.c
205 .end literal;.lm -10
206 .sk
207 For security reasons, paths in Zip archives are always stored as
208 relative paths, so some care is needed when creating an archive so that
209 it will create the intended directory structure when UnZip is used to
210 unpack it.
211 .sk
212 To use -r with a specific directory, the name of the directory file
213 itself must be specified:
214 .sk;.indent 10
215 zip -r foo.zip [000000]www.dir ftp.dir
216 .sk
217 You may want to make an archive that contains the files in [.foo], but not
218 record the directory name, "foo". You can use the -j (junk path) option
219 to leave off the path:
220 .sk;.indent 10
221 $ zip -j foo [.foo]*.*
222 .sk
223 If you are short on disk space, you might not have enough room to hold
224 both the original directory and the corresponding compressed Zip
225 archive. In this case, you can create the archive in steps, and use the
226 -m option. For example, if [.foo] contains the subdirectories [.tom],
227 [.dick], and [.harry], you could:
228 .sk
229 .lm +10;.literal
230 zip -m foo [.foo.tom...]*.*
231 zip -m foo [.foo.dick...]*.*
232 zip -m foo [.foo.harry...]*.*
233 .end literal;.lm -10
234 .sk
235 The first command would create foo.zip, and the next two would add to
236 it. The -m option means "move", and it will cause Zip to delete all
237 files added to the archive after making or updating foo.zip. No
238 deletions will be done until the Zip operation has completed with no
239 errors. This option is obviously dangerous and should be used with
240 care, but it does reduce the need for free disk space. When -m is
241 used, the -T option is recommended and will test the resulting archive
242 before deleting the input files.
243 .sk
244 If a file specification list is too long to fit conveniently on the Zip
245 command line, the -@ option can be used to cause Zip to read a list of
246 file specifications from SYS$INPUT (stdin). If a DCL command procedure
247 is used, the names can be specified in the procedure:
248 .sk;
249 .lm +10;.literal
250 $ zip foo -@
251 $ deck
252 file_spec_1
253 file_spec_2
254 file_spec_3
255 $ eod
256 .end literal;.lm -10
257 .sk
258 The file specifications can also be put into a separate file, and fed
259 into Zip by explicitly defining SYS$INPUT, or by using PIPE. For
260 example, with the list in foo.zfl:
261 .sk;
262 .lm +10;.literal
263 $ define /user_mode sys$input foo.zfl
264 $ zip foo -@
265 .end literal;.lm -10;
266 or:
267 .lm +10;.literal
268 $ pipe type foo.zfl | zip foo -@
269 .end literal;.lm -10
270 .sk
271 If Zip is not able to read a file, it issues a warning but continues.
272 See the -MM option for more on how Zip handles patterns that are not
273 matched and files that are not readable. If some files were skipped, a
274 warning is issued at the end of the Zip operation noting how many files
275 were read and how many skipped.
276 .!------------------------------------------------------------------------------
277 .indent -4
278 2 Comments
279 .br
280 One-line comments may be included in the archive for each file added,
281 using the -c (--entry-comments) option. File operations (adding,
282 updating) are done first, and the user is then prompted for a one-line
283 comment for each file added or updated. Enter the comment followed by
284 <Return>, or just <Return> for no comment.
285 .sk
286 A single multi-line comment may be included for the archive as a whole,
287 using the -z (--archive-comment) option. UnZip (including UnZip SFX)
288 will display this comment when it expands the archive. The comment is
289 read from SYS$INPUT (stdin), and is terminated by the usual end-of-file
290 character, CTRL/Z. As usual, in a DCL command procedure, these data can
291 be included in-line in the procedure, or a user may DEFINE SYS$INPUT to
292 a file to get the comment from that file. Where supported, the DCL PIPE
293 command can also be used to redirect SYS$INPUT from a file.
294 .sk
295 Note that -z (--archive-comment) and -@ (read file specifications from
296 SYS$INPUT (stdin)) can't be used together (successfully).
297 .!------------------------------------------------------------------------------
298 .indent -4
299 2 Compression
300 .br
301 Zip can archive files with or without compression. The standard
302 compression method ("deflate") is compatible with all UnZip versions
303 (except really old ones that only understand the "store" method).
304 Current Zip and UnZip versions may be built with optional support for
305 the bzip2 compression method. (The bzip2 method can compress better,
306 especially when compressing smaller files, but uses more CPU time, and
307 requires an UnZip which includes the optional bzip2 support. See the
308 installation instructions for details on adding bzip2 compression
309 support at build time.)
310 .sk
311 Numeric compression level options control the effort put into data
312 compression, with -1 being the fastest, and -9 giving the most
313 compression.
314 .sk
315 Compression control options:
316 .sk;.lm +10;.literal
317 -Z mthd use compress method "mthd",
318 --compression-method mthd "bzip2" or "deflate" (default)
319
320 -0 (--store) no compression
321 -1 (--compress-1) compression level 1
322 -2 (--compress-2) compression level 2
323 -3 (--compress-3) compression level 3
324 -4 (--compress-4) compression level 4
325 -5 (--compress-5) compression level 5
326 -6 (--compress-6) compression level 6
327 -7 (--compress-7) compression level 7
328 -8 (--compress-8) compression level 8
329 -9 (--compress-9) compression level 9
330 .end literal;.lm -10
331 .sk
332 Normally, a file which is already compressed will not be compressed much
333 further (if at all) by Zip, and trying to do it can waste considerable
334 CPU time. Zip can suppress compression on files with particular types,
335 specified as a colon- or semi-colon-separated list of file types:
336 .sk;.indent 10
337 -n type1[:type2[...]] (--suffixes type1[:type2[...]])
338 .sk
339 For example:
340 .sk;.indent 10
341 zip -n .bz2:.gz:.jpeg:.jpg:.mp3:.zip foo [.foo]*.*
342 .sk
343 will put everything (";0") from [.foo] into foo.zip, but will store any
344 files that end in .bz2, .gz, .jpeg, .jpg, .mp3, or .zip, without trying
345 to compress them.
346 .sk
347 The default type list is .Z:.zip:.zoo:.arc:.lzh:.arj, and the comparison
348 is case-insensitive.
349 .sk
350 -9 (--compress-9) will override -n (--suffixes), causing compression to
351 be attempted for all files.
352 .!------------------------------------------------------------------------------
353 .indent -4
354 2 Encryption
355 .br
356 Zip offers optional encryption, using a method which by modern standards
357 is generally considered to be weak.
358 .sk;.literal
359 -e --encrypt
360 .end literal;.br
361 Encrypt new or updated archive entries using a password which is
362 supplied by the user interactively on the terminal in response to a
363 prompt. (The password will not be echoed.) If SYS$COMMAND is not a
364 terminal, Zip will exit with an error. The password is verified before
365 being accepted.
366 .sk;.literal
367 -P password --password password
368 .end literal;.br
369 Use "password" to encrypt new or updated archive entries (if any).
370 USING -P IS INSECURE! Many multi-user operating systems provide ways
371 for any user (or a privileged user) to see the current command line of
372 any other user. Even on more secure systems, there is always the threat
373 of over-the-shoulder peeking. Storing the plaintext password as part of
374 a command line in a command procedure is even less secure. Whenever
375 possible, use the non-echoing, interactive password entry method.
376 .sk
377 Because standard Zip encryption is weak, where security is truly
378 important, use a strong encryption program, such as Pretty Good Privacy
379 (PGP) or GNU Privacy Guard (GnuPG), on an archive instead of standard
380 Zip encryption. A stronger encryption method, such as AES, is planned
381 for Zip 3.1.
382 .!------------------------------------------------------------------------------
383 .indent -4
384 2 Exit_Status
385 .br
386 On VMS, Zip's UNIX-style exit values are mapped into VMS-style status
387 codes with facility code 1955 = %x7A3, and with the inhibit-message
388 (%x10000000) and facility-specific (%x00008000) bits set:
389 .sk
390 .literal
391 %x17A38001 normal exit
392 %x17A38000+ 16* Zip_error_code warnings
393 %x17A38002+ 16* Zip_error_code normal errors
394 %x17A38004+ 16* Zip_error_code fatal errors
395 .end literal
396 .sk
397 Note that multiplying the UNIX-style Zip error code by 16 places it
398 conveniently in the hexadecimal representation of the VMS exit code,
399 "__" in %x17A38__s, where "s" is the severity code. For example, a
400 truncated archive might cause Zip error code 2, which would be
401 transformed into the VMS exit status %x17A38024.
402 .sk
403 The Zip VMS exit codes include severity values which approximate those
404 defined by PKWARE, as shown in the following table:
405 .literal
406
407 VMS Zip err
408 severity code Error description
409 ----------+---------+----------------------------------------------
410 Success 0 Normal; no errors or warnings detected.
411 Fatal 2 Unexpected end of archive.
412 Error 3 A generic error in the archive format was
413 detected. Processing may have completed
414 successfully anyway; some broken archives
415 created by other archivers have simple work-
416 arounds.
417 Fatal 4 Zip was unable to allocate memory for one or
418 more buffers during program initialization.
419 Fatal 5 A severe error in the archive format was
420 detected. Processing probably failed imme-
421 diately.
422 Error 6 Entry too large to be split with zipsplit.
423 Error 7 Invalid comment format.
424 Fatal 8 Zip -T failed or out of memory.
425 Error 9 The user aborted zip prematurely with con-
426 trol-C (or equivalent).
427 Fatal 10 Zip encountered an error while using a temp
428 file.
429 Fatal 11 Read or seek error.
430 Warning 12 Zip has nothing to do.
431 Error 13 Missing or empty zip file.
432 Fatal 14 Error writing to a file.
433 Fatal 15 Zip was unable to create a file to write to.
434 Error 16 Bad command line parameters.
435 Error 18 Zip could not open a specified file to read.
436 Fatal 19 Zip was built with options not supported on
437 this system
438 Fatal 20 Attempt to read unsupported Zip64 archive
439 .end literal
440 .!------------------------------------------------------------------------------
441 .indent -4
442 2 Extra_Fields
443 .br
444 The .ZIP file format allows some extra data to be stored with a file in
445 the archive. For example, where local time zone information is
446 available, Zip can store UTC date-time data for files. (Look for
447 USE_EF_UT_TIME in a "zip -v" report.) On VMS, with -V or -VV, Zip will
448 also store VMS-specific file attributes. These data are packaged as
449 "extra fields" in the archive. Some extra fields are specific to a
450 particular operating system (like VMS file attributes). Large files
451 (bigger than 4GB) on any OS require an extra field to hold their 64-bit
452 size data. Depending on the capabilities of the UnZip program used to
453 expand the archive, these extra fields may be used or ignored when files
454 are extracted from the archive.
455 .sk
456 Some extra fields, like UTC date-times or VMS file attributes, are
457 optional. Others, like the Zip64 extra field which holds 64-bit sizes
458 for a large file, are required.
459 .sk
460 The -X (--strip-extra) option suppresses the saving of any optional
461 extra fields in the archive. (Thus, -X conflicts with -V or -VV.)
462 .!------------------------------------------------------------------------------
463 .indent -4
464 2 Environment
465 .br
466 A user can specify default command-line options and arguments by
467 defining an "environment variable" (that is, a logical name or DCL
468 symbol), "ZIP_OPTS" or "ZIPOPT", to specify them. If both "ZIP_OPTS" and
469 "ZIPOPT" are specified, the definition of "ZIPOPT" prevails.
470 .sk
471 The C RTL function getenv() is used to sense these variables, so its
472 behavior determines what happens if both a logical name and a symbol are
473 defined. As of VMS V7.3, a logical name supercedes a symbol.
474 .sk
475 The "zip -v" report should show the perceived settings of these
476 variables.
477 .!------------------------------------------------------------------------------
478 .indent -4
479 2 File_Names
480 .br
481 Zip deals with file names in the system file system and with file names
482 in Zip archives. File names in a Zip archive are stored in a UNIX-like
483 path-name format. For example, a VMS file specification like this:
484 .sk;.indent 10
485 [.zip30.vms]descrip.mms
486 .sk
487 could appear in a Zip archive as:
488 .sk;.indent 10
489 zip30/vms/descrip.mms
490 .sk
491 For security reasons, paths in Zip archives are always stored as
492 relative paths, so an absolute VMS directory specification will be
493 transformed to a relative path in the archive (that is, no leading "/").
494 For example, the following absolute directory specification would give
495 the same archive path as the previous (relative) example:
496 .sk;.indent 10
497 [zip30.vms]descrip.mms
498 .sk
499 Also, device names are dropped, so the following file specification
500 would also give the same archive path:
501 .sk;.indent 10
502 sys$sysdevice:[zip30.vms]descrip.mms
503 .sk
504 If an archive is intended for use with PKUNZIP under MSDOS, then the -k
505 (for "Katz", --DOS-names) option should be used to attempt to adjust the
506 names and paths to conform to MSDOS character-set and length
507 limitations, to store only the MSDOS file attributes (just the
508 owner:write attribute from VMS), and to mark the entry as made under
509 MSDOS (even though it wasn't).
510 .sk
511 Note that file specifications in the file system must be specified using
512 VMS notation, but file names in an archive must be specified using the
513 UNIX-like notation used in the archive. For example, where a BACKUP
514 command might look like this:
515 .sk.indent 10
516 $ back [.zip30...]*.* /excl = [...vms]*.c stuff.bck /save
517 .sk
518 a corresponding Zip command might look like this:
519 .sk;.indent 10;
520 $ zip stuff.zip [.zip30...]*.* -x */vms/*.c
521 .sk
522 because the files to be added to the Zip archive are specified using VMS
523 file specifications, but the -x (--exclude) option excludes names based
524 on their archive path/file names. Options dealing with archive names
525 include -R (--recurse-patterns), -d (--delete), -i (--include), -x
526 (--exclude), and -U (--copy-entries).
527 .sk
528 Note: By default, on VMS, archive name pattern matching (-R, -d, -i, -x,
529 and -U) is case sensitive, even when the file system is not case
530 sensitive (or even case preserving). This allows accurate matching of
531 mixed-case names in an archive which may have been created on a system
532 with a case sensitive file system, but it can involve extra effort on
533 VMS, where it may be necessary to use unnatural case names (or the same
534 names in multiple cases, like "*.obj *.OBJ") for this kind of pattern
535 matching to give the desired behavior. If completely case-blind pattern
536 matching behavior is desired, specify the -ic (--ignore-case) option.
537 .!------------------------------------------------------------------------------
538 .indent -4
539 3 Case
540 .br
541 For better compatibility with UNIX-like systems, Zip, by default,
542 down-cases ODS2 file names. For example, the following file on an ODS2
543 file system:
544 .sk;.indent 10
545 [.ZIP30.VMS]DESCRIP.MMS
546 .sk
547 would appear in an archive as:
548 .sk;.indent 10
549 zip30/vms/descrip.mms
550 .sk
551 Zip versions before 3.0 down-cased all VMS file names. Now, various
552 options give the user control over these conversions:
553 .sk
554 .lm +10;.literal
555 -C preserve case of all file names
556 -C- down-case all file names
557 -C2 preserve case of ODS2 names
558 -C2- down-case ODS2 file names (default)
559 -C5 preserve case of ODS5 names (default)
560 -C5- down-case ODS5 file names
561 .end literal;.lm -10
562 .sk
563 Case is handled differently for archive member names, which the user
564 specifies with the -R, -d, -i, -x, and -U options. By default, on VMS,
565 archive name pattern matching is case sensitive, even when the file
566 system is not case sensitive (or even case preserving). This allows
567 accurate matching of mixed-case names in an archive which may have been
568 created on a system with a case sensitive file system, but it can
569 involve extra effort on VMS, where it may be necessary to use unnatural
570 case names (or the same names in multiple cases, like "*.obj *.OBJ") for
571 this kind of pattern matching to give the desired behavior. If
572 completely case-blind pattern matching behavior is desired, specify the
573 -ic (--ignore-case) option.
574 .!------------------------------------------------------------------------------
575 .indent -4
576 2 Fixing_Damage
577 .br
578 Two options can be used to fix a damaged Zip archive.
579 .sk;.literal
580 -F --fix
581 -FF --fixfix
582 .end literal;.sk
583 The -F (--fix) option can be used if some portions of the archive are
584 missing, but it requires a reasonably intact central directory. The
585 input archive is scanned as usual, but zip will ignore some problems.
586 The resulting archive should be valid, but any inconsistent entries
587 will be left out.
588 .sk
589 If the archive is too damaged or the end (where the central directory is
590 situated) has been truncated, you must use -FF (--fixfix). This is a
591 change from zip 2.32, where the -F option is able to read a truncated
592 archive. The -F option now more reliably fixes archives with minor
593 damage, and the -FF option is needed to fix archives where -F and -FF
594 was used before.
595 .sk
596 With -FF, the archive is scanned from the beginning and Zip scans for
597 special signatures to identify the limits between the archive members.
598 The -F option is more reliable if the archive is not too much damaged,
599 so try this option first.
600 .sk
601 Neither option will recover archives that have been incorrectly
602 transferred, such as by FTP in ASCII mode instead of binary. After the
603 repair, the -t option of UnZip may show that some files have a bad CRC.
604 Such files cannot be recovered; you can remove them from the archive
605 using the -d option of Zip.
606 .sk
607 Because of the uncertainty of the "fixing" process, it's required
608 to specify an output archive, rather than risking further damage to the
609 original damaged archive. For example, to fix the damaged archive
610 foo.zip,
611 .sk;.indent 10
612 zip -F foo --out foo_fix
613 .sk
614 tries to read the entries normally, copying good entries to the new
615 archive foo_fix.zip. If this doesn't work, as when the archive is
616 truncated, or if some entries are missed because of bad central
617 directory entries, try -FF:
618 .sk;.indent 10
619 zip -FF foo --out foo_fixfix
620 .sk
621 and compare the resulting archive to the archive created using -F. The
622 -FF option may create an inconsistent archive. Depending on what is
623 damaged, you can then use the -F option to fix that archive.
624 .sk
625 A split archive with missing split files can be fixed using -F if you
626 have the last split of the archive (the ".zip" file). If this file is
627 missing, you must use -FF to fix the archive, which will prompt you for
628 the splits you have.
629 .sk
630 Currently, the fix options can't recover an entry which has a bad
631 checksum or is otherwise damaged.
632 .!------------------------------------------------------------------------------
633 .indent -4
634 2 Log_File
635 .br
636 Zip normally sends messages to the user's terminal, but these may be
637 also directed to a log file.
638 .sk;.literal
639 -la --log-append
640 .end literal;.br
641 Append to an existing log file. Default is to create a new version.
642 .sk;.literal
643 -lf logfilepath --logfile-path logfilepath
644 .end literal;.br
645 Open a logfile at the given path. By default, a new version will be
646 created, but with the -la option an existing file will be opened and the
647 new log information appended to any existing information. Only
648 warnings and errors are written to the log unless the -li option is also
649 given, then all information messages are also written to the log.
650 .sk;.literal
651 -li --log-info
652 .end literal;.br
653 Include information messages, such as file names being zipped, in the
654 log. The default is to include only the command line, any warnings
655 and errors, and the final status.
656 .!------------------------------------------------------------------------------
657 .indent -4
658 2 Modes_of_Operation
659 .br
660 Zip supports two distinct types of command modes, external and
661 internal. The external modes (update, grow, and freshen) read files
662 from the file system (as well as from an existing archive) while the
663 internal modes (delete and copy) operate exclusively on entries in an
664 existing archive.
665 .sk;.literal
666 -u --update
667 .end literal;.br
668 Update existing entries and add new files. If the archive does not
669 exist, create it. This is the default mode, so -u is optional.
670 .sk;.literal
671 -g --grow
672 .end literal;.br
673 Grow (append to) the specified Zip archive, instead of creating a new
674 one. If this operation fails, Zip attempts to restore the archive to
675 its original state. If the restoration fails, the archive might become
676 corrupted. This option is ignored when there's no existing archive or
677 when at least one archive member must be updated or deleted.
678 .sk;.literal
679 -f --freshen
680 .end literal;.br
681 Update existing entries in an existing archive. Does not add new files
682 to the archive.
683 .sk;.literal
684 -d --delete
685 .end literal;.br
686 Delete entries from an existing archive.
687 .sk;.literal
688 -DF --difference-archive
689 .end literal;.br
690 Create an incremental backup-style archive, where the resulting archive
691 will contain all new and changed files since the original archive was
692 created. For this to work, the input file list and current directory
693 must be the same as during the original Zip operation.
694 .sk
695 For example, if the existing archive was created using
696 .sk;.indent 10
697 zip foo_full.zip [.foo...]*.*
698 .sk
699 from just above the foo directory, then the command (also from just
700 above the foo directory):
701 .sk;.indent 10
702 zip foo_full.zip [.foo...]*.* -DF -O foo_incr.zip
703 .sk
704 creates the archive foo_incr.zip with just the files not in foo_full.zip
705 and the files where the size or date-time of the files does not match
706 that in foo_full.zip. Note that in the "zip -DF" operation, the
707 original full archive is specified as the input archive, and the -O
708 (--output-file) option is used to specify the new (incremental) output
709 archive.
710 .sk;.literal
711 -FS --filesync
712 .end literal;.br
713 Delete entries in the archive that do not match files on the OS.
714 Normally when an archive is updated, new files are added and changed
715 files are updated but files that no longer exist on the OS are not
716 deleted from the archive. This option enables deleting of entries that
717 are not matched on the OS. Enabling this option should create archives
718 that are the same as new archives, but since existing entries are copied
719 instead of compressed, updating an existing archive with -FS can be much
720 faster than creating a new archive. If few files are being copied from
721 the old archive, it may be faster to create a new archive instead.
722 .sk
723 This option deletes files from the archive. If you need to preserve the
724 original archive, make a copy of the archive first, or use the -O
725 (--output) option to output the new archive to a new file. Even though
726 it's slower, creating a new archive with a new archive name is safer,
727 avoids mismatches between archive and OS paths, and is preferred.
728 .sk;.literal
729 -U --copy-entries
730 .end literal;.br
731 Select entries in an existing archive and copy them to a new archive.
732 Copy mode is like update mode, but entries in the existing archive are
733 selected by command line patterns rather than files from the file system
734 and it uses the -O (--output-file) option to write the resulting archive
735 to a new file rather than updating the existing archive, leaving the
736 original archive unchanged.
737 .sk
738 Normally, when updating an archive using relative file specifications
739 ("[]", "[.xxx]", and so on), it helps to have the same default directory
740 as when the archive was created, but this is not a strict requirement.
741 .sk
742 Date-time information in a Zip archive may be influenced by time zone.
743 .!------------------------------------------------------------------------------
744 .indent -4
745 3 Examples
746 .br
747 When given the name of an existing archive, Zip will replace identically
748 named entries in the archive or add entries for new names. For example,
749 if foo.zip exists and contains foo/file1 and foo/file2, and the
750 directory [.foo] contains the files file1 and file3, then:
751 .sk;.indent 10
752 $ zip foo [.foo...]*.*
753 .sk
754 will replace foo/file1 in foo.zip and add foo/file3 to foo.zip. After
755 this, foo.zip contains foo/file1, foo/file2, and foo/file3, with foo/file2
756 unchanged from before. This is the default mode -u (update).
757 .sk
758 Update will add new entries to the archive and will replace
759 existing entries only if the modified date of the file is more recent than
760 the date recorded for that name in the archive. For example:
761 .sk;.indent 10
762 $ zip -u stuff *.*
763 .sk
764 will add any new files in the current directory, and update any changed
765 files in the archive stuff.zip. Note that Zip will not try to pack
766 stuff.zip into itself when you do this. Zip avoids including its own
767 output files when selecting files to include in the archive, so it
768 should be safe, as in this case, to have the archive included in the
769 list of input files.
770 .sk
771 A second mode, -f (freshen), like update will only
772 replace entries with newer files. Unlike update, however, it will not
773 add files that are not already in the archive. For example:
774 .sk;.indent 10
775 $ zip -f foo
776 .sk
777 Note that the -f option with no arguments freshens all the entries in the
778 archive. The same is true of -u, so "zip -u foo" and "zip -f foo" do
779 the same thing.
780 .sk
781 When these options are used, Zip should be run from the same directory
782 as when the original Zip command was run, so that the path names in the
783 archive will continue to agree with the path names in the file system.
784 Normally, it's also a good idea to keep the other options the same (-V,
785 -w, and the like), to keep the archive contents consistent.
786 .sk
787 The -t (--from-date) and -tt (--before-date) options can also be used
788 with adding, updating, or freshening to restrict further the files to be
789 included in the archive. For example:
790 .sk;.indent 10
791 $ zip -rt 12071991 infamy [.FOO]*.*
792 .sk
793 will add all the files in [.FOO] and its subdirectories that were last
794 modified on December 7, 1991, or later to the achive infamy.zip. Dates
795 can be in format mmddyyyy or yyyy-mm-dd.
796 .sk
797 Also, files can be explicitly excluded using the -x option:
798 .sk;.indent 10
799 $ zip -r foo [.FOO] -x *.obj
800 .sk
801 which will zip up the contents of [.FOO] into foo.zip but exclude all the
802 files that end in ".obj".
803 .sk
804 The -d (delete) mode will remove entries from an
805 archive. An example might be:
806 .sk;.indent 10
807 $ zip -d foo foo/harry/*.* *.obj
808 .sk
809 which will remove all of the files that start with "foo/harry/" and all of
810 the files that end with ".obj" (in any path).
811 .sk
812 The last mode, -U (--copy-entries), selects entries from an existing
813 archive and copies them to a new archive.
814 .sk;.indent 10
815 $ zip -U foo *.obj --out fooobj
816 .sk
817 will copy all .obj entries from foo.zip and put them in the new archive
818 fooobj.zip.
819 .sk
820 Note: By default, on VMS, archive name pattern matching (-R, -d, -i, -x,
821 and -U) is case sensitive, even when the file system is not case
822 sensitive (or even case preserving). This allows accurate matching of
823 mixed-case names in an archive which may have been created on a system
824 with a case sensitive file system, but it can involve extra effort on
825 VMS, where it may be necessary to use unnatural case names (or the same
826 names in multiple cases, like "*.obj *.OBJ") for this kind of pattern
827 matching to give the desired behavior. If completely case-blind pattern
828 matching behavior is desired, specify the -ic (--ignore-case) option.
829 .!------------------------------------------------------------------------------
830 .indent -4
831 2 Options_List
832 .br
833 "zip -h" provides a concise list of common command-line options. "zip
834 -h2" provides more details. "zip -so" provides a list of all available
835 options. "zip -v" shows the program version and available features.
836 (The list below was derived from a "zip -so" listing.)
837 .sk
838 Short-form options begin with a single hyphen ("-"). Long-form option
839 begin with a double hyphen ("--"), and may be abbreviated to any
840 unambiguous shorter string. For example:
841 .lm +10;.literal
842 -v
843 --verbose
844 --verb
845 .end literal;.lm -10
846 .sk
847 To avoid confusion, if a negatable option contains an embedded hyphen
848 ("-"), then avoid abbreviating it at the hyphen if you plan to negate
849 it. For example, if an option like --some-option were abbreviated to
850 --some-, the parser would consider that trailing hyphen to be part of
851 the option name, rather than as a negating trailing hyphen. This
852 behavior may change in the future, to interpret the trailing hyphen in
853 --some- to be negating. (So don't do it.)
854 .sk
855 Some options may be negated (or modified) by appending a "-":
856 .lm +10;.literal
857 -la-
858 --show-files-
859 .end literal;.lm -10
860 .sk
861 Some options take a value, which may immediately follow the option, or
862 be separated by a space or "=". For example:
863 .lm +10;.literal
864 -ttmmddyyyy
865 -tt mmddyyyy
866 -tt=mmddyyyy
867 .end literal;.lm -10
868 .sk
869 .lm -4;.literal
870 Sh Long Description
871 ----+-------------------+--------------------------------------------------
872 0 store store (instead of compress)
873 1 compress-1 compress faster (-2, -3, -4, ...)
874 9 compress-9 compress better
875 ? show the Zip help screen
876 @ names-stdin read input file patterns from SYS$INPUT (1/line)
877 A adjust-sfx adjust self-extracting executable
878 b temp-path path use "path" directory for temporary files
879 C preserve-case preserve case of all file names added to archive
880 C- preserve-case- down-case all file names added to archive
881 C2 preserve-case-2 preserve case of ODS2 names added to archive
882 C2- preserve-case-2- down-case ODS2 file added to archive (default)
883 C5 preserve-case-5 preserve case of ODS5 names added to archive (dflt)
884 C5- preserve-case-5- down-case ODS5 names added to archive
885 c entry-comments add a comment for each entry added to archive
886 D no-dir-entries do not add archive entries for directories
887 DF difference-archive difference archive: add only changed or new files
888 d delete delete entries in archive
889 db display-bytes display running byte counts
890 dc display-counts display running file counts
891 dd display-dots display progress dots for files (dflt size = 10MB)
892 dg display-globaldots display progress dots for archive, not each file
893 ds dot-size size set progress dot interval to "size" (MB)
894 du display-usize display original uncompressed size for entries
895 dv display-volume display volume (disk) number as in_disk>out_disk
896 e encrypt encrypt entries, ask for password
897 F fix fix mostly intact archive (try F before FF)
898 FF fixfix salvage what can be salvaged (not as reliable)
899 FS filesync remove archive entries unmatched in file system
900 f freshen update existing entries (only changed files)
901 fd force-descriptors force data descriptors as if streaming
902 fz force-zip64 force use of Zip64 format
903 g grow grow existing archive (unless updating or deleting)
904 H show the Zip help screen
905 h help show the Zip help screen
906 h2 more-help show extended Zip help
907 i include pat1 [pat2 [...]] include only names matching the patterns
908 ic ignore-case ignore case (case-blind archive entry name matching)
909 J junk-sfx junk (remove) archive preamble (unzipsfx)
910 j junk-paths junk (don't store) directory names, only file names
911 k DOS-names simulate PKZIP-made archive (DOS 8.3 names)
912 L license show software license
913 l to-crlf translate end-of-lines (LF -> CRLF)
914 la log-append append to existing log file
915 lf logfile-path lfile log to log file at lfile (default: new version)
916 li log-info include informational messages in log
917 ll from-crlf translate end-of-lines (CRLF -> LF)
918 MM must-match input file spec must exist (wildcards must match)
919 m move delete files added to archive
920 n suffixes sfx1[:sfx2[...]] don't compress files with these suffixes
921 nw no-wild no wildcards during add or update
922 O output-file ozf use "ozf" as the output archive (dflt = inp archive)
923 o latest-time set archive date-time to match oldest entry
924 P password password encrypt with supplied "password" string
925 q quiet quiet operation (no info messages)
926 R recurse-patterns recurse into subdirs from cur dir, match names only
927 r recurse-paths recurse into directories from specified path pats
928 s split-size size split archive at "size" (K/MB) (0: don't split)
929 sb split-bell ring terminal bell at pause for split medium change
930 sc show-command show command line
931 sd show-debug show debug messages
932 sf show-files show files to process (only)
933 so show-options show list of all command-line options
934 sp split-pause pause to select split destination(s)
935 sv split-verbose be verbose about creating splits
936 T test test archive integrity (runs UnZip -T)
937 t from-date mmddyyyy only do files since (at or after) "mmddyyyy"
938 tt before-date mmddyyyy only do files before "mmddyyyy"
939 u update update changed files, add new files (default mode)
940 V VMS-portable save VMS file attributes
941 VV VMS-specific save VMS file attributes and all allocated blocks
942 v verbose verbose messages (print version info if only arg)
943 w VMS-versions save VMS version numbers in archive
944 ww VMS-dot-versions save VMS version numbers as ".nnn", not ";nnn"
945 X strip-extra strip all but critical extra fields
946 X- strip-extra- keep all extra fields
947 x exclude pat1 [pat2 [...]] exclude all names matching the patterns
948 Z compression-method mthd use compress method "mthd" (bzip2 or deflate)
949 z archive-comment ask for archive comment
950 .end literal;.lm +4
951 .!------------------------------------------------------------------------------
952 .indent -4
953 2 Miscellaneous_Options
954 .sk;.literal
955 -D --no-dir-entries
956 .end literal;.br
957 Do not create entries in the archive for directories. By default,
958 directory entries are added to an archive, so that their attributes can
959 be saved in the archive. When an archive is created using -D, UnZip
960 will still create directories as needed (subject to user control), but
961 they will get the default attributes (date-time, permissions, ...) on
962 the destination system, rather than their original atributes.
963 .sk;.literal
964 -MM --must-match
965 .end literal;.br
966 All input patterns must match at least one file and all input files
967 found must be readable. Normally when an input pattern does not match
968 a file the "name not matched" warning is issued and when an input
969 file has been found but later is missing or not readable a "missing or
970 not readable" warning is issued. In either case Zip continues
971 creating the archive, with missing or unreadable new files being skipped
972 and files already in the archive remaining unchanged. After the
973 archive is created, if any files were not readable zip returns the OPEN
974 error code (18 on most systems) instead of the normal success return (0
975 on most systems). With -MM, Zip exits as soon as an input pattern
976 is not matched (whenever the "name not matched" warning would be issued)
977 or when an input file is not readable. In either case Zip exits with
978 an OPEN error and no archive is created.
979 .sk
980 This option is useful when a known list of files is to be zipped so any
981 missing or unreadable files should result in an error. It may be less
982 useful when used with wildcards, but Zip will still exit with an error
983 if any input pattern doesn't match at least one file or if any
984 matched files are unreadable. If you want to create the archive anyway
985 and only need to know if files were skipped, then don't use -MM and just
986 check the exit status. Also, a log file (see -lf (--logfile-path))
987 could be useful.
988 .sk;.literal
989 -O out_file --output-file out_file
990 .end literal;.br
991 Process the archive changes as usual, but instead of updating the
992 existing archive, send the output to a new archive, "out_file". The
993 output archive specified must be a different file from the input
994 archive.
995 .sk
996 This option can be used to create updated split archives. It can
997 also be used with -U to copy entries from an existing archive to
998 a new archive. See the EXAMPLES section below.
999 .sk
1000 Another use is converting zip files from one split size to
1001 another. For instance, to convert an archive with 700MB CD splits
1002 to one with 2GB DVD splits, can use:
1003 .sk;.indent 10
1004 zip -s 2g cd-split.zip --out dvd-split.zip
1005 .sk
1006 which uses copy mode. See -U below. Also:
1007 .sk;.indent 10
1008 zip -s 0 split.zip --out unsplit.zip
1009 .sk
1010 will convert a split archive to a single-file archive.
1011 .sk
1012 Copy mode will convert stream entries (using data descriptors and which
1013 may be incompatible with some unzip programs) to normal entries (which
1014 should be compatible with all unzip programs), except if standard
1015 encryption was used. For archives with encrypted entries, zipcloak
1016 will decrypt the entries and convert them to normal entries.
1017 .sk;.literal
1018 -o --latest-time
1019 .end literal;.br
1020 Set the modification date-time of the Zip archive file to the latest
1021 (newest) modification date-time found among the entries in the zip
1022 archive. This can be used without any other operations, if
1023 desired. For example:
1024 .sk;.indent 10
1025 zip -o foo
1026 .sk
1027 will change the modification date-time of foo.zip to the latest time of
1028 the entries in foo.zip.
1029 .sk;.literal
1030 -q --quiet
1031 .end literal;.br
1032 Quiet mode. Eliminates informational messages and comment prompts.
1033 This mode may be useful in command procedures, or if the Zip operation
1034 is being performed as a background task ("$ spawn/nowait zip -q foo
1035 *.c").
1036 .sk
1037 .sk;.literal
1038 -T --test
1039 .end literal;.br
1040 Test the integrity of a zip archive (the new one, if -O (--output-file)
1041 is specified). If the check fails, the old zip file is unchanged and
1042 (with the -m option) no input files are removed.
1043 .sk
1044 Implementation
1045 .br
1046 "zip -T" actually runs an "unzip -t" command to do the testing, so UnZip
1047 must be installed properly for this to work.
1048 .sk;.literal
1049 -TT unzip_cmd --unzip-command unzip_cmd
1050 .end literal;.br
1051 Specify the actual UnZip command, "unzip_cmd" (normally a DCL symbol) to
1052 use for "zip -T". This can be useful if multiple versions of UnZip are
1053 installed on a system, and the default DCL symbol "UNZIP" would run the
1054 wrong one (or the logical name DCL$PATH would lead to the wrong one).
1055 .sk
1056 In "unzip_cmd", the string "{}" is replaced by the temporary name of the
1057 archive to be tested, otherwise the name of the archive is appended
1058 to the end of the command. The exit status is checked for success severity.
1059 .sk;.literal
1060 -v --verbose
1061 .end literal;.br
1062 Verbose mode or print diagnostic version info.
1063 .sk
1064 Normally, when applied to real operations, this option enables the
1065 display of a progress indicator during compression (see -dd for more on
1066 dots) and requests verbose diagnostic info about archive structure
1067 oddities.
1068 .sk
1069 When -v is the only command line argument, a diagnostic report is
1070 displayed, showing:
1071 .lm +3;.br;.indent -2
1072 o Copyright and other legal notices
1073 .br;.indent -2
1074 o Program name, version, and release date
1075 .br;.indent -2
1076 o Pointers to Info-ZIP FTP and Web sites
1077 .br;.indent -2
1078 o Program build information (compiler type and version, OS version, and
1079 the compilation date
1080 .br;.indent -2
1081 o Optional features enabled at compile-time
1082 .br;.indent -2
1083 o Environment variable definitions (ZIP_OPTS, ZIPOPT)
1084 .lm -3;.br
1085 .sk
1086 This information should be included in bug reports.
1087 .sk;.literal
1088 -y --symlinks
1089 .end literal;.br
1090 Store symbolic links as such in the Zip archive, instead of compressing
1091 and storing the file referred to by the link. A symbolic link normally
1092 requires less storage than the actual file, both in the archive, and on
1093 the destination file system.
1094 .sk
1095 On VMS, symbolic links are supported on ODS5 disks where the C RTL
1096 supports symbolic links. Full support for symbolic links seems to
1097 require VMS V8.3, but a Zip program supporting symbolic links may be
1098 built on VMS V7.3-2.
1099 .!------------------------------------------------------------------------------
1100 .indent -4
1101 2 Progress_Display
1102 .br
1103 Various options control the display of progress messages during Zip
1104 operation.
1105 .sk;.literal
1106 -db --display-bytes
1107 .end literal;.br
1108 Display running byte counts showing the bytes processed and the bytes to
1109 go.
1110 .sk;.literal
1111 -dc --display-counts
1112 .end literal;.br
1113 Display running count of entries processed and entries to go.
1114 .sk;.literal
1115 -dd --display-dots
1116 .end literal;.br
1117 Display dots while each entry is processed (except on ports that have
1118 their own progress indicator). See -ds below for setting dot size. The
1119 default is a dot every 10 MB of input file processed. The -v
1120 (--verbose) option also displays dots and used to at a higher rate than
1121 this (at the same rate as in previous versions of Zip) but this rate has
1122 been changed to the new 10 MB default, and is also controlled by -ds.
1123 .sk;.literal
1124 -dg --display-globaldots
1125 .end literal;.br
1126 Display progress dots for the archive instead of for each file. The
1127 command
1128 .sk;.indent 10
1129 zip -qdgds 10m
1130 .sk
1131 will turn off most output except dots every 10 MB.
1132 .sk;.literal
1133 -ds size --dot-size size
1134 .end literal;.br
1135 Set amount of input file processed for each dot displayed. See -dd to
1136 enable displaying dots. Setting this option implies -dd. "size" is in
1137 the format "nm" where n is a number and m is a multiplier. Currently
1138 "m" can be k (KB), m (MB), g (GB), or t (TB), so if "n" is 100 and "m"
1139 is k, "size" would be 100k which is 100KB. The default is 10MB.
1140 .sk
1141 The -v (--verbose) option also displays dots and used to default to a
1142 higher rate than this (at the same rate as in previous versions of Zip)
1143 but now the default is 10 MB and the -v dots are also controlled by this
1144 option. A "size" of 0 turns dots off.
1145 .sk
1146 This option does not control the dots from the "Scanning files" message
1147 as Zip scans for input files. The dot size for that is fixed at 2
1148 seconds or a fixed number of entries, whichever is longer.
1149 .sk;.literal
1150 -du --display-usize
1151 .end literal;.br
1152 Display the uncompressed size of each entry.
1153 .sk;.literal
1154 -dv --display-volume
1155 .end literal;.br
1156 Display the volume (disk) number each entry is being written to.
1157 .!------------------------------------------------------------------------------
1158 .indent -4
1159 2 Self_Extracting_Archives
1160 .br
1161 A self-extracting archive (SFX) comprises a normal Zip archive appended
1162 to a special UnZip program (such as UNZIPSFX.EXE) for the intended
1163 target system.
1164 .sk
1165 The UnZip distribution includes a VMS command procedure,
1166 [,vms]makesfx.com, which can be used directly or adapted to create an
1167 SFX archive from a normal Zip archive.
1168 .sk
1169 The .ZIP file format includes offsets to data structures in the archive,
1170 and these offsets are measured from the start of the archive file.
1171 Appending an archive to an UnZip SFX executable effectively moves the
1172 start of the archive file. That makes the original offsets wrong, and
1173 that will cause the UnZip SFX program to emit warning messages when it
1174 tries to unpack the archive. Zip -A can be used to adjust these offsets
1175 in a self-extracting archive. For example, to adjust the offsets in
1176 foo.sfx_exe:
1177 .sk;.indent 10
1178 zip -A foo.sfx_exe
1179 .sk
1180 Similarly, the UnZip SFX program can be removed from a self-extracting
1181 archive (and the offsets in the archive restored) using the -J
1182 (--junk-sfx) option. For example:
1183 .sk;.indent 10
1184 zip -J foo.sfx_exe
1185 .sk
1186 Note that a self-extracting archive contains a normal Zip archive, and a
1187 normal UnZip program can be used to expand it in the normal way. You
1188 may get a warning about extra bytes at the beginning of the archive (the
1189 UnZip SFX program), but UnZip should work properly after that. This
1190 allows data in a self-extracting archive to be accessed on any system,
1191 not just the target system where its embedded UnZip SFX program runs.
1192 .!------------------------------------------------------------------------------
1193 .indent -4
1194 2 Split_Archives
1195 .br
1196 Beginning with version 3.0, Zip supports split archives. A split
1197 archive is one which is divided into multiple files, usually to allow it
1198 to be stored on multiple storage media (floppy diskettes, CD-ROMs, or
1199 the like) when a single medium would be too small to contain the whole
1200 archive. (Note that split archives are not just unitary archives split
1201 into pieces, as the .ZIP file format includes offsets to data structures
1202 in the archive, and for a split archive these are based on the start of
1203 each split, not on the start of the whole archive. Concatenating the
1204 pieces will invalidate these offsets, but UnZip can usually deal with
1205 it. Zip will usually refuse to process such a spliced archive unless
1206 the -FF fix option is used to fix the offsets.)
1207 .sk
1208 For a split archive with, say, 20 split files, the files are typically
1209 named ARCHIVE.z01, ARCHIVE.z02, ..., ARCHIVE.z19, ARCHIVE.zip, where
1210 "ARCHIVE" is the archive name specified by the user on the Zip command
1211 line. Note that the last split file is the ".zip" file. In contrast,
1212 "spanned" archives are the original multi-disk archive generally
1213 requiring floppy disks and using volume labels to store disk numbers.
1214 Zip supports split archives but not spanned archives, though a procedure
1215 exists for converting split archives of the right size to spanned
1216 archives. The reverse is also true, where each file of a spanned
1217 archive can be copied in order to files with the above names to create a
1218 split archive.
1219 .!------------------------------------------------------------------------------
1220 .indent -4
1221 3 Options
1222 .br
1223 Use "-s size" to create a split archive (and to set the split size).
1224 The size is given as a number followed optionally by a multiplier suffix
1225 of k (KB), m (MB, the default if no suffix is specified), g (GB), or t
1226 (TB). (All are powers of 1024, not 1000). 64K is the minimum split
1227 size. For example, the following command could be used to create a
1228 split archive called "foo" from the contents of the "bar" directory with
1229 splits of 670MB, which might be useful for burning on CDs:
1230 .sk;.indent 10
1231 zip -s 670m foo [.bar...]*.*
1232 .sk
1233 Using -s without -sp as above creates all the splits in the directory
1234 specified by "foo", in this case the current default directory. This
1235 split mode updates the splits as the archive is being created, requiring
1236 all splits to remain writable, but creates split archives that are
1237 readable by any UnZip that supports split archives. See -sp below for
1238 enabling split pause mode which allows splits to be written directly to
1239 removable media.
1240 .sk
1241 The -sv option can be used to enable verbose splitting and display
1242 details of how the splitting is being done. The -sb option can be used
1243 to ring the terminal bell when Zip pauses for the next split
1244 destination.
1245 .sk
1246 The -sp option can be used to pause Zip between splits to allow
1247 changing removable media, for example, but read the descriptions and
1248 warnings for both -s and -sp below.
1249 .sk
1250 Though Zip does not update split archives, Zip provides the option
1251 -O (--output-file) to allow split archives to be updated and saved in a
1252 new archive. For example:
1253 .sk;.indent 10
1254 zip inarchive.zip foo.c bar.c -O outarchive.zip
1255 .sk
1256 reads archive inarchive.zip, even if split, adds the files foo.c and
1257 bar.c, and writes the resulting archive to outarchive.zip. If
1258 inarchive.zip is split, then outarchive.zip defaults to the same split
1259 size. Be aware that outarchive.zip and any split files that are created
1260 with it are always overwritten without warning. This may be changed in
1261 the future.
1262 .!------------------------------------------------------------------------------
1263 .indent -4
1264 2 Temporary_Files
1265 .br
1266 When creating a new archive or normally when changing an existing
1267 archive, Zip will write a temporary file in the archive destination
1268 directory ("ZIxxxxxxxx", where "xxxxxxxx" is the hexadecimal process ID)
1269 with the new contents. Then, if and when the Zip job has completed with
1270 no errors, it will rename the temporary file to the specified archive
1271 name (replacing the old archive, if any).
1272 .sk
1273 You can use the -b (--temp-path) option to specify a different path
1274 (device and/or directory) for the temporary file, but specifying a
1275 different device will force Zip to copy the temporary file to its final
1276 destination instead of simply renaming it, and that copying will take
1277 more time than renaming, especially for a large archive. For example:
1278 .sk;.indent 10
1279 $ zip -b disk$scratch:[tmp] stuff *
1280 .sk
1281 will cause Zip to put its temporary files in the directory
1282 "disk$scratch:[tmp]", copying the temporary file back to the current
1283 directory as stuff.zip when it's complete.
1284 .!------------------------------------------------------------------------------
1285 .indent -4
1286 2 Text_Files
1287 .br
1288 Zip offers some options to help deal with line endings in text files.
1289 These may have limited utility on VMS.
1290 .sk;.literal
1291 -l --to-crlf
1292 .end literal;.br
1293 Translate the UNIX end-of-line character LF (CR on MAC) into the MSDOS
1294 convention CR-LF. This option should not be used on binary files. This
1295 option can be used on UNIX if the Zip file is intended for PKUNZIP under
1296 MSDOS. If the input files already contain CR-LF, this option adds an
1297 extra CR. This ensure that "unzip -a" on Unix will get back an exact
1298 copy of the original file, to undo the effect of "zip -l". See -ll
1299 below for the binary checks.
1300 .sk;.literal
1301 -ll --from-crlf
1302 .end literal;.br
1303 Translate the MSDOS end-of-line CR LF into UNIX LF (CR on MAC). This
1304 option should not be used on binary files. This option can be used on
1305 MSDOS if the Zip archive is intended for UnZip under UNIX.
1306 .sk
1307 For both -l and -ll, if the file is converted and the file is later
1308 determined to be binary, a warning is issued and the file is probably
1309 corrupted. If Zip with -l or -ll detects binary (non-text) in the first
1310 buffer read from a file, it issues a warning and skips line-ending
1311 conversion on the file, avoiding corruption. This check seems to catch
1312 all binary files tested, but the original check remains and if a
1313 converted file is later determined to be binary, that warning is still
1314 issued. The algorithm now being used for binary detection should allow
1315 line-ending conversion of text files in UTF-8 and similar encodings.
1316 .!------------------------------------------------------------------------------
1317 .indent -4
1318 2 VMS_Specifics
1319 .br
1320 VMS File Attributes
1321 .sk;.literal
1322 -V --VMS-portable
1323 -VV --VMS-specific
1324 .end literal;.br
1325 The -V and -VV options cause Zip to store VMS file atributes (such as
1326 file organization, record format, carriage control, and so on) in
1327 VMS-specific "extra fields" in an archive along with the usual data.
1328 These extra fields are ignored on non-VMS systems, but on a VMS system,
1329 they allow UnZip to restore the files with their VMS attributes intact.
1330 .sk
1331 With -V, Zip ignores any data in the file after the end-of-file (EOF)
1332 point (defined by FAT$L_EFBLK and FAT$W_FFBYTE), which works well for
1333 well-formed files (that is, those with no valid data beyond EOF).
1334 Portable-format files (Stream_LF, fixed-512) archived with -V should be
1335 extracted properly on a non-VMS system. Files with more complex
1336 structures, such as indexed files and files with embedded byte counts
1337 or other such data may be of limited use on other systems. (UnZip on
1338 non-VMS systems may be able to extract various VMS-format text files,
1339 however.)
1340 .sk
1341 With -VV, Zip processes all allocated blocks for the file (including
1342 those beyond EOF). When extracted on a VMS system, the original file
1343 should be reproduced with as much fidelity as possible, but on a non-VMS
1344 system, most files will be seen as corrupt because of the data from
1345 beyond EOF.
1346 .sk
1347 VMS File Version Numbers
1348 .sk;.literal
1349 -w --VMS-versions
1350 -ww --VMS-dot-versions
1351 .end literal;.br
1352 By default, for compatibility with non-VMS systems, Zip strips VMS file
1353 version numbers from the names stored in an archive. The -w
1354 (--VMS-versions) option causes Zip to retain file version numbers on
1355 names in an archive. Without -w, a version number wildcard (";*") can
1356 cause errors when multiple versions of a single file are treated as
1357 multiple files with the same name.
1358 .sk
1359 For better compatibility with non-VMS systems where semi-colons are less
1360 popular in file names, the -ww (--VMS-dot-versions) option stores the
1361 file version numbers with a dot (".nnn") instead of a semi-colon
1362 (";nnn").
1363 .!------------------------------------------------------------------------------
1364 .indent -4
1365 2 Copyright_and_License
1366 .br
1367 Zip has an option to display its copyright and license.
1368 .sk;.literal
1369 -L --license
1370 .end literal;.br
1371 The license is reproduced below.
1372 .sk.lm +3
1373 This is version 2007-Mar-4 of the Info-ZIP license. The definitive
1374 version of this document should be available at
1375 ftp://ftp.info-zip.org/pub/infozip/license.html indefinitely and a copy
1376 at http://www.info-zip.org/pub/infozip/license.html.
1377 .lm -3;.sk
1378 --------------------------------------------------------
1379 .sk
1380 Copyright (c) 1990-2007 Info-ZIP. All rights reserved.
1381 .sk
1382 For the purposes of this copyright and license, "Info-ZIP" is defined as
1383 the following set of individuals:
1384 .sk;.lm +3
1385 Mark Adler, John Bush, Karl Davis, Harald Denker, Jean-Michel Dubois,
1386 Jean-loup Gailly, Hunter Goatley, Ed Gordon, Ian Gorman, Chris Herborth,
1387 Dirk Haase, Greg Hartwig, Robert Heath, Jonathan Hudson, Paul Kienitz,
1388 David Kirschbaum, Johnny Lee, Onno van der Linden, Igor Mandrichenko,
1389 Steve P. Miller, Sergio Monesi, Keith Owens, George Petrov, Greg Roelofs,
1390 Kai Uwe Rommel, Steve Salisbury, Dave Smith, Steven M. Schweda,
1391 Christian Spieler, Cosmin Truta, Antoine Verheijen, Paul von Behren,
1392 Rich Wales, Mike White.
1393 .lm -3;.sk
1394 This software is provided "as is," without warranty of any kind, express
1395 or implied. In no event shall Info-ZIP or its contributors be held
1396 liable for any direct, indirect, incidental, special or consequential
1397 damages arising out of the use of or inability to use this software.
1398 .sk
1399 Permission is granted to anyone to use this software for any purpose,
1400 including commercial applications, and to alter it and redistribute it
1401 freely, subject to the above disclaimer and the following restrictions:
1402 .sk;.lm +7;.indent -4
1403 1. Redistributions of source code (in whole or in part) must retain
1404 the above copyright notice, definition, disclaimer, and this list
1405 of conditions.
1406 .sk;.indent -4
1407 2. Redistributions in binary form (compiled executables and libraries)
1408 must reproduce the above copyright notice, definition, disclaimer,
1409 and this list of conditions in documentation and/or other materials
1410 provided with the distribution. The sole exception to this condition
1411 is redistribution of a standard UnZipSFX binary (including SFXWiz) as
1412 part of a self-extracting archive; that is permitted without inclusion
1413 of this license, as long as the normal SFX banner has not been removed
1414 from the binary or disabled.
1415 .sk;.indent -4
1416 3. Altered versions -- including, but not limited to, ports to new operating
1417 systems, existing ports with new graphical interfaces, versions with
1418 modified or added functionality, and dynamic, shared, or static library
1419 versions not from Info-ZIP -- must be plainly marked as such and must not
1420 be misrepresented as being the original source or, if binaries,
1421 compiled from the original source. Such altered versions also must not
1422 be misrepresented as being Info-ZIP releases -- including, but not
1423 limited to, labeling of the altered versions with the names "Info-ZIP"
1424 (or any variation thereof, including, but not limited to, different
1425 capitalizations), "Pocket UnZip," "WiZ" or "MacZip" without the
1426 explicit permission of Info-ZIP. Such altered versions are further
1427 prohibited from misrepresentative use of the Zip-Bugs or Info-ZIP
1428 e-mail addresses or the Info-ZIP URL(s), such as to imply Info-ZIP
1429 will provide support for the altered versions.
1430 .sk;.indent -4
1431 4. Info-ZIP retains the right to use the names "Info-ZIP", "Zip",
1432 "UnZip", "UnZipSFX", "WiZ", "Pocket UnZip", "Pocket Zip", and
1433 "MacZip" for its own source and binary releases.
1434 .lm -7;.sk
1435 .!------------------------------------------------------------------------------
1436 .indent -4
1437 2 Acknowledgements
1438 .br
1439 Thanks to R. P. Byrne for his Shrink.Pas program, which
1440 inspired this project, and from which the shrink algorithm
1441 was stolen; to Phil Katz for placing in the public domain
1442 the zip file format, compression format, and .ZIP filename
1443 extension, and for accepting minor changes to the file
1444 format; to Steve Burg for clarifications on the deflate
1445 format; to Haruhiko Okumura and Leonid Broukhis for providing
1446 some useful ideas for the compression algorithm; to
1447 Keith Petersen, Rich Wales, Hunter Goatley and Mark Adler
1448 for providing a mailing list and ftp site for the Info-ZIP
1449 group to use; and most importantly, to the Info-ZIP group
1450 itself (listed in the file infozip.who) without whose
1451 tireless testing and bug-fixing efforts a portable zip
1452 would not have been possible. Finally we should thank
1453 (blame) the first Info-ZIP moderator, David Kirschbaum,
1454 for getting us into this mess in the first place.
1455 .!------------------------------------------------------------------------------
1456 .indent -4
1457 2 Bugs
1458 .br
1459 All bug reports, patches, or suggestions should go to zip-bugs via the
1460 web site contact form at http://www.Info-ZIP.org. Patches should be
1461 sent as unified or context diffs only (diff -u or diff -c).
1462 .sk
1463 Any bug report should include the Zip version, any special compilation
1464 options (see "zip -v" report), the host system type and operating system
1465 version, and any other relevant information (compiler version, lunar
1466 phase, ...).
1467 .!------------------------------------------------------------------------------