1zip(3) Erlang Module Definition zip(3)
2
6 zip - Utility for reading and creating 'zip' archives.
7
10 This module archives and extracts files to and from a zip archive. The
11 zip format is specified by the "ZIP Appnote.txt" file, available on the
12 PKWARE web site www.pkware.com.
13 The zip module supports zip archive versions up to 6.1. However, pass‐
15 word-protection and Zip64 are not supported.
16 By convention, the name of a zip file is to end with .zip. To abide to
18 the convention, add .zip to the filename.
19 * To create zip archives, use function zip/2 or zip/3. They are also
21 available as create/2,3, to resemble the erl_tar module.
22 * To extract files from a zip archive, use function unzip/1 or
24 unzip/2. They are also available as extract/1,2, to resemble the
25 erl_tar module.
26 * To fold a function over all files in a zip archive, use function
28 foldl/3.
29 * To return a list of the files in a zip archive, use function
31 list_dir/1 or list_dir/2. They are also available as table/1,2, to
32 resemble the erl_tar module.
33 * To print a list of files to the Erlang shell, use function t/1 or
35 tt/1.
36 * Sometimes it is desirable to open a zip archive, and to unzip files
38 from it file by file, without having to reopen the archive. This
39 can be done by functions zip_open/1,2, zip_get/1,2, zip_list_dir/1,
40 and zip_close/1.
41
43 * Zip64 archives are not supported.
44 * Password-protected and encrypted archives are not supported.
46 * Only the DEFLATE (zlib-compression) and the STORE (uncompressed
48 data) zip methods are supported.
49 * The archive size is limited to 2 GB (32 bits).
51 * Comments for individual files are not supported when creating zip
53 archives. The zip archive comment for the whole zip archive is sup‐
54 ported.
55 * Changing a zip archive is not supported. To add or remove a file
57 from an archive, the whole archive must be recreated.
58
60 zip_comment() = #zip_comment{comment = string()}
61 The record zip_comment only contains the archive comment for a
63 zip archive.
64 zip_file() =
66 #zip_file{name = string(),
67 info = file:file_info(),
68 comment = string(),
69 offset = integer() >= 0,
70 comp_size = integer() >= 0}
71 The record zip_file contains the following fields:
73 name:
75 The filename
76 info:
78 File information as in file:read_file_info/1 in Kernel
79 comment:
81 The comment for the file in the zip archive
82 offset:
84 The file offset in the zip archive (used internally)
85 comp_size:
87 The size of the compressed file (the size of the uncom‐
88 pressed file is found in info)
89 filename() = file:filename()
91 The name of a zip file.
93 extension() = string()
95 extension_spec() =
97 all |
98 [extension()] |
99 {add, [extension()]} |
100 {del, [extension()]}
101 create_option() =
103 memory |
104 cooked |
105 verbose |
106 {comment, string()} |
107 {cwd, file:filename()} |
108 {compress, extension_spec()} |
109 {uncompress, extension_spec()}
110 These options are described in create/3.
112 handle()
114 As returned by zip_open/2.
116
118 foldl(Fun, Acc0, Archive) -> {ok, Acc1} | {error, Reason}
119 Types:
121 Fun = fun((FileInArchive, GetInfo, GetBin, AccIn) -> AccOut)
123 FileInArchive = file:name()
124 GetInfo = fun(() -> file:file_info())
125 GetBin = fun(() -> binary())
126 Acc0 = Acc1 = AccIn = AccOut = term()
127 Archive = file:name() | {file:name(), binary()}
128 Reason = term()
129 Calls Fun(FileInArchive, GetInfo, GetBin, AccIn) on successive
131 files in the Archive, starting with AccIn == Acc0.
132 FileInArchive is the name that the file has in the archive.
134 GetInfo is a fun that returns information about the file.
136 GetBin returns the file contents.
138 Both GetInfo and GetBin must be called within the Fun. Their
140 behavior is undefined if they are called outside the context of
141 Fun.
142 The Fun must return a new accumulator, which is passed to the
144 next call. foldl/3 returns the final accumulator value. Acc0 is
145 returned if the archive is empty. It is not necessary to iterate
146 over all files in the archive. The iteration can be ended prema‐
147 turely in a controlled manner by throwing an exception.
148 Example:
150 > Name = "dummy.zip".
152 "dummy.zip"
153 > {ok, {Name, Bin}} = zip:create(Name, [{"foo", <<"FOO">>}, {"bar", <<"BAR">>}], [memory]).
154 {ok,{"dummy.zip",
155 <<80,75,3,4,20,0,0,0,0,0,74,152,97,60,171,39,212,26,3,0,
156 0,0,3,0,0,...>>}}
157 > {ok, FileSpec} = zip:foldl(fun(N, I, B, Acc) -> [{N, B(), I()} | Acc] end, [], {Name, Bin}).
158 {ok,[{"bar",<<"BAR">>,
159 {file_info,3,regular,read_write,
160 {{2010,3,1},{19,2,10}},
161 {{2010,3,1},{19,2,10}},
162 {{2010,3,1},{19,2,10}},
163 54,1,0,0,0,0,0}},
164 {"foo",<<"FOO">>,
165 {file_info,3,regular,read_write,
166 {{2010,3,1},{19,2,10}},
167 {{2010,3,1},{19,2,10}},
168 {{2010,3,1},{19,2,10}},
169 54,1,0,0,0,0,0}}]}
170 > {ok, {Name, Bin}} = zip:create(Name, lists:reverse(FileSpec), [memory]).
171 {ok,{"dummy.zip",
172 <<80,75,3,4,20,0,0,0,0,0,74,152,97,60,171,39,212,26,3,0,
173 0,0,3,0,0,...>>}}
174 > catch zip:foldl(fun("foo", _, B, _) -> throw(B()); (_,_,_,Acc) -> Acc end, [], {Name, Bin}).
175 <<"FOO">>
176 list_dir(Archive) -> RetValue
179 list_dir(Archive, Options) -> RetValue
181 table(Archive) -> RetValue
183 table(Archive, Options) -> RetValue
185 Types:
187 Archive = file:name() | binary()
189 RetValue = {ok, CommentAndFiles} | {error, Reason :: term()}
190 CommentAndFiles = [zip_comment() | zip_file()]
191 Options = [Option]
192 Option = cooked
193 list_dir/1 retrieves all filenames in the zip archive Archive.
195 list_dir/2 provides options.
197 table/1 and table/2 are provided as synonyms to resemble the
199 erl_tar module.
200 The result value is the tuple {ok, List}, where List contains
202 the zip archive comment as the first element.
203 One option is available:
205 cooked:
207 By default, this function opens the zip file in raw mode,
208 which is faster but does not allow a remote (Erlang) file
209 server to be used. Adding cooked to the mode list overrides
210 the default and opens the zip file without option raw.
211 t(Archive) -> ok
213 Types:
215 Archive = file:name() | binary() | ZipHandle
217 ZipHandle = handle()
218 Prints all filenames in the zip archive Archive to the Erlang
220 shell. (Similar to tar t.)
221 tt(Archive) -> ok
223 Types:
225 Archive = file:name() | binary() | ZipHandle
227 ZipHandle = handle()
228 Prints filenames and information about all files in the zip ar‐
230 chive Archive to the Erlang shell. (Similar to tar tv.)
231 unzip(Archive) -> RetValue
233 unzip(Archive, Options) -> RetValue
235 extract(Archive) -> RetValue
237 extract(Archive, Options) -> RetValue
239 Types:
241 Archive = file:name() | binary()
243 Options = [Option]
244 Option =
245 {file_list, FileList} |
246 keep_old_files |
247 verbose |
248 memory |
249 {file_filter, FileFilter} |
250 {cwd, CWD}
251 FileList = [file:name()]
252 FileBinList = [{file:name(), binary()}]
253 FileFilter = fun((ZipFile) -> boolean())
254 CWD = file:filename()
255 ZipFile = zip_file()
256 RetValue =
257 {ok, FileList} |
258 {ok, FileBinList} |
259 {error, Reason :: term()} |
260 {error, {Name :: file:name(), Reason :: term()}}
261 unzip/1 extracts all files from a zip archive.
263 unzip/2 provides options to extract some files, and more.
265 extract/1 and extract/2 are provided as synonyms to resemble
267 module erl_tar.
268 If argument Archive is specified as a binary, the contents of
270 the binary is assumed to be a zip archive, otherwise a filename.
271 Options:
273 {file_list, FileList}:
275 By default, all files are extracted from the zip archive.
276 With option {file_list, FileList}, function unzip/2 only
277 extracts the files whose names are included in FileList. The
278 full paths, including the names of all subdirectories within
279 the zip archive, must be specified.
280 cooked:
282 By default, this function opens the zip file in raw mode,
283 which is faster but does not allow a remote (Erlang) file
284 server to be used. Adding cooked to the mode list overrides
285 the default and opens the zip file without option raw. The
286 same applies for the files extracted.
287 keep_old_files:
289 By default, all files with the same name as files in the zip
290 archive are overwritten. With option keep_old_files set,
291 function unzip/2 does not overwrite existing files. Notice
292 that even with option memory specified, which means that no
293 files are overwritten, existing files are excluded from the
294 result.
295 verbose:
297 Prints an informational message for each extracted file.
298 memory:
300 Instead of extracting to the current directory, the result
301 is given as a list of tuples {Filename, Binary}, where
302 Binary is a binary containing the extracted data of file
303 Filename in the zip archive.
304 {cwd, CWD}:
306 Uses the specified directory as current directory. It is
307 prepended to filenames when extracting them from the zip ar‐
308 chive. (Acting like file:set_cwd/1 in Kernel, but without
309 changing the global cwd property.)
310 zip(Name, FileList) -> RetValue
312 zip(Name, FileList, Options) -> RetValue
314 create(Name, FileList) -> RetValue
316 create(Name, FileList, Options) -> RetValue
318 Types:
320 Name = file:name()
322 FileList = [FileSpec]
323 FileSpec =
324 file:name() |
325 {file:name(), binary()} |
326 {file:name(), binary(), file:file_info()}
327 Options = [Option]
328 Option = create_option()
329 RetValue =
330 {ok, FileName :: filename()} |
331 {ok, {FileName :: filename(), binary()}} |
332 {error, Reason :: term()}
333 Creates a zip archive containing the files specified in
335 FileList.
336 create/2 and create/3 are provided as synonyms to resemble mod‐
338 ule erl_tar.
339 FileList is a list of files, with paths relative to the current
341 directory, which are stored with this path in the archive. Files
342 can also be specified with data in binaries to create an archive
343 directly from data.
344 Files are compressed using the DEFLATE compression, as described
346 in the "Appnote.txt" file. However, files are stored without
347 compression if they are already compressed. zip/2 and zip/3
348 check the file extension to determine if the file is to be
349 stored without compression. Files with the following extensions
350 are not compressed: .Z, .zip, .zoo, .arc, .lzh, .arj.
351 It is possible to override the default behavior and control what
353 types of files that are to be compressed by using options {com‐
354 press, What} and {uncompress, What}. It is also possible to use
355 many compress and uncompress options.
356 To trigger file compression, its extension must match with the
358 compress condition and must not match the uncompress condition.
359 For example, if compress is set to ["gif", "jpg"] and uncompress
360 is set to ["jpg"], only files with extension "gif" are com‐
361 pressed.
362 Options:
364 cooked:
366 By default, this function opens the zip file in mode raw,
367 which is faster but does not allow a remote (Erlang) file
368 server to be used. Adding cooked to the mode list overrides
369 the default and opens the zip file without the raw option.
370 The same applies for the files added.
371 verbose:
373 Prints an informational message about each added file.
374 memory:
376 The output is not to a file, but instead as a tuple {File‐
377 Name, binary()}. The binary is a full zip archive with
378 header and can be extracted with, for example, unzip/2.
379 {comment, Comment}:
381 Adds a comment to the zip archive.
382 {cwd, CWD}:
384 Uses the specified directory as current work directory
385 (cwd). This is prepended to filenames when adding them,
386 although not in the zip archive (acting like file:set_cwd/1
387 in Kernel, but without changing the global cwd property.).
388 {compress, What}:
390 Controls what types of files to be compressed. Defaults to
391 all. The following values of What are allowed:
392 all:
394 All files are compressed (as long as they pass the uncom‐
395 press condition).
396 [Extension]:
398 Only files with exactly these extensions are compressed.
399 {add,[Extension]}:
401 Adds these extensions to the list of compress extensions.
402 {del,[Extension]}:
404 Deletes these extensions from the list of compress exten‐
405 sions.
406 {uncompress, What}:
408 Controls what types of files to be uncompressed. Defaults to
409 [".Z", ".zip", ".zoo", ".arc", ".lzh", ".arj"]. The follow‐
410 ing values of What are allowed:
411 all:
413 No files are compressed.
414 [Extension]:
416 Files with these extensions are uncompressed.
417 {add,[Extension]}:
419 Adds these extensions to the list of uncompress exten‐
420 sions.
421 {del,[Extension]}:
423 Deletes these extensions from the list of uncompress
424 extensions.
425 zip_close(ZipHandle) -> ok | {error, einval}
427 Types:
429 ZipHandle = handle()
431 Closes a zip archive, previously opened with zip_open/1,2. All
433 resources are closed, and the handle is not to be used after
434 closing.
435 zip_get(ZipHandle) -> {ok, [Result]} | {error, Reason}
437 zip_get(FileName, ZipHandle) -> {ok, Result} | {error, Reason}
439 Types:
441 FileName = file:name()
443 ZipHandle = handle()
444 Result = file:name() | {file:name(), binary()}
445 Reason = term()
446 Extracts one or all files from an open archive.
448 The files are unzipped to memory or to file, depending on the
450 options specified to function zip_open/1,2 when opening the ar‐
451 chive.
452 zip_list_dir(ZipHandle) -> {ok, Result} | {error, Reason}
454 Types:
456 Result = [zip_comment() | zip_file()]
458 ZipHandle = handle()
459 Reason = term()
460 Returns the file list of an open zip archive. The first returned
462 element is the zip archive comment.
463 zip_open(Archive) -> {ok, ZipHandle} | {error, Reason}
465 zip_open(Archive, Options) -> {ok, ZipHandle} | {error, Reason}
467 Types:
469 Archive = file:name() | binary()
471 ZipHandle = handle()
472 Options = [Option]
473 Option = cooked | memory | {cwd, CWD :: file:filename()}
474 Reason = term()
475 Opens a zip archive, and reads and saves its directory. This
477 means that later reading files from the archive is faster than
478 unzipping files one at a time with unzip/1,2.
479 The archive must be closed with zip_close/1.
481 The ZipHandle is closed if the process that originally opened
483 the archive dies.
484Ericsson AB stdlib 3.4.5.1 zip(3)