.TH zip 3erl "stdlib 1.18.1" "Ericsson AB" "Erlang Module Definition"
.SH NAME
zip \- Utility for reading and creating 'zip' archives.
.SH DESCRIPTION
.LP
The \fIzip\fR\& module archives and extracts files to and from a zip archive\&. The zip format is specified by the "ZIP Appnote\&.txt" file available on PKWare\&'s website www\&.pkware\&.com\&.
.LP
The zip module supports zip archive versions up to 6\&.1\&. However, password-protection and Zip64 are not supported\&.
.LP
By convention, the name of a zip file should end in "\fI\&.zip\fR\&"\&. To abide to the convention, you\&'ll need to add "\fI\&.zip\fR\&" yourself to the name\&.
.LP
Zip archives are created with the \fBzip/2\fR\& or the \fBzip/3\fR\& function\&. (They are also available as \fIcreate\fR\&, to resemble the \fIerl_tar\fR\& module\&.)
.LP
To extract files from a zip archive, use the \fBunzip/1\fR\& or the \fBunzip/2\fR\& function\&. (They are also available as \fIextract\fR\&\&.)
.LP
To fold a function over all files in a zip archive, use the \fBfoldl_3\fR\& function\&.
.LP
To return a list of the files in a zip archive, use the \fBlist_dir/1\fR\& or the \fBlist_dir/2\fR\& function\&. (They are also available as \fItable\fR\&\&.)
.LP
To print a list of files to the Erlang shell, use either the \fBt/1\fR\& or \fBtt/1\fR\& function\&.
.LP
In some cases, it is desirable to open a zip archive, and to unzip files from it file by file, without having to reopen the archive\&. The functions \fBzip_open\fR\&, \fBzip_get\fR\&, \fBzip_list_dir\fR\& and \fBzip_close\fR\& do this\&.
.SH "LIMITATIONS"

.LP
Zip64 archives are not currently supported\&.
.LP
Password-protected and encrypted archives are not currently supported
.LP
Only the DEFLATE (zlib-compression) and the STORE (uncompressed data) zip methods are supported\&.
.LP
The size of the archive is limited to 2 G-byte (32 bits)\&.
.LP
Comments for individual files is not supported when creating zip archives\&. The zip archive comment for the whole zip archive is supported\&.
.LP
There is currently no support for altering an existing zip archive\&. To add or remove a file from an archive, the whole archive must be recreated\&.
.SH DATA TYPES
.nf

\fBzip_comment()\fR\& = #zip_comment{comment = undefined | string()}
.br
.fi
.RS
.LP
The record \fIzip_comment\fR\& just contains the archive comment for a zip archive
.RE

.nf

\fBzip_file()\fR\& = 
.br
    #zip_file{name = undefined | string(),
.br
              info = undefined | \fBfile:file_info()\fR\&,
.br
              comment = undefined | string(),
.br
              offset = undefined | integer() >= 0,
.br
              comp_size = undefined | integer() >= 0}
.br
.fi
.RS
.LP
The record \fIzip_file\fR\& contains the following fields\&.
.RS 2
.TP 2
.B
\fIname\fR\&:
the name of the file
.TP 2
.B
\fIinfo\fR\&:
file info as in \fBfile:read_file_info/1\fR\&
.TP 2
.B
\fIcomment\fR\&:
the comment for the file in the zip archive
.TP 2
.B
\fIoffset\fR\&:
the offset of the file in the zip archive (used internally)
.TP 2
.B
\fIcomp_size\fR\&:
the compressed size of the file (the uncompressed size is found in \fIinfo\fR\&)
.RE
.RE

.SH EXPORTS
.LP
.nf

.B
zip(Name, FileList) -> RetValue
.br
.fi
.br
.nf

.B
zip(Name, FileList, Options) -> RetValue
.br
.fi
.br
.nf

.B
create(Name, FileList) -> RetValue
.br
.fi
.br
.nf

.B
create(Name, FileList, Options) -> RetValue
.br
.fi
.br
.RS
.LP
Types:

.RS 3
Name = \fBfile:name()\fR\&
.br
FileList = [FileSpec]
.br
FileSpec = \fBfile:name()\fR\&
.br
         | {\fBfile:name()\fR\&, binary()}
