File: zip.html

package info (click to toggle)
erlang-doc-html 1%3A11.b.2-1
links: PTS
area: main
in suites: etch, etch-m68k
size: 23,284 kB
ctags: 10,724
sloc: erlang: 505; ansic: 323; makefile: 62; perl: 61; sh: 45
file content (454 lines) | stat: -rw-r--r-- 15,068 bytes
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<!-- This document was generated using DocBuilder 3.3.3 -->
<HTML>
<HEAD>
  <TITLE>zip</TITLE>
  <SCRIPT type="text/javascript" src="../../../../doc/erlresolvelinks.js">
</SCRIPT>
  <STYLE TYPE="text/css">
<!--
    .REFBODY     { margin-left: 13mm }
    .REFTYPES    { margin-left: 8mm }
-->
  </STYLE>
</HEAD>
<BODY BGCOLOR="#FFFFFF" TEXT="#000000" LINK="#0000FF" VLINK="#FF00FF"
      ALINK="#FF0000">
<!-- refpage -->
<CENTER>
<A HREF="http://www.erlang.se">
  <IMG BORDER=0 ALT="[Ericsson AB]" SRC="min_head.gif">
</A>
<H1>zip</H1>
</CENTER>

<H3>MODULE</H3>
<DIV CLASS=REFBODY>
zip
</DIV>

<H3>MODULE SUMMARY</H3>
<DIV CLASS=REFBODY>
 Utility for reading and creating 'zip' arhcives.

</DIV>

<H3>DESCRIPTION</H3>
<DIV CLASS=REFBODY>

<P>The <CODE>zip</CODE> module archives and extract files to and from a zip
archive. The zip format is specified by the &#34;ZIP Appnote.txt&#34; file
available on PKWare's website www.pkware.com.
<P>The zip module supports zip archive versions up to 6.1. However,
password-protection and Zip64 is not supported.
<P>By convention, the name of a zip file should end in &#34;<CODE>.zip</CODE>&#34;.
To abide to the convention, you'll need to add &#34;<CODE>.zip</CODE>&#34; yourself
to the name.
<P>Zip archives are created with the 
<A HREF="#zip_2">zip/2</A> or the 
<A HREF="#zip_3">zip/3</A> function. (They are
also available as <CODE>create</CODE>, to resemble the <CODE>erl_tar</CODE>
module.)
<P>To extract files from a zip archive, use the 
<A HREF="#unzip_1">unzip/1</A> or the 
<A HREF="#unzip_2">unzip/2</A> function. (They are
also available as <CODE>extract</CODE>.)
<P>To return a list of the files in a zip archive, use the 
<A HREF="#list_dir_1">list_dir/1</A> or the
<A HREF="#list_dir_2">list_dir/2</A> function. (They
are also available as <CODE>table</CODE>.)
<P>To print a list of files to the Erlang shell,
use either the <A HREF="#t_1">t/1</A> or
<A HREF="#tt_1">tt/1</A> function.
<P>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
<A HREF="#zip_open">zip_open</A>,
<A HREF="#zip_get">zip_get</A>,
<A HREF="#zip_list_dir">zip_list_dir</A> and
<A HREF="#zip_close">zip_close</A> do this.
</DIV>

<H3>LIMITATIONS</H3>
<DIV CLASS=REFBODY>

<P>Zip64 archives are not currently supported.
<P>Password-protected and encrypted archives are not currently
supported
<P>Only the DEFLATE (zlib-compression) and the STORE (uncompressed
data) zip methods are supported.
<P>The size of the archive is limited to 2 G-byte (32 bits).
<P>Comments for indivudal files is not supported when creating zip
archives. The zip archive comment for the whole zip archive is
supported.
<P>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.
</DIV>

<H3>EXPORTS</H3>

<P><A NAME="zip/2"><STRONG><CODE>zip(Name, FileList)</CODE></STRONG></A><BR>
<A NAME="zip/3"><STRONG><CODE>zip(Name, FileList, Options)</CODE></STRONG></A><BR>
<A NAME="create/2"><STRONG><CODE>create(Name, FileList)</CODE></STRONG></A><BR>
<A NAME="create/3"><STRONG><CODE>create(Name, FileList, Options)</CODE></STRONG></A><BR>

<DIV CLASS=REFBODY><P>Types:
  <DIV CLASS=REFTYPES>
