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 un‐
24 zip/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 :: extension()] |
99 {add, [Extension :: extension()]} |
100 {del, [Extension :: extension()]}
101 create_option() =
103 memory | cooked | verbose |
104 {comment, Comment :: string()} |
105 {cwd, CWD :: file:filename()} |
106 {compress, What :: extension_spec()} |
107 {uncompress, What :: extension_spec()}
108 These options are described in create/3.
110 handle()
112 As returned by zip_open/2.
114
116 foldl(Fun, Acc0, Archive) -> {ok, Acc1} | {error, Reason}
117 Types:
119 Fun = fun((FileInArchive, GetInfo, GetBin, AccIn) -> AccOut)
121 FileInArchive = file:name()
122 GetInfo = fun(() -> file:file_info())
123 GetBin = fun(() -> binary())
124 Acc0 = Acc1 = AccIn = AccOut = term()
125 Archive = file:name() | {file:name(), binary()}
126 Reason = term()
127 Calls Fun(FileInArchive, GetInfo, GetBin, AccIn) on successive
129 files in the Archive, starting with AccIn == Acc0.
130 FileInArchive is the name that the file has in the archive.
132 GetInfo is a fun that returns information about the file.
134 GetBin returns the file contents.
136 Both GetInfo and GetBin must be called within the Fun. Their be‐
138 havior is undefined if they are called outside the context of
139 Fun.
140 The Fun must return a new accumulator, which is passed to the
142 next call. foldl/3 returns the final accumulator value. Acc0 is
143 returned if the archive is empty. It is not necessary to iterate
144 over all files in the archive. The iteration can be ended prema‐
145 turely in a controlled manner by throwing an exception.
146 Example:
148 > Name = "dummy.zip".
150 "dummy.zip"
151 > {ok, {Name, Bin}} = zip:create(Name, [{"foo", <<"FOO">>}, {"bar", <<"BAR">>}], [memory]).
152 {ok,{"dummy.zip",
153 <<80,75,3,4,20,0,0,0,0,0,74,152,97,60,171,39,212,26,3,0,
154 0,0,3,0,0,...>>}}
155 > {ok, FileSpec} = zip:foldl(fun(N, I, B, Acc) -> [{N, B(), I()} | Acc] end, [], {Name, Bin}).
156 {ok,[{"bar",<<"BAR">>,
157 {file_info,3,regular,read_write,
158 {{2010,3,1},{19,2,10}},
159 {{2010,3,1},{19,2,10}},
160 {{2010,3,1},{19,2,10}},
161 54,1,0,0,0,0,0}},
162 {"foo",<<"FOO">>,
163 {file_info,3,regular,read_write,
164 {{2010,3,1},{19,2,10}},
165 {{2010,3,1},{19,2,10}},
166 {{2010,3,1},{19,2,10}},
167 54,1,0,0,0,0,0}}]}
168 > {ok, {Name, Bin}} = zip:create(Name, lists:reverse(FileSpec), [memory]).
169 {ok,{"dummy.zip",
170 <<80,75,3,4,20,0,0,0,0,0,74,152,97,60,171,39,212,26,3,0,
171 0,0,3,0,0,...>>}}
172 > catch zip:foldl(fun("foo", _, B, _) -> throw(B()); (_,_,_,Acc) -> Acc end, [], {Name, Bin}).
173 <<"FOO">>
174 list_dir(Archive) -> RetValue
177 list_dir(Archive, Options) -> RetValue
179 table(Archive) -> RetValue
181 table(Archive, Options) -> RetValue
183 Types:
185 Archive = file:name() | binary()
187 RetValue = {ok, CommentAndFiles} | {error, Reason :: term()}
188 CommentAndFiles = [zip_comment() | zip_file()]
189 Options = [Option]
190 Option = cooked
191 list_dir/1 retrieves all filenames in the zip archive Archive.
193 list_dir/2 provides options.
195 table/1 and table/2 are provided as synonyms to resemble the
197 erl_tar module.
198 The result value is the tuple {ok, List}, where List contains
200 the zip archive comment as the first element.
201 One option is available:
203 cooked:
205 By default, this function opens the zip file in raw mode,
206 which is faster but does not allow a remote (Erlang) file
207 server to be used. Adding cooked to the mode list overrides
208 the default and opens the zip file without option raw.
209 t(Archive) -> ok
211 Types:
213 Archive = file:name() | binary() | ZipHandle
215 ZipHandle = handle()
216 Prints all filenames in the zip archive Archive to the Erlang
218 shell. (Similar to tar t.)
219 tt(Archive) -> ok
221 Types:
223 Archive = file:name() | binary() | ZipHandle
225 ZipHandle = handle()
226 Prints filenames and information about all files in the zip ar‐
228 chive Archive to the Erlang shell. (Similar to tar tv.)
229 unzip(Archive) -> RetValue
231 unzip(Archive, Options) -> RetValue
233 extract(Archive) -> RetValue
235 extract(Archive, Options) -> RetValue
237 Types:
239 Archive = file:name() | binary()
241 Options = [Option]
242 Option =
243 {file_list, FileList} |
244 keep_old_files | verbose | memory |
245 {file_filter, FileFilter} |
246 {cwd, CWD}
247 FileList = [file:name()]
248 FileBinList = [{file:name(), binary()}]
249 FileFilter = fun((ZipFile) -> boolean())
250 CWD = file:filename()
251 ZipFile = zip_file()
252 RetValue =
253 {ok, FileList} |
254 {ok, FileBinList} |
255 {error, Reason :: term()} |
256 {error, {Name :: file:name(), Reason :: term()}}
257 unzip/1 extracts all files from a zip archive.
259 unzip/2 provides options to extract some files, and more.
261 extract/1 and extract/2 are provided as synonyms to resemble
263 module erl_tar.
264 If argument Archive is specified as a binary, the contents of
266 the binary is assumed to be a zip archive, otherwise a filename.
267 Options:
269 {file_list, FileList}:
271 By default, all files are extracted from the zip archive.
272 With option {file_list, FileList}, function unzip/2 only ex‐
273 tracts the files whose names are included in FileList. The
274 full paths, including the names of all subdirectories within
275 the zip archive, must be specified.
276 cooked:
278 By default, this function opens the zip file in raw mode,
279 which is faster but does not allow a remote (Erlang) file
280 server to be used. Adding cooked to the mode list overrides
281 the default and opens the zip file without option raw. The
282 same applies for the files extracted.
283 keep_old_files:
285 By default, all files with the same name as files in the zip
286 archive are overwritten. With option keep_old_files set,
287 function unzip/2 does not overwrite existing files. Notice
288 that even with option memory specified, which means that no
289 files are overwritten, existing files are excluded from the
290 result.
291 verbose:
293 Prints an informational message for each extracted file.
294 memory:
296 Instead of extracting to the current directory, the result
297 is given as a list of tuples {Filename, Binary}, where Bi‐
298 nary is a binary containing the extracted data of file File‐
299 name in the zip archive.
300 {cwd, CWD}:
302 Uses the specified directory as current directory. It is
303 prepended to filenames when extracting them from the zip ar‐
304 chive. (Acting like file:set_cwd/1 in Kernel, but without
305 changing the global cwd property.)
306 zip(Name, FileList) -> RetValue
308 zip(Name, FileList, Options) -> RetValue
310 create(Name, FileList) -> RetValue
312 create(Name, FileList, Options) -> RetValue
314 Types:
316 Name = file:name()
318 FileList = [FileSpec]
319 FileSpec =
320 file:name() |
321 {file:name(), binary()} |
322 {file:name(), binary(), file:file_info()}
323 Options = [Option]
324 Option = create_option()
325 RetValue =
326 {ok, FileName :: filename()} |
327 {ok, {FileName :: filename(), binary()}} |
328 {error, Reason :: term()}
329 create_option() =
330 memory | cooked | verbose |
331 {comment, Comment :: string()} |
332 {cwd, CWD :: file:filename()} |
333 {compress, What :: extension_spec()} |
334 {uncompress, What :: extension_spec()}
335 extension_spec() =
336 all |
337 [Extension :: extension()] |
338 {add, [Extension :: extension()]} |
339 {del, [Extension :: extension()]}
340 Creates a zip archive containing the files specified in
342 FileList.
343 create/2 and create/3 are provided as synonyms to resemble mod‐
345 ule erl_tar.
346 FileList is a list of files, with paths relative to the current
348 directory, which are stored with this path in the archive. Files
349 can also be specified with data in binaries to create an archive
350 directly from data.
351 Files are compressed using the DEFLATE compression, as described
353 in the "Appnote.txt" file. However, files are stored without
354 compression if they are already compressed. zip/2 and zip/3
355 check the file extension to determine if the file is to be
356 stored without compression. Files with the following extensions
357 are not compressed: .Z, .zip, .zoo, .arc, .lzh, .arj.
358 It is possible to override the default behavior and control what
360 types of files that are to be compressed by using options {com‐
361 press, What} and {uncompress, What}. It is also possible to use
362 many compress and uncompress options.
363 To trigger file compression, its extension must match with the
365 compress condition and must not match the uncompress condition.
366 For example, if compress is set to ["gif", "jpg"] and uncompress
367 is set to ["jpg"], only files with extension "gif" are com‐
368 pressed.
369 Options:
371 cooked:
373 By default, this function opens the zip file in mode raw,
374 which is faster but does not allow a remote (Erlang) file
375 server to be used. Adding cooked to the mode list overrides
376 the default and opens the zip file without the raw option.
377 The same applies for the files added.
378 verbose:
380 Prints an informational message about each added file.
381 memory:
383 The output is not to a file, but instead as a tuple {File‐
384 Name, binary()}. The binary is a full zip archive with
385 header and can be extracted with, for example, unzip/2.
386 {comment, Comment}:
388 Adds a comment to the zip archive.
389 {cwd, CWD}:
391 Uses the specified directory as current work directory
392 (cwd). This is prepended to filenames when adding them, al‐
393 though not in the zip archive (acting like file:set_cwd/1 in
394 Kernel, but without changing the global cwd property.).
395 {compress, What}:
397 Controls what types of files to be compressed. Defaults to
398 all. The following values of What are allowed:
399 all:
401 All files are compressed (as long as they pass the uncom‐
402 press condition).
403 [Extension]:
405 Only files with exactly these extensions are compressed.
406 {add,[Extension]}:
408 Adds these extensions to the list of compress extensions.
409 {del,[Extension]}:
411 Deletes these extensions from the list of compress exten‐
412 sions.
413 {uncompress, What}:
415 Controls what types of files to be uncompressed. Defaults to
416 [".Z", ".zip", ".zoo", ".arc", ".lzh", ".arj"]. The follow‐
417 ing values of What are allowed:
418 all:
420 No files are compressed.
421 [Extension]:
423 Files with these extensions are uncompressed.
424 {add,[Extension]}:
426 Adds these extensions to the list of uncompress exten‐
427 sions.
428 {del,[Extension]}:
430 Deletes these extensions from the list of uncompress ex‐
431 tensions.
432 zip_close(ZipHandle) -> ok | {error, einval}
434 Types:
436 ZipHandle = handle()
438 Closes a zip archive, previously opened with zip_open/1,2. All
440 resources are closed, and the handle is not to be used after
441 closing.
442 zip_get(ZipHandle) -> {ok, [Result]} | {error, Reason}
444 zip_get(FileName, ZipHandle) -> {ok, Result} | {error, Reason}
446 Types:
448 FileName = file:name()
450 ZipHandle = handle()
451 Result = file:name() | {file:name(), binary()}
452 Reason = term()
453 Extracts one or all files from an open archive.
455 The files are unzipped to memory or to file, depending on the
457 options specified to function zip_open/1,2 when opening the ar‐
458 chive.
459 zip_list_dir(ZipHandle) -> {ok, Result} | {error, Reason}
461 Types:
463 Result = [zip_comment() | zip_file()]
465 ZipHandle = handle()
466 Reason = term()
467 Returns the file list of an open zip archive. The first returned
469 element is the zip archive comment.
470 zip_open(Archive) -> {ok, ZipHandle} | {error, Reason}
472 zip_open(Archive, Options) -> {ok, ZipHandle} | {error, Reason}
474 Types:
476 Archive = file:name() | binary()
478 ZipHandle = handle()
479 Options = [Option]
480 Option = cooked | memory | {cwd, CWD :: file:filename()}
481 Reason = term()
482 Opens a zip archive, and reads and saves its directory. This
484 means that later reading files from the archive is faster than
485 unzipping files one at a time with unzip/1,2.
486 The archive must be closed with zip_close/1.
488 The ZipHandle is closed if the process that originally opened
490 the archive dies.
491Ericsson AB stdlib 3.16.1 zip(3)