.br
         | {\fBfile:name()\fR\&, binary(), \fBfile:file_info()\fR\&}
.br
Options = [Option]
.br
Option = memory
.br
       | cooked
.br
       | verbose
.br
       | {comment, Comment}
.br
       | {cwd, CWD}
.br
       | {compress, What}
.br
       | {uncompress, What}
.br
What = all
.br
     | [Extension]
.br
     | {add, [Extension]}
.br
     | {del, [Extension]}
.br
Extension = Comment = CWD = string()
.br
RetValue = {ok, FileName :: \fBfile:name()\fR\&}
.br
         | {ok, {FileName :: \fBfile:name()\fR\&, binary()}}
.br
         | {error, Reason :: term()}
.br
.RE
.RE
.RS
.LP
The \fIzip\fR\& function creates a zip archive containing the files specified in \fIFileList\fR\&\&.
.LP
As synonyms, the functions \fIcreate/2\fR\& and \fIcreate/3\fR\& are provided, to make it resemble the \fIerl_tar\fR\& module\&.
.LP
The file-list is a list of files, with paths relative to the current directory, they will be stored with this path in the archive\&. Files may also be specified with data in binaries, to create an archive directly from data\&.
.LP
Files will be compressed using the DEFLATE compression, as described in the Appnote\&.txt file\&. However, files will be stored without compression if they already are compressed\&. The \fIzip/2\fR\& and \fIzip/3\fR\& functions check the file extension to see whether the file should be stored without compression\&. Files with the following extensions are not compressed: \fI\&.Z\fR\&, \fI\&.zip\fR\&, \fI\&.zoo\fR\&, \fI\&.arc\fR\&, \fI\&.lzh\fR\&, \fI\&.arj\fR\&\&.
.LP
It is possible to override the default behavior and explicitly control what types of files that should be compressed by using the \fI{compress, What}\fR\& and \fI{uncompress, What}\fR\& options\&. It is possible to have several \fIcompress\fR\& and \fIuncompress\fR\& options\&. In order to trigger compression of a file, its extension must match with the \fIcompress\fR\& condition and must not match the \fIuncompress\fR\& condition\&. For example if \fIcompress\fR\& is set to \fI["gif", "jpg"]\fR\& and \fIuncompress\fR\& is set to \fI["jpg"]\fR\&, only files with \fI"gif"\fR\& as extension will be compressed\&. No other files will be compressed\&.
.LP
The following options are available:
.RS 2
.TP 2
.B
\fIcooked\fR\&:
By default, the \fIopen/2\fR\& function will open the zip file in \fIraw\fR\& mode, which is faster but does not allow a remote (erlang) file server to be used\&. Adding \fIcooked\fR\& to the mode list will override the default and open the zip file without the \fIraw\fR\& option\&. The same goes for the files added\&.
.TP 2
.B
\fIverbose\fR\&:
Print an informational message about each file being added\&.
.TP 2
.B
\fImemory\fR\&:
The output will not be to a file, but instead as a tuple \fI{FileName, binary()}\fR\&\&. The binary will be a full zip archive with header, and can be extracted with for instance \fIunzip/2\fR\&\&.
.TP 2
.B
\fI{comment, Comment}\fR\&:
Add a comment to the zip-archive\&.
.TP 2
.B
\fI{cwd, CWD}\fR\&:
Use the given directory as current directory, it will be prepended to file names when adding them, although it will not be in the zip-archive\&. (Acting like a file:set_cwd/1, but without changing the global cwd property\&.)
.TP 2
.B
\fI{compress, What}\fR\&:
Controls what types of files will be compressed\&. It is by default set to \fIall\fR\&\&. The following values of \fIWhat\fR\& are allowed:
.RS 2
.TP 2
.B
\fIall\fR\&:
means that all files will be compressed (as long as they pass the \fIuncompress\fR\& condition)\&.
.TP 2
.B
\fI[Extension]\fR\&:
means that only files with exactly these extensions will be compressed\&.
.TP 2
.B
\fI{add,[Extension]}\fR\&:
adds these extensions to the list of compress extensions\&.
.TP 2
.B
\fI{del,[Extension]}\fR\&:
deletes these extensions from the list of compress extensions\&.
.RE
.TP 2
.B
\fI{uncompress, What}\fR\&:
Controls what types of files will be uncompressed\&. It is by default set to \fI["\&.Z","\&.zip","\&.zoo","\&.arc","\&.lzh","\&.arj"]\fR\&\&. The following values of \fIWhat\fR\& are allowed:
.RS 2
.TP 2
.B
\fIall\fR\&:
means that no files will be compressed\&.
.TP 2
.B
\fI[Extension]\fR\&:
means that files with these extensions will be uncompressed\&.
.TP 2
.B
\fI{add,[Extension]}\fR\&:
adds these extensions to the list of uncompress extensions\&.
.TP 2
.B
\fI{del,[Extension]}\fR\&:
deletes these extensions from the list of uncompress extensions\&.
.RE
.RE
.RE

