Provided by: erlang-manpages_16.b.3-dfsg-1ubuntu2.2_all 
NAME
zip - Utility for reading and creating 'zip' archives.
DESCRIPTION
The zip 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.
The zip module supports zip archive versions up to 6.1. However, password-protection and
Zip64 are not supported.
By convention, the name of a zip file should end in ".zip". To abide to the convention,
you'll need to add ".zip" yourself to the name.
Zip archives are created with the zip/2 or the zip/3 function. (They are also available as
create, to resemble the erl_tar module.)
To extract files from a zip archive, use the unzip/1 or the unzip/2 function. (They are
also available as extract.)
To fold a function over all files in a zip archive, use the foldl_3 function.
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 table.)
To print a list of files to the Erlang shell, use either the t/1 or tt/1 function.
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.
LIMITATIONS
Zip64 archives are not currently supported.
Password-protected and encrypted archives are not currently supported
Only the DEFLATE (zlib-compression) and the STORE (uncompressed data) zip methods are
supported.
The size of the archive is limited to 2 G-byte (32 bits).
Comments for individual files is not supported when creating zip archives. The zip archive
comment for the whole zip archive is supported.
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.
DATA TYPES
zip_comment() = #zip_comment{comment = undefined | string()}
The record zip_comment just contains the archive comment for a zip archive
zip_file() =
#zip_file{name = undefined | string(),
info = undefined | file:file_info(),
comment = undefined | string(),
offset = undefined | integer() >= 0,
comp_size = undefined | integer() >= 0}
The record zip_file contains the following fields.
name:
the name of the file
info:
file info as in file:read_file_info/1
comment:
the comment for the file in the zip archive
offset:
the offset of the file in the zip archive (used internally)
comp_size:
the compressed size of the file (the uncompressed size is found in info)
EXPORTS
zip(Name, FileList) -> RetValue
zip(Name, FileList, Options) -> RetValue
create(Name, FileList) -> RetValue
create(Name, FileList, Options) -> RetValue
Types:
Name = file:name()
FileList = [FileSpec]
FileSpec = file:name()
| {file:name(), binary()}
| {file:name(), binary(), file:file_info()}
Options = [Option]
Option = memory
| cooked
| verbose
| {comment, Comment}
| {cwd, CWD}
| {compress, What}
| {uncompress, What}
What = all
| [Extension]
| {add, [Extension]}
| {del, [Extension]}
Extension = Comment = CWD = string()
RetValue = {ok, FileName :: file:name()}
| {ok, {FileName :: file:name(), binary()}}
| {error, Reason :: term()}
The zip function creates a zip archive containing the files specified in FileList.
As synonyms, the functions create/2 and create/3 are provided, to make it resemble
the erl_tar module.
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.
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 zip/2 and zip/3 functions check the file extension to see
whether the file should be stored without compression. Files with the following
extensions are not compressed: .Z, .zip, .zoo, .arc, .lzh, .arj.
It is possible to override the default behavior and explicitly control what types
of files that should be compressed by using the {compress, What} and {uncompress,
What} options. It is possible to have several compress and uncompress options. In
order to trigger compression of a file, its extension must match with the compress
condition and must not match the uncompress condition. For example if compress is
set to ["gif", "jpg"] and uncompress is set to ["jpg"], only files with "gif" as
extension will be compressed. No other files will be compressed.
The following options are available:
cooked:
By default, the open/2 function will open the zip file in raw mode, which is
faster but does not allow a remote (erlang) file server to be used. Adding
cooked to the mode list will override the default and open the zip file without
the raw option. The same goes for the files added.
verbose:
Print an informational message about each file being added.
memory:
The output will not be to a file, but instead as a tuple {FileName, binary()}.
The binary will be a full zip archive with header, and can be extracted with
for instance unzip/2.
{comment, Comment}:
Add a comment to the zip-archive.
{cwd, CWD}:
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.)
{compress, What}:
Controls what types of files will be compressed. It is by default set to all.
The following values of What are allowed:
all:
means that all files will be compressed (as long as they pass the uncompress
condition).
[Extension]:
means that only files with exactly these extensions will be compressed.
{add,[Extension]}:
adds these extensions to the list of compress extensions.
{del,[Extension]}:
deletes these extensions from the list of compress extensions.
{uncompress, What}:
Controls what types of files will be uncompressed. It is by default set to
[".Z", ".zip", ".zoo", ".arc", ".lzh", ".arj"]. The following values of What
are allowed:
all:
means that no files will be compressed.
[Extension]:
means that files with these extensions will be uncompressed.
{add,[Extension]}:
adds these extensions to the list of uncompress extensions.
{del,[Extension]}:
deletes these extensions from the list of uncompress extensions.
unzip(Archive) -> RetValue
unzip(Archive, Options) -> RetValue
extract(Archive) -> RetValue
extract(Archive, Options) -> RetValue
Types:
Archive = file:name() | binary()
Options = [Option]
Option = {file_list, FileList}
| keep_old_files
| verbose
| memory
| {file_filter, FileFilter}
| {cwd, CWD}
FileList = [file:name()]
FileBinList = [{file:name(), binary()}]
FileFilter = fun((ZipFile) -> boolean())
CWD = string()
ZipFile = zip_file()
RetValue = {ok, FileList}
| {ok, FileBinList}
| {error, Reason :: term()}
| {error, {Name :: file:name(), Reason :: term()}}
The unzip/1 function extracts all files from a zip archive. The unzip/2 function
provides options to extract some files, and more.
If the Archive argument is given as a binary, the contents of the binary is assumed
to be a zip archive, otherwise it should be a filename.
The following options are available:
{file_list, FileList}:
By default, all files will be extracted from the zip archive. With the
{file_list, FileList} option, the unzip/2 function will only extract the files
whose names are included in FileList. The full paths, including the names of
all sub directories within the zip archive, must be specified.
cooked:
By default, the open/2 function will open the zip file in raw mode, which is
faster but does not allow a remote (erlang) file server to be used. Adding
cooked to the mode list will override the default and open the zip file without
the raw option. The same goes for the files extracted.
keep_old_files:
By default, all existing files with the same name as file in the zip archive
will be overwritten. With the keep_old_files option, the unzip/2 function will
not overwrite any existing files. Note that even with the memory option given,
which means that no files will be overwritten, files existing will be excluded
from the result.
verbose:
Print an informational message as each file is being extracted.
memory:
Instead of extracting to the current directory, the memory option will give the
result as a list of tuples {Filename, Binary}, where Binary is a binary
containing the extracted data of the file named Filename in the zip archive.
{cwd, CWD}:
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.)
foldl(Fun, Acc0, Archive) -> {ok, Acc1} | {error, Reason}
Types:
Fun = fun((FileInArchive, GetInfo, GetBin, AccIn) -> AccOut)
FileInArchive = file:name()
GetInfo = fun(() -> file:file_info())
GetBin = fun(() -> binary())
Acc0 = Acc1 = AccIn = AccOut = term()
Archive = file:name() | {file:name(), binary()}
Reason = term()
The foldl/3 function calls Fun(FileInArchive, GetInfo, GetBin, AccIn) on successive
files in the Archive, starting with AccIn == Acc0. FileInArchive is the name that
the file has in the archive. GetInfo is a fun that returns info about the the file.
GetBin returns the contents of the file. Both GetInfo and GetBin must be called
within the Fun. Their behavior is undefined if they are called outside the context
of the Fun. The Fun must return a new accumulator which is passed to the next call.
foldl/3 returns the final value of the accumulator. Acc0 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.
For example:
> 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">>
list_dir(Archive) -> RetValue
list_dir(Archive, Options) -> RetValue
table(Archive) -> RetValue
table(Archive, Options) -> RetValue
Types:
Archive = file:name() | binary()
RetValue = {ok, CommentAndFiles} | {error, Reason :: term()}
CommentAndFiles = [zip_comment() | zip_file()]
Options = [Option]
Option = cooked
The list_dir/1 function retrieves the names of all files in the zip archive
Archive. The list_dir/2 function provides options.
As synonyms, the functions table/2 and table/3 are provided, to make it resemble
the erl_tar module.
The result value is the tuple {ok, List}, where List contains the zip archive
comment as the first element.
The following options are available:
cooked:
By default, the open/2 function will open the zip file in raw mode, which is
faster but does not allow a remote (erlang) file server to be used. Adding
cooked to the mode list will override the default and open the zip file without
the raw option.
t(Archive) -> ok
Types:
Archive = file:name() | binary() | ZipHandle
ZipHandle = pid()
The t/1 function prints the names of all files in the zip archive Archive to the
Erlang shell. (Similar to "tar t".)
tt(Archive) -> ok
Types:
Archive = file:name() | binary() | ZipHandle
ZipHandle = pid()
The tt/1 function prints names and information about all files in the zip archive
Archive to the Erlang shell. (Similar to "tar tv".)
zip_open(Archive) -> {ok, ZipHandle} | {error, Reason}
zip_open(Archive, Options) -> {ok, ZipHandle} | {error, Reason}
Types:
Archive = file:name() | binary()
ZipHandle = pid()
Options = [Option]
Option = cooked | memory | {cwd, CWD :: string()}
Reason = term()
The zip_open 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 unzip.
The archive must be closed with zip_close/1.
zip_list_dir(ZipHandle) -> {ok, Result} | {error, Reason}
Types:
Result = [zip_comment() | zip_file()]
ZipHandle = pid()
Reason = term()
The zip_list_dir/1 function returns the file list of an open zip archive. The first
returned element is the zip archive comment.
zip_get(ZipHandle) -> {ok, [Result]} | {error, Reason}
zip_get(FileName, ZipHandle) -> {ok, Result} | {error, Reason}
Types:
FileName = file:name()
ZipHandle = pid()
Result = file:name() | {file:name(), binary()}
Reason = term()
The zip_get function extracts one or all files from an open archive.
The files will be unzipped to memory or to file, depending on the options given to
the zip_open function when the archive was opened.
zip_close(ZipHandle) -> ok | {error, einval}
Types:
ZipHandle = pid()
The zip_close/1 function closes a zip archive, previously opened with zip_open. All
resources are closed, and the handle should not be used after closing.