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 | cooked | verbose |
104 {comment, string()} |
105 {cwd, file:filename()} |
106 {compress, extension_spec()} |
107 {uncompress, 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
138 behavior 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
273 extracts 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
298 Binary is a binary containing the extracted data of file
299 Filename 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 Creates a zip archive containing the files specified in
331 FileList.
332 create/2 and create/3 are provided as synonyms to resemble mod‐
334 ule erl_tar.
335 FileList is a list of files, with paths relative to the current
337 directory, which are stored with this path in the archive. Files
338 can also be specified with data in binaries to create an archive
339 directly from data.
340 Files are compressed using the DEFLATE compression, as described
342 in the "Appnote.txt" file. However, files are stored without
343 compression if they are already compressed. zip/2 and zip/3
344 check the file extension to determine if the file is to be
345 stored without compression. Files with the following extensions
346 are not compressed: .Z, .zip, .zoo, .arc, .lzh, .arj.
347 It is possible to override the default behavior and control what
349 types of files that are to be compressed by using options {com‐
350 press, What} and {uncompress, What}. It is also possible to use
351 many compress and uncompress options.
352 To trigger file compression, its extension must match with the
354 compress condition and must not match the uncompress condition.
355 For example, if compress is set to ["gif", "jpg"] and uncompress
356 is set to ["jpg"], only files with extension "gif" are com‐
357 pressed.
358 Options:
360 cooked:
362 By default, this function opens the zip file in mode raw,
363 which is faster but does not allow a remote (Erlang) file
364 server to be used. Adding cooked to the mode list overrides
365 the default and opens the zip file without the raw option.
366 The same applies for the files added.
367 verbose:
369 Prints an informational message about each added file.
370 memory:
372 The output is not to a file, but instead as a tuple {File‐
373 Name, binary()}. The binary is a full zip archive with
374 header and can be extracted with, for example, unzip/2.
375 {comment, Comment}:
377 Adds a comment to the zip archive.
378 {cwd, CWD}:
380 Uses the specified directory as current work directory
381 (cwd). This is prepended to filenames when adding them,
382 although not in the zip archive (acting like file:set_cwd/1
383 in Kernel, but without changing the global cwd property.).
384 {compress, What}:
386 Controls what types of files to be compressed. Defaults to
387 all. The following values of What are allowed:
388 all:
390 All files are compressed (as long as they pass the uncom‐
391 press condition).
392 [Extension]:
394 Only files with exactly these extensions are compressed.
395 {add,[Extension]}:
397 Adds these extensions to the list of compress extensions.
398 {del,[Extension]}:
400 Deletes these extensions from the list of compress exten‐
401 sions.
402 {uncompress, What}:
404 Controls what types of files to be uncompressed. Defaults to
405 [".Z", ".zip", ".zoo", ".arc", ".lzh", ".arj"]. The follow‐
406 ing values of What are allowed:
407 all:
409 No files are compressed.
410 [Extension]:
412 Files with these extensions are uncompressed.
413 {add,[Extension]}:
415 Adds these extensions to the list of uncompress exten‐
416 sions.
417 {del,[Extension]}:
419 Deletes these extensions from the list of uncompress
420 extensions.
421 zip_close(ZipHandle) -> ok | {error, einval}
423 Types:
425 ZipHandle = handle()
427 Closes a zip archive, previously opened with zip_open/1,2. All
429 resources are closed, and the handle is not to be used after
430 closing.
431 zip_get(ZipHandle) -> {ok, [Result]} | {error, Reason}
433 zip_get(FileName, ZipHandle) -> {ok, Result} | {error, Reason}
435 Types:
437 FileName = file:name()
439 ZipHandle = handle()
440 Result = file:name() | {file:name(), binary()}
441 Reason = term()
442 Extracts one or all files from an open archive.
444 The files are unzipped to memory or to file, depending on the
446 options specified to function zip_open/1,2 when opening the ar‐
447 chive.
448 zip_list_dir(ZipHandle) -> {ok, Result} | {error, Reason}
450 Types:
452 Result = [zip_comment() | zip_file()]
454 ZipHandle = handle()
455 Reason = term()
456 Returns the file list of an open zip archive. The first returned
458 element is the zip archive comment.
459 zip_open(Archive) -> {ok, ZipHandle} | {error, Reason}
461 zip_open(Archive, Options) -> {ok, ZipHandle} | {error, Reason}
463 Types:
465 Archive = file:name() | binary()
467 ZipHandle = handle()
468 Options = [Option]
469 Option = cooked | memory | {cwd, CWD :: file:filename()}
470 Reason = term()
471 Opens a zip archive, and reads and saves its directory. This
473 means that later reading files from the archive is faster than
474 unzipping files one at a time with unzip/1,2.
475 The archive must be closed with zip_close/1.
477 The ZipHandle is closed if the process that originally opened
479 the archive dies.
480Ericsson AB stdlib 3.12.1 zip(3)