.LP
.nf

.B
unzip(Archive) -> RetValue
.br
.fi
.br
.nf

.B
unzip(Archive, Options) -> RetValue
.br
.fi
.br
.nf

.B
extract(Archive) -> RetValue
.br
.fi
.br
.nf

.B
extract(Archive, Options) -> RetValue
.br
.fi
.br
.RS
.LP
Types:

.RS 3
Archive = \fBfile:name()\fR\& | binary()
.br
Options = [Option]
.br
Option = {file_list, FileList}
.br
       | keep_old_files
.br
       | verbose
.br
       | memory
.br
       | {file_filter, FileFilter}
.br
       | {cwd, CWD}
.br
FileList = [\fBfile:name()\fR\&]
.br
FileBinList = [{\fBfile:name()\fR\&, binary()}]
.br
FileFilter = fun((ZipFile) -> boolean())
.br
CWD = string()
.br
ZipFile = \fBzip_file()\fR\&
.br
RetValue = {ok, FileList}
.br
         | {ok, FileBinList}
.br
         | {error, Reason :: term()}
.br
         | {error, {Name :: \fBfile:name()\fR\&, Reason :: term()}}
.br
.RE
.RE
.RS
.LP
The \fIunzip/1\fR\& function extracts all files from a zip archive\&. The \fIunzip/2\fR\& function provides options to extract some files, and more\&.
.LP
If the \fIArchive\fR\& argument is given as a binary, the contents of the binary is assumed to be a zip archive, otherwise it should be a filename\&.
.LP
The following options are available:
.RS 2
.TP 2
.B
\fI{file_list, FileList}\fR\&:
By default, all files will be extracted from the zip archive\&. With the \fI{file_list, FileList}\fR\& option, the \fIunzip/2\fR\& function will only extract the files whose names are included in \fIFileList\fR\&\&. The full paths, including the names of all sub directories within the zip archive, must be specified\&.
.TP 2
.B
\fIcooked\fR\&:
By default, the \fIopen/2\fR\& function will open the zip file in \fIraw\fR\& mode, which is faster but does not allow a remote (erlang) file server to be used\&. Adding \fIcooked\fR\& to the mode list will override the default and open the zip file without the \fIraw\fR\& option\&. The same goes for the files extracted\&.
.TP 2
.B
\fIkeep_old_files\fR\&:
By default, all existing files with the same name as file in the zip archive will be overwritten\&. With the \fIkeep_old_files\fR\& option, the \fIunzip/2\fR\& function will not overwrite any existing files\&. Note that even with the \fImemory\fR\& option given, which means that no files will be overwritten, files existing will be excluded from the result\&.
.TP 2
.B
\fIverbose\fR\&:
Print an informational message as each file is being extracted\&.
.TP 2
.B
\fImemory\fR\&:
Instead of extracting to the current directory, the \fImemory\fR\& option will give the result as a list of tuples \fI{Filename, Binary}\fR\&, where \fIBinary\fR\& is a binary containing the extracted data of the file named \fIFilename\fR\& in the zip archive\&.
.TP 2
.B
\fI{cwd, CWD}\fR\&:
Use the given directory as current directory, it will be prepended to file names when extracting them from the zip-archive\&. (Acting like a file:set_cwd/1, but without changing the global cwd property\&.)
.RE
.RE

.LP
.nf