<P>
<STRONG><CODE>Name = filename()</CODE></STRONG><BR>
<STRONG><CODE>FileList = [FileSpec]</CODE></STRONG><BR>
<STRONG><CODE>FileSpec = filename() | {filename(), binary()</CODE></STRONG><BR>
<STRONG><CODE>Options = [Option]</CODE></STRONG><BR>
<STRONG><CODE>Option = memory | cooked | verbose | {comment, Comment}</CODE></STRONG><BR>
<STRONG><CODE>Comment = string()</CODE></STRONG><BR>
<STRONG><CODE>RetValue = ok | {Name, binary} | {error, {Name, Reason}}</CODE></STRONG><BR>
<STRONG><CODE>Reason = term()</CODE></STRONG><BR>

  </DIV>
</DIV>

<DIV CLASS=REFBODY>

<P>The <A NAME="zip_2"><!-- Empty --></A><CODE>zip/2</CODE> function creates a
         zip archive containing the files specified in <CODE>FileList</CODE>.
         The <A NAME="zip_3"><!-- Empty --></A><CODE>zip/3</CODE> function provides options.
<P>As synonyms, the functions <CODE>create/2</CODE> and <CODE>create/3</CODE>
         are provided, to make it resemble the <CODE>erl_tar</CODE> module.
<P>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.
<P>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 <CODE>zip/2</CODE> and <CODE>zip/3</CODE> checks the file extension
         to see whether the file should be stored without compression.
         Files with the following extensions are not compressed:
         <CODE>.Z</CODE>, <CODE> .zip</CODE>, <CODE> .zoo</CODE>, <CODE> .arc</CODE>, <CODE> .lzh</CODE>,
         <CODE> .arj</CODE>.
        
<P>The following options are available:
<P>
<DL>

<DT>
<CODE>cooked</CODE>
</DT>

<DD>
By default, the <CODE>open/2</CODE> function will open the
         zip file in <CODE>raw</CODE> mode, which is faster but does not allow
         a remote (erlang) file server to be used. Adding <CODE>cooked</CODE>
         to the mode list will override the default and open the zip file
         without the <CODE>raw</CODE> option. The same goes for the files
         added.<BR>

</DD>

<DT>
<CODE>verbose</CODE>
</DT>

<DD>
Print an informational message about each file
         being added.<BR>

</DD>

<DT>
<CODE>memory</CODE>
</DT>

<DD>
The output will not be to a file, but instead as a tuple
         <CODE>{FileName, binary()}</CODE>. The binary will be a full zip
         archive with header, and can be extracted with for instance
         <CODE>unzip/2</CODE>.<BR>

</DD>

<DT>
<CODE>{comment, Comment}</CODE>
</DT>

<DD>
Add a comment to the zip-archive.<BR>

</DD>

</DL>

</DIV>

<P><A NAME="unzip/1"><STRONG><CODE>unzip(Archive) -&#62; RetValue</CODE></STRONG></A><BR>
<A NAME="unzip/2"><STRONG><CODE>unzip(Archive, Options) -&#62; RetValue</CODE></STRONG></A><BR>
<A NAME="extract/1"><STRONG><CODE>extract(Archive) -&#62; RetValue</CODE></STRONG></A><BR>
<A NAME="extract/2"><STRONG><CODE>extract(Archive, Options) -&#62; RetValue</CODE></STRONG></A><BR>

<DIV CLASS=REFBODY><P>Types:
  <DIV CLASS=REFTYPES>
<P>
<STRONG><CODE>Name = filename() | binary()</CODE></STRONG><BR>
<STRONG><CODE>Options = [Option]</CODE></STRONG><BR>
<STRONG><CODE>Option = {files, FileList} | keep_old_files | verbose |
         memory | {file_filter, FileFilter}</CODE></STRONG><BR>
<STRONG><CODE>FileList = [filename()]</CODE></STRONG><BR>
<STRONG><CODE>FileFilter = fun(ZipFile) -&#62; true | false</CODE></STRONG><BR>
<STRONG><CODE>ZipFile = #zip_file</CODE></STRONG><BR>
<STRONG><CODE>RetValue = ok | {error, Reason} | {error, {Name, Reason}}</CODE></STRONG><BR>
<STRONG><CODE>Reason = term()</CODE></STRONG><BR>

  </DIV>
</DIV>

<DIV CLASS=REFBODY>

<P>The <A NAME="unzip_1"><!-- Empty --></A><CODE>unzip/1</CODE> function extracts
         all files from a zip archive. The
         <A NAME="unzip_2"><!-- Empty --></A><CODE>unzip/2</CODE> function provides options
         to extract some files, and more.
<P>If the <CODE>Archive</CODE> argument is given as a binary,
         the contents of the binary is assumed to be a zip archive,
         otherwise it should be a filename.
<P>The following options are available:
<P>
<DL>

<DT>
<CODE>{files, FileList}</CODE>
</DT>

<DD>
By default, all files will be extracted from the zip
         archive. With the <CODE>{files,Files}</CODE> option,
         the <CODE>unzip/2</CODE> function will only extract the files
         whose names are included in <CODE>FileList</CODE>.<BR>

</DD>

<DT>
<CODE>cooked</CODE>
</DT>

<DD>
By default, the <CODE>open/2</CODE> function will open the
         zip file in <CODE>raw</CODE> mode, which is faster but does not allow
         a remote (erlang) file server to be used. Adding <CODE>cooked</CODE>
         to the mode list will override the default and open zip file
         without the <CODE>raw</CODE> option. The same goes for the files
         extracted.<BR>

</DD>

<DT>
<CODE>keep_old_files</CODE>
</DT>

<DD>
By default, all existing files with the same name as file in
         the zip archive will be overwritten. With the <CODE>keep_old_files</CODE>
         option, the <CODE>unzip/2</CODE> function will not overwrite any existing
         files. Not that even with the <CODE>memory</CODE> option given, which
         means that no files will be overwritten, files existing will be
         excluded from the result.<BR>

</DD>

<DT>
<CODE>verbose</CODE>
</DT>

<DD>
Print an informational message as each file is being
         extracted.<BR>

</DD>

</DL>

</DIV>

<P><A NAME="list_dir/1"><STRONG><CODE>list_dir(Archive) -&#62; RetValue</CODE></STRONG></A><BR>
<A NAME="list_dir/2"><STRONG><CODE>list_dir(Archive, Options)</CODE></STRONG></A><BR>
<A NAME="table/1"><STRONG><CODE>table(Archive) -&#62; RetValue</CODE></STRONG></A><BR>
<A NAME="table/2"><STRONG><CODE>table(Archive, Options)</CODE></STRONG></A><BR>

<DIV CLASS=REFBODY><P>Types:
  <DIV CLASS=REFTYPES>
<P>
<STRONG><CODE>Name = filename() | binary()</CODE></STRONG><BR>
<STRONG><CODE>RetValue = {ok, [Comment, Files]} | {error, Reason}</CODE></STRONG><BR>
<STRONG><CODE>Options = [Option]</CODE></STRONG><BR>
<STRONG><CODE>Option = cooked</CODE></STRONG><BR>
<STRONG><CODE>Reason = term()</CODE></STRONG><BR>

  </DIV>
</DIV>

<DIV CLASS=REFBODY>

<P>The <A NAME="list_dir_1"><!-- Empty --></A><CODE>list_dir/1</CODE> function retrieves
         the names of all files in the zip archive <CODE>Archive</CODE>. The
         <A NAME="list_dir_2"><!-- Empty --></A><CODE>list_dir/2</CODE> function provides options.
        
<P>As synonyms, the functions <CODE>table/2</CODE> and <CODE>table/3</CODE>
         are provided, to make it resemble the <CODE>erl_tar</CODE> module.
<P>The result value is the tuple <CODE>{ok, List}</CODE>, where <CODE>List</CODE>
         contains the zip archive comment as the first element.
         The rest is tuples: <CODE>{filename(), fileinfo(), CompSize, Comment}</CODE>,
         where <CODE>CompSize</CODE> is the compressed size of the file in the
         archive and <CODE>Comment</CODE> is the files comment.
<P>The following options are available:
<P>
<DL>

<DT>
<CODE>cooked</CODE>
</DT>

<DD>
By default, the <CODE>open/2</CODE> function will open the
         zip file in <CODE>raw</CODE> mode, which is faster but does not allow
         a remote (erlang) file server to be used. Adding <CODE>cooked</CODE>
         to the mode list will override the default and open zip file
         without the <CODE>raw</CODE> option.<BR>

</DD>

</DL>

</DIV>

<P><A NAME="t/1"><STRONG><CODE>t(Archive)</CODE></STRONG></A><BR>

<DIV CLASS=REFBODY><P>Types:
  <DIV CLASS=REFTYPES>
<P>
<STRONG><CODE>Archive = filename() | binary() | ZipHandle</CODE></STRONG><BR>
<STRONG><CODE>ZipHandle = pid()</CODE></STRONG><BR>

  </DIV>
</DIV>

<DIV CLASS=REFBODY>

<P>The <A NAME="t_1"><!-- Empty --></A><CODE>t/1</CODE> function prints the names
         of all files in the zip archive <CODE>Archive</CODE> to the Erlang shell.
         (Similar to &#34;<CODE>tart</CODE>&#34;.)
</DIV>

<P><A NAME="tt/1"><STRONG><CODE>tt(Archive)</CODE></STRONG></A><BR>

<DIV CLASS=REFBODY><P>Types:
  <DIV CLASS=REFTYPES>
<P>
<STRONG><CODE>Name = filename() | binary()</CODE></STRONG><BR>

  </DIV>
</DIV>

<DIV CLASS=REFBODY>

<P>The <A NAME="tt_1"><!-- Empty --></A><CODE>tt/1</CODE> function prints names and
         information about all files in the zip archive <CODE>Archive</CODE> to
         the Erlang shell. (Similar to &#34;<CODE>tar tv</CODE>&#34;.)
</DIV>

<P><A NAME="zip_open/1"><STRONG><CODE>zip_open(Archive) -&#62; {ok, ZipHandle} | {error, Reason}</CODE></STRONG></A><BR>
<A NAME="zip_open/2"><STRONG><CODE>zip_open(Archive, Options) -&#62;
        {ok, ZipHandle} | {error, Reason}</CODE></STRONG></A><BR>

<DIV CLASS=REFBODY><P>Types:
  <DIV CLASS=REFTYPES>
<P>
<STRONG><CODE>Name = filename() | binary()</CODE></STRONG><BR>
<STRONG><CODE>Options = [Option]</CODE></STRONG><BR>
<STRONG><CODE>Options = cooked | memory</CODE></STRONG><BR>
<STRONG><CODE>ZipHandle = pid()</CODE></STRONG><BR>

  </DIV>
</DIV>

<DIV CLASS=REFBODY>

<P>The <A NAME="zip_open"><!-- Empty --></A><CODE>zip_open</CODE> 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 <CODE>unzip</CODE>.
<P>The archive must be closed with <CODE>zip_close/1</CODE>.
</DIV>

<P><A NAME="zip_list_dir/1"><STRONG><CODE>zip_list_dir(ZipHandle) -&#62; Result | {error, Reason}</CODE></STRONG></A><BR>

<DIV CLASS=REFBODY><P>Types:
  <DIV CLASS=REFTYPES>
<P>
<STRONG><CODE>Result = [ZipComment, ZipFile...]</CODE></STRONG><BR>
<STRONG><CODE>ZipComment = #zip_comment{}</CODE></STRONG><BR>
<STRONG><CODE>ZipFile = #zip_file{}</CODE></STRONG><BR>
<STRONG><CODE>ZipHandle = pid()</CODE></STRONG><BR>

  </DIV>
</DIV>

<DIV CLASS=REFBODY>

<P>The <A NAME="zip_list_dir"><!-- Empty --></A><CODE>zip_list_dir/1</CODE> function
         returns the file list of an open zip archive.
</DIV>

<P><A NAME="zip_get/1"><STRONG><CODE>zip_get(ZipHandle) -&#62; {ok, Result} | {error, Reason}</CODE></STRONG></A><BR>
<A NAME="zip_get/2"><STRONG><CODE>zip_get(FileName, ZipHandle) -&#62;
        {ok, Result} | {error, Reason}</CODE></STRONG></A><BR>

<DIV CLASS=REFBODY><P>Types:
  <DIV CLASS=REFTYPES>
<P>
<STRONG><CODE>Name = filename() | binary() | ZipHandle</CODE></STRONG><BR>
<STRONG><CODE>ZipHandle = pid()</CODE></STRONG><BR>

  </DIV>
</DIV>

<DIV CLASS=REFBODY>

<P>The <A NAME="zip_get"><!-- Empty --></A><CODE>zip_get</CODE> function extracts
         one or all files from an open archive.
<P>The files will be unzipped to memory or to file, depending on
         the options given to the <CODE>zip_open</CODE> function when the
         archive was opened.
</DIV>

<P><A NAME="zip_close/1"><STRONG><CODE>zip_close(ZipHandle) -&#62; ok | {error, einval}</CODE></STRONG></A><BR>

<DIV CLASS=REFBODY><P>Types:
  <DIV CLASS=REFTYPES>
<P>
<STRONG><CODE>ZipHandle = pid()</CODE></STRONG><BR>

  </DIV>
</DIV>

<DIV CLASS=REFBODY>

<P>The <A NAME="zip_close"><!-- Empty --></A><CODE>zip_close/1</CODE> function closes
         a zip archive, previously opened with <CODE>zip_open</CODE>. All
         resources are closed, and the handle should not be used after
         closing.
</DIV>

<H3>AUTHORS</H3>
<DIV CLASS=REFBODY>
Jakob Cederlund - support@erlang.ericsson.se<BR>

</DIV>
<CENTER>
<HR>
<SMALL>stdlib 1.14.2<BR>
Copyright &copy; 1991-2006
<A HREF="http://www.erlang.se">Ericsson AB</A><BR>
</SMALL>
</CENTER>
</BODY>
</HTML>