.TH zip 3 "stdlib  1.15.3" "Ericsson AB" "ERLANG MODULE DEFINITION"
.SH MODULE
zip \- Utility for reading and creating \&'zip\&' arhcives\&.
.SH DESCRIPTION
.LP
The \fIzip\fR module archives and extract 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 is 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 zip/2 or the zip/3 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 unzip/1 or the unzip/2 function\&. (They are also available as \fIextract\fR\&.)
.LP
To return a list of the files in a zip archive, use the list_dir/1 or the list_dir/2 function\&. (They are also available as \fItable\fR\&.)
.LP
To print a list of files to the Erlang shell, use either the t/1 or tt/1 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 zip_open, zip_get, zip_list_dir and zip_close 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 indivudal 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
zip_file()    
.fi
.LP
The record \fIzip_file\fR contains the following fields\&.
.RS 2
.TP 4
.B
\fIname = string()\fR:
the name of the file
.TP 4
.B
\fIinfo = file_info()\fR:
file info as in file:read_file_info/1
.TP 4
.B
\fIcomment = string()\fR:
the comment for the file in the zip archive
.TP 4
.B
\fIoffset = integer()\fR:
the offset of the file in the zip archive (used internally)
.TP 4
.B
\fIcomp_size = integer()\fR:
the compressed size of the file (the uncompressed size is found in \fIinfo\fR)
.RE

.nf
zip_comment    
.fi
.LP
The record \fIzip_comment\fR just contains the archive comment for a zip archive
.RS 2
.TP 4
.B
\fIcomment = string()\fR:
the comment for the zip archive
.RE
.SH EXPORTS
.LP
.B
zip(Name, FileList) -> RetValue
.br
.B
zip(Name, FileList, Options) -> RetValue
.br
.B
create(Name, FileList) -> RetValue
.br
.B
create(Name, FileList, Options) -> RetValue
.br
.RS
.TP
Types
Name = filename()
.br
FileList = [FileSpec]
.br
FileSpec = filename() | {filename(), binary()}
.br
Options = [Option]
.br
Option = memory | cooked | verbose | {comment, Comment} | {cwd, CWD}
.br
Comment = CWD = string()
.br
RetValue = {ok, Name} | {ok, {Name, binary()}} | {error, Reason}
.br
Reason = term()
.br
.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 checks 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
The following options are available:
.RS 2
.TP 4
.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 4
.B
\fIverbose\fR:
Print an informational message about each file being added\&.
.TP 4
.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 4
.B
\fI{comment, Comment}\fR:
Add a comment to the zip-archive\&.
.TP 4
.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\&.)
.RE
.RE
.LP
.B
unzip(Archive) -> RetValue
.br
.B
unzip(Archive, Options) -> RetValue
.br
.B
extract(Archive) -> RetValue
.br
.B
extract(Archive, Options) -> RetValue
.br
.RS
.TP
Types
Archive = filename() | binary()
.br
Options = [Option]
.br
Option = {file_list, FileList} | keep_old_files | verbose | memory | {file_filter, FileFilter} | {cwd, CWD}
.br
FileList = [filename()]
.br
FileBinList = [{filename(), binary()}]
.br
FileFilter = fun(ZipFile) -> true | false
.br
CWD = string()
.br
ZipFile = zip_file()
.br
RetValue = {ok, FileList} | {ok, FileBinList} | {error, Reason} | {error, {Name, Reason}}
.br
Reason = term()
.br
.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 4
.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 4
.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 zip file without the \fIraw\fR option\&. The same goes for the files extracted\&.
.TP 4
.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\&. Not 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 4
.B
\fIverbose\fR:
Print an informational message as each file is being extracted\&.
.TP 4
.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 4
.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
.B
list_dir(Archive) -> RetValue
.br
.B
list_dir(Archive, Options)
.br
.B
table(Archive) -> RetValue
.br
.B
table(Archive, Options)
.br
.RS
.TP
Types
Archive = filename() | binary()
.br
RetValue = {ok, [Comment, Files]} | {error, Reason}
.br
Comment = zip_comment()
.br
Files = [zip_file()]
.br
Options = [Option]
.br
Option = cooked
.br
Reason = term()
.br
.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 4
.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 zip file without the \fIraw\fR option\&.
.RE
.RE
.LP
.B
t(Archive)
.br
.RS
.TP
Types
Archive = filename() | binary() | ZipHandle
.br
ZipHandle = pid()
.br
.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 "\fItart\fR"\&.)
.RE
.LP
.B
tt(Archive)
.br
.RS
.TP
Types
Archive = filename() | binary()
.br
.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
.B
zip_open(Archive) -> {ok, ZipHandle} | {error, Reason}
.br
.B
zip_open(Archive, Options) -> {ok, ZipHandle} | {error, Reason}
.br
.RS
.TP
Types
Archive = filename() | binary()
.br
Options = [Option]
.br
Options = cooked | memory | {cwd, CWD}
.br
CWD = string()
.br
ZipHandle = pid()
.br
.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
.B
zip_list_dir(ZipHandle) -> Result | {error, Reason}
.br
.RS
.TP
Types
Result = [ZipComment, ZipFile\&.\&.\&.]
.br
ZipComment = #zip_comment{}
.br
ZipFile = #zip_file{}
.br
ZipHandle = pid()
.br
.RE
.RS
.LP
The \fIzip_list_dir/1\fR function returns the file list of an open zip archive\&.
.RE
.LP
.B
zip_get(ZipHandle) -> {ok, [Result]} | {error, Reason}
.br
.B
zip_get(FileName, ZipHandle) -> {ok, Result} | {error, Reason}
.br
.RS
.TP
Types
FileName = filename()
.br
ZipHandle = pid()
.br
Result = filename() | {filename(), binary()}
.br
.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
.B
zip_close(ZipHandle) -> ok | {error, einval}
.br
.RS
.TP
Types
ZipHandle = pid()
.br
.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