.B
foldl(Fun, Acc0, Archive) -> {ok, Acc1} | {error, Reason}
.br
.fi
.br
.RS
.LP
Types:

.RS 3
Fun = fun((FileInArchive, GetInfo, GetBin, AccIn) -> AccOut)
.br
FileInArchive = \fBfile:name()\fR\&
.br
GetInfo = fun(() -> \fBfile:file_info()\fR\&)
.br
GetBin = fun(() -> binary())
.br
Acc0 = Acc1 = AccIn = AccOut = term()
.br
Archive = \fBfile:name()\fR\& | {\fBfile:name()\fR\&, binary()}
.br
Reason = term()
.br
.RE
.RE
.RS
.LP
The \fIfoldl/3\fR\& function calls \fIFun(FileInArchive, GetInfo, GetBin, AccIn)\fR\& on successive files in the \fIArchive\fR\&, starting with \fIAccIn == Acc0\fR\&\&. \fIFileInArchive\fR\& is the name that the file has in the archive\&. \fIGetInfo\fR\& is a fun that returns info about the the file\&. \fIGetBin\fR\& returns the contents of the file\&. Both \fIGetInfo\fR\& and \fIGetBin\fR\& must be called within the \fIFun\fR\&\&. Their behavior is undefined if they are called outside the context of the \fIFun\fR\&\&. The \fIFun\fR\& must return a new accumulator which is passed to the next call\&. \fIfoldl/3\fR\& returns the final value of the accumulator\&. \fIAcc0\fR\& is returned if the archive is empty\&. It is not necessary to iterate over all files in the archive\&. The iteration may be ended prematurely in a controlled manner by throwing an exception\&.
.LP
For example:
.LP
.nf

> Name = "dummy\&.zip"\&.
"dummy.zip"
> {ok, {Name, Bin}} = zip:create(Name, [{"foo", <<"FOO">>}, {"bar", <<"BAR">>}], [memory])\&.
{ok,{"dummy.zip",
     <<80,75,3,4,20,0,0,0,0,0,74,152,97,60,171,39,212,26,3,0,
       0,0,3,0,0,...>>}}
> {ok, FileSpec} = zip:foldl(fun(N, I, B, Acc) -> [{N, B(), I()} | Acc] end, [], {Name, Bin})\&.
{ok,[{"bar",<<"BAR">>,
      {file_info,3,regular,read_write,
                 {{2010,3,1},{19,2,10}},
                 {{2010,3,1},{19,2,10}},
                 {{2010,3,1},{19,2,10}},
                 54,1,0,0,0,0,0}},
     {"foo",<<"FOO">>,
      {file_info,3,regular,read_write,
                 {{2010,3,1},{19,2,10}},
                 {{2010,3,1},{19,2,10}},
                 {{2010,3,1},{19,2,10}},
                 54,1,0,0,0,0,0}}]}
> {ok, {Name, Bin}} = zip:create(Name, lists:reverse(FileSpec), [memory])\&.
{ok,{"dummy.zip",
     <<80,75,3,4,20,0,0,0,0,0,74,152,97,60,171,39,212,26,3,0,
       0,0,3,0,0,...>>}}
> catch zip:foldl(fun("foo", _, B, _) -> throw(B()); (_, _, _, Acc) -> Acc end, [], {Name, Bin})\&. 
<<"FOO">>

.fi
.RE

.LP
.nf

.B
list_dir(Archive) -> RetValue
.br
.fi
.br
.nf

.B
list_dir(Archive, Options) -> RetValue
.br
.fi
.br
.nf

.B
table(Archive) -> RetValue
.br
.fi
.br
.nf

.B
table(Archive, Options) -> RetValue
.br
.fi
.br
.RS
.LP
Types:

