1zip(3)                     Erlang Module Definition                     zip(3)
2
3
4

NAME

6       zip - Utility for reading and creating 'zip' archives.
7
8

DESCRIPTION

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
14       The  zip module supports zip archive versions up to 6.1. However, pass‐
15       word-protection and Zip64 are not supported.
16
17       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
20         * 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
23         * 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
27         * To fold a function over all files in a zip  archive,  use  function
28           foldl/3.
29
30         * 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
34         * To  print  a list of files to the Erlang shell, use function t/1 or
35           tt/1.
36
37         * 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

LIMITATIONS

43         * Zip64 archives are not supported.
44
45         * Password-protected and encrypted archives are not supported.
46
47         * Only  the  DEFLATE  (zlib-compression)  and the STORE (uncompressed
48           data) zip methods are supported.
49
50         * The archive size is limited to 2 GB (32 bits).
51
52         * 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
56         * Changing a zip archive is not supported. To add or  remove  a  file
57           from an archive, the whole archive must be recreated.
58

DATA TYPES

60       zip_comment() = #zip_comment{comment = string()}
61
62              The  record  zip_comment only contains the archive comment for a
63              zip archive.
64
65       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
72              The record zip_file contains the following fields:
73
74                name:
75                  The filename
76
77                info:
78                  File information as in file:read_file_info/1 in Kernel
79
80                comment:
81                  The comment for the file in the zip archive
82
83                offset:
84                  The file offset in the zip archive (used internally)
85
86                comp_size:
87                  The size of the compressed file  (the  size  of  the  uncom‐
88                  pressed file is found in info)
89
90       filename() = file:filename()
91
92              The name of a zip file.
93
94       extension() = string()
95
96       extension_spec() =
97           all |
98           [Extension :: extension()] |
99           {add, [Extension :: extension()]} |
100           {del, [Extension :: extension()]}
101
102       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
109              These options are described in create/3.
110
111       handle()
112
113              As returned by zip_open/2.
114

EXPORTS

116       foldl(Fun, Acc0, Archive) -> {ok, Acc1} | {error, Reason}
117
118              Types:
119
120                 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
128              Calls  Fun(FileInArchive,  GetInfo, GetBin, AccIn) on successive
129              files in the Archive, starting with AccIn == Acc0.
130
131              FileInArchive is the name that the file has in the archive.
132
133              GetInfo is a fun that returns information about the file.
134
135              GetBin returns the file contents.
136
137              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
141              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
147              Example:
148
149              > 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
175
176       list_dir(Archive) -> RetValue
177
178       list_dir(Archive, Options) -> RetValue
179
180       table(Archive) -> RetValue
181
182       table(Archive, Options) -> RetValue
183
184              Types:
185
186                 Archive = file:name() | binary()
187                 RetValue = {ok, CommentAndFiles} | {error, Reason :: term()}
188                 CommentAndFiles = [zip_comment() | zip_file()]
189                 Options = [Option]
190                 Option = cooked
191
192              list_dir/1 retrieves all filenames in the zip archive Archive.
193
194              list_dir/2 provides options.
195
196              table/1 and table/2 are provided as  synonyms  to  resemble  the
197              erl_tar module.
198
199              The  result  value  is the tuple {ok, List}, where List contains
200              the zip archive comment as the first element.
201
202              One option is available:
203
204                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
210       t(Archive) -> ok
211
212              Types:
213
214                 Archive = file:name() | binary() | ZipHandle
215                 ZipHandle = handle()
216
217              Prints  all  filenames  in the zip archive Archive to the Erlang
218              shell. (Similar to tar t.)
219
220       tt(Archive) -> ok
221
222              Types:
223
224                 Archive = file:name() | binary() | ZipHandle
225                 ZipHandle = handle()
226
227              Prints filenames and information about all files in the zip  ar‐
228              chive Archive to the Erlang shell. (Similar to tar tv.)
229
230       unzip(Archive) -> RetValue
231
232       unzip(Archive, Options) -> RetValue
233
234       extract(Archive) -> RetValue
235
236       extract(Archive, Options) -> RetValue
237
238              Types:
239
240                 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
258              unzip/1 extracts all files from a zip archive.
259
260              unzip/2 provides options to extract some files, and more.
261
262              extract/1  and  extract/2  are  provided as synonyms to resemble
263              module erl_tar.
264
265              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
268              Options:
269
270                {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
277                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
284                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
292                verbose:
293                  Prints an informational message for each extracted file.
294
295                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
301                {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
307       zip(Name, FileList) -> RetValue
308
309       zip(Name, FileList, Options) -> RetValue
310
311       create(Name, FileList) -> RetValue
312
313       create(Name, FileList, Options) -> RetValue
314
315              Types:
316
317                 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
341              Creates  a  zip  archive  containing  the  files  specified   in
342              FileList.
343
344              create/2  and create/3 are provided as synonyms to resemble mod‐
345              ule erl_tar.
346
347              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
352              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
359              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
364              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
370              Options:
371
372                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
379                verbose:
380                  Prints an informational message about each added file.
381
382                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
387                {comment, Comment}:
388                  Adds a comment to the zip archive.
389
390                {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
396                {compress, What}:
397                  Controls what types of files to be compressed.  Defaults  to
398                  all. The following values of What are allowed:
399
400                  all:
401                    All  files are compressed (as long as they pass the uncom‐
402                    press condition).
403
404                  [Extension]:
405                    Only files with exactly these extensions are compressed.
406
407                  {add,[Extension]}:
408                    Adds these extensions to the list of compress extensions.
409
410                  {del,[Extension]}:
411                    Deletes these extensions from the list of compress  exten‐
412                    sions.
413
414                {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
419                  all:
420                    No files are compressed.
421
422                  [Extension]:
423                    Files with these extensions are uncompressed.
424
425                  {add,[Extension]}:
426                    Adds  these  extensions  to  the list of uncompress exten‐
427                    sions.
428
429                  {del,[Extension]}:
430                    Deletes these extensions from the list of  uncompress  ex‐
431                    tensions.
432
433       zip_close(ZipHandle) -> ok | {error, einval}
434
435              Types:
436
437                 ZipHandle = handle()
438
439              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
443       zip_get(ZipHandle) -> {ok, [Result]} | {error, Reason}
444
445       zip_get(FileName, ZipHandle) -> {ok, Result} | {error, Reason}
446
447              Types:
448
449                 FileName = file:name()
450                 ZipHandle = handle()
451                 Result = file:name() | {file:name(), binary()}
452                 Reason = term()
453
454              Extracts one or all files from an open archive.
455
456              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
460       zip_list_dir(ZipHandle) -> {ok, Result} | {error, Reason}
461
462              Types:
463
464                 Result = [zip_comment() | zip_file()]
465                 ZipHandle = handle()
466                 Reason = term()
467
468              Returns the file list of an open zip archive. The first returned
469              element is the zip archive comment.
470
471       zip_open(Archive) -> {ok, ZipHandle} | {error, Reason}
472
473       zip_open(Archive, Options) -> {ok, ZipHandle} | {error, Reason}
474
475              Types:
476
477                 Archive = file:name() | binary()
478                 ZipHandle = handle()
479                 Options = [Option]
480                 Option = cooked | memory | {cwd, CWD :: file:filename()}
481                 Reason = term()
482
483              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
487              The archive must be closed with zip_close/1.
488
489              The ZipHandle is closed if the process  that  originally  opened
490              the archive dies.
491
492
493
494Ericsson AB                       stdlib 4.2                            zip(3)
Impressum