Unix/Linux Go Back    


Linux 2.6 - man page for zip (linux section 3erl)

Linux & Unix Commands - Search Man Pages
Man Page or Keyword Search:   man
Select Man Page Set:       apropos Keyword Search (sections above)


zip(3erl)			     Erlang Module Definition				zip(3erl)

NAME
       zip - Utility for reading and creating 'zip' archives.

DESCRIPTION
       The  zip  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.

       The zip module supports zip archive versions up to 6.1. However,  password-protection  and
       Zip64 is 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 .

       To return a list of the files in a zip archive, use the list_dir/1 or the list_dir/2 func-
       tion. (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 sup-
       ported.

       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_file()

       The record zip_file contains the following fields.

	 name = string() :
	   the name of the file

	 info = file_info() :
	   file info as in file:read_file_info/1

	 comment = string() :
	   the comment for the file in the zip archive

	 offset = integer() :
	   the offset of the file in the zip archive (used internally)

	 comp_size = integer() :
	   the compressed size of the file (the uncompressed size is found in info )

       zip_comment

       The record zip_comment just contains the archive comment for a zip archive

	 comment = string() :
	   the comment for the zip archive

EXPORTS
       zip(Name, FileList) -> RetValue
       zip(Name, FileList, Options) -> RetValue
       create(Name, FileList) -> RetValue
       create(Name, FileList, Options) -> RetValue

	      Types  Name = filename()
		     FileList = [FileSpec]
		     FileSpec = filename() |  {filename(),  binary()}  |  {filename(),	binary(),
		     #file_info{}}
		     Options = [Option]
		     Option = memory | cooked | verbose | {comment, Comment} | {cwd, CWD} | {com-
		     press, What} | {uncompress, What}
		     What = all | [Extension] | {add, [Extension]} | {del, [Extension]}
		     Extension = string()
		     Comment = CWD = string()
		     RetValue = {ok, Name} | {ok, {Name, binary()}} | {error, Reason}
		     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 App-
	      note.txt file. However, files will be stored without compression	if  they  already
	      are  compressed.	The  zip/2 and zip/3 checks 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 that 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 that 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 = filename() | binary()
		     Options = [Option]
		     Option = {file_list,  FileList}  |  keep_old_files  |  verbose  |	memory	|
		     {file_filter, FileFilter} | {cwd, CWD}
		     FileList = [filename()]
		     FileBinList = [{filename(),binary()}]
		     FileFilter = fun(ZipFile) -> true | false
		     CWD = string()
		     ZipFile = zip_file()
		     RetValue  =  {ok,FileList}  |  {ok,FileBinList}  | {error, Reason} | {error,
		     {Name, Reason}}
		     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 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. Not 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 con-
		  taining 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 = filename()
		     GetInfo = fun() -> #file_info{}
		     GetBin = fun() -> binary()
		     Acc0 = Acc1 = AccIn = AccOut = term()
		     Archive = filename() | {filename(), binary()}

	      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)
       table(Archive) -> RetValue
       table(Archive, Options)

	      Types  Archive = filename() | binary()
		     RetValue = {ok, [Comment, Files]} | {error, Reason}
		     Comment = zip_comment()
		     Files = [zip_file()]
		     Options = [Option]
		     Option = cooked
		     Reason = term()

	      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 com-
	      ment 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 zip file without the
		  raw option.

       t(Archive)

	      Types  Archive = filename() | 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)

	      Types  Archive = filename() | binary()

	      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 = filename() | binary()
		     Options = [Option]
		     Options = cooked | memory | {cwd, CWD}
		     CWD = string()
		     ZipHandle = pid()

	      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 unzip-
	      ping files one at a time with unzip .

	      The archive must be closed with zip_close/1 .

       zip_list_dir(ZipHandle) -> Result | {error, Reason}

	      Types  Result = [ZipComment, ZipFile...]
		     ZipComment = #zip_comment{}
		     ZipFile = #zip_file{}
		     ZipHandle = pid()

	      The zip_list_dir/1 function returns the file list of an open zip archive.

       zip_get(ZipHandle) -> {ok, [Result]} | {error, Reason}
       zip_get(FileName, ZipHandle) -> {ok, Result} | {error, Reason}

	      Types  FileName = filename()
		     ZipHandle = pid()
		     Result = filename() | {filename(), binary()}

	      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.

Ericsson AB				  stdlib 1.17.3 				zip(3erl)
Unix & Linux Commands & Man Pages : ©2000 - 2018 Unix and Linux Forums


All times are GMT -4. The time now is 06:12 AM.