.RS 3
Archive = \fBfile:name()\fR\& | binary()
.br
RetValue = {ok, CommentAndFiles} | {error, Reason :: term()}
.br
CommentAndFiles = [\fBzip_comment()\fR\& | \fBzip_file()\fR\&]
.br
Options = [Option]
.br
Option = cooked
.br
.RE
.RE
.RS
.LP
The \fIlist_dir/1\fR\& function retrieves the names of all files in the zip archive \fIArchive\fR\&\&. The \fIlist_dir/2\fR\& function provides options\&.
.LP
As synonyms, the functions \fItable/2\fR\& and \fItable/3\fR\& are provided, to make it resemble the \fIerl_tar\fR\& module\&.
.LP
The result value is the tuple \fI{ok, List}\fR\&, where \fIList\fR\& contains the zip archive comment as the first element\&.
.LP
The following options are available:
.RS 2
.TP 2
.B
\fIcooked\fR\&:
By default, the \fIopen/2\fR\& function will open the zip file in \fIraw\fR\& mode, which is faster but does not allow a remote (erlang) file server to be used\&. Adding \fIcooked\fR\& to the mode list will override the default and open the zip file without the \fIraw\fR\& option\&.
.RE
.RE

.LP
.nf

.B
t(Archive) -> ok
.br
.fi
.br
.RS
.LP
Types:

.RS 3
Archive = \fBfile:name()\fR\& | binary() | ZipHandle
.br
ZipHandle = pid()
.br
.RE
.RE
.RS
.LP
The \fIt/1\fR\& function prints the names of all files in the zip archive \fIArchive\fR\& to the Erlang shell\&. (Similar to "\fItar t\fR\&"\&.)
.RE

.LP
.nf

.B
tt(Archive) -> ok
.br
.fi
.br
.RS
.LP
Types:

.RS 3
Archive = \fBfile:name()\fR\& | binary() | ZipHandle
.br
ZipHandle = pid()
.br
.RE
.RE
.RS
.LP
The \fItt/1\fR\& function prints names and information about all files in the zip archive \fIArchive\fR\& to the Erlang shell\&. (Similar to "\fItar tv\fR\&"\&.)
.RE

.LP
.nf

.B
zip_open(Archive) -> {ok, ZipHandle} | {error, Reason}
.br
.fi
.br
.nf

.B
zip_open(Archive, Options) -> {ok, ZipHandle} | {error, Reason}
.br
.fi
.br
.RS
.LP
Types:

.RS 3
Archive = \fBfile:name()\fR\& | binary()
.br
ZipHandle = pid()
.br
Options = [Option]
.br
Option = cooked | memory | {cwd, CWD :: string()}
.br
Reason = term()
.br
.RE
.RE
.RS
.LP
The \fIzip_open\fR\& function opens a zip archive, and reads and saves its directory\&. This means that subsequently reading files from the archive will be faster than unzipping files one at a time with \fIunzip\fR\&\&.
.LP
The archive must be closed with \fIzip_close/1\fR\&\&.
.RE

.LP
.nf

.B
zip_list_dir(ZipHandle) -> {ok, Result} | {error, Reason}
.br
.fi
.br
.RS
.LP
Types:

.RS 3
Result = [\fBzip_comment()\fR\& | \fBzip_file()\fR\&]
.br
ZipHandle = pid()
.br
Reason = term()
.br
.RE
.RE
.RS
.LP
The \fIzip_list_dir/1\fR\& function returns the file list of an open zip archive\&. The first returned element is the zip archive comment\&.
.RE

.LP
.nf

.B
zip_get(ZipHandle) -> {ok, [Result]} | {error, Reason}
.br
.fi
.br
.nf

.B
zip_get(FileName, ZipHandle) -> {ok, Result} | {error, Reason}
.br
.fi
.br
.RS
.LP
Types:

.RS 3
FileName = \fBfile:name()\fR\&
.br
ZipHandle = pid()
.br
Result = \fBfile:name()\fR\& | {\fBfile:name()\fR\&, binary()}
.br
Reason = term()
.br
.RE
.RE
.RS
.LP
The \fIzip_get\fR\& function extracts one or all files from an open archive\&.
.LP
The files will be unzipped to memory or to file, depending on the options given to the \fIzip_open\fR\& function when the archive was opened\&.
.RE

.LP
.nf

.B
zip_close(ZipHandle) -> ok | {error, einval}
.br
.fi
.br
.RS
.LP
Types:

.RS 3
ZipHandle = pid()
.br
.RE
.RE
.RS
.LP
The \fIzip_close/1\fR\& function closes a zip archive, previously opened with \fIzip_open\fR\&\&. All resources are closed, and the handle should not be used after closing\&.
.RE