Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
zip(3)			   Erlang Module Definition			zip(3)

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

DESCRIPTION
       This  module archives and extracts files	to and from a zip archive. The
       zip format is specified by the "ZIP Appnote.txt"	file, available	on the
       PKWARE web site www.pkware.com.

       The  zip	module supports	zip archive versions up	to 6.1.	However, pass-
       word-protection and Zip64 are not supported.

       By convention, the name of a zip	file is	to end with .zip. To abide  to
       the convention, add .zip	to the filename.

	 * To  create zip archives, use	function zip/2 or zip/3. They are also
	   available as	create/2,3, to resemble	the erl_tar module.

	 * To extract files from a zip archive,	use function  unzip/1  or  un-
	   zip/2.  They	 are  also  available  as extract/1,2, to resemble the
	   erl_tar module.

	 * To fold a function over all files in	a zip  archive,	 use  function
	   foldl/3.

	 * To  return  a  list	of  the	 files	in a zip archive, use function
	   list_dir/1 or list_dir/2. They are also available as	table/1,2,  to
	   resemble the	erl_tar	module.

	 * To  print  a	list of	files to the Erlang shell, use function	t/1 or
	   tt/1.

	 * Sometimes it	is desirable to	open a zip archive, and	to unzip files
	   from	 it  file  by file, without having to reopen the archive. This
	   can be done by functions zip_open/1,2, zip_get/1,2, zip_list_dir/1,
	   and zip_close/1.

LIMITATIONS
	 * Zip64 archives are not supported.

	 * Password-protected and encrypted archives are not supported.

	 * Only	 the  DEFLATE  (zlib-compression)  and the STORE (uncompressed
	   data) zip methods are supported.

	 * The archive size is limited to 2 GB (32 bits).

	 * Comments for	individual files are not supported when	 creating  zip
	   archives. The zip archive comment for the whole zip archive is sup-
	   ported.

	 * Changing a zip archive is not supported. To add or  remove  a  file
	   from	an archive, the	whole archive must be recreated.

DATA TYPES
       zip_comment() = #zip_comment{comment = string()}

	      The  record  zip_comment only contains the archive comment for a
	      zip archive.

       zip_file() =
	   #zip_file{name = string(),
		     info = file:file_info(),
		     comment = string(),
		     offset = integer()	>= 0,
		     comp_size = integer() >= 0}

	      The record zip_file contains the following fields:

		name:
		  The filename

		info:
		  File information as in file:read_file_info/1 in Kernel

		comment:
		  The comment for the file in the zip archive

		offset:
		  The file offset in the zip archive (used internally)

		comp_size:
		  The size of the compressed file  (the	 size  of  the	uncom-
		  pressed file is found	in info)

       filename() = file:filename()

	      The name of a zip	file.

       extension() = string()

       extension_spec()	=
	   all |
	   [extension()] |
	   {add, [extension()]}	|
	   {del, [extension()]}

       create_option() =
	   memory |
	   cooked |
	   verbose |
	   {comment, string()} |
	   {cwd, file:filename()} |
	   {compress, extension_spec()}	|
	   {uncompress,	extension_spec()}

	      These options are	described in create/3.

       handle()

	      As returned by zip_open/2.

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

	      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 information	about the file.

	      GetBin returns the file contents.

	      Both GetInfo and GetBin must be called within the	Fun. Their be-
	      havior  is  undefined  if	they are called	outside	the context of
	      Fun.

	      The Fun must return a new	accumulator, which is  passed  to  the
	      next  call. foldl/3 returns the final accumulator	value. Acc0 is
	      returned if the archive is empty.	It is not necessary to iterate
	      over all files in	the archive. The iteration can be ended	prema-
	      turely in	a controlled manner by throwing	an exception.

	      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

	      list_dir/1 retrieves all filenames in the	zip archive Archive.

	      list_dir/2 provides options.

	      table/1 and table/2 are provided as  synonyms  to	 resemble  the
	      erl_tar module.

	      The  result  value  is the tuple {ok, List}, where List contains
	      the zip archive comment as the first element.

	      One option is available:

		cooked:
		  By default, this function opens 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  overrides
		  the default and opens	the zip	file without option raw.

       t(Archive) -> ok

	      Types:

		 Archive = file:name() | binary() | ZipHandle
		 ZipHandle = handle()

	      Prints  all  filenames  in the zip archive Archive to the	Erlang
	      shell. (Similar to tar t.)

       tt(Archive) -> ok

	      Types:

		 Archive = file:name() | binary() | ZipHandle
		 ZipHandle = handle()

	      Prints filenames and information about all files in the zip  ar-
	      chive Archive to the Erlang shell. (Similar to tar tv.)

       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 = file:filename()
		 ZipFile = zip_file()
		 RetValue =
		     {ok, FileList} |
		     {ok, FileBinList} |
		     {error, Reason :: term()} |
		     {error, {Name :: file:name(), Reason :: term()}}

	      unzip/1 extracts all files from a	zip archive.

	      unzip/2 provides options to extract some files, and more.

	      extract/1	 and  extract/2	 are  provided as synonyms to resemble
	      module erl_tar.

	      If argument Archive is specified as a binary,  the  contents  of
	      the binary is assumed to be a zip	archive, otherwise a filename.

	      Options:

		{file_list, FileList}:
		  By  default,	all  files are extracted from the zip archive.
		  With option {file_list, FileList}, function unzip/2 only ex-
		  tracts  the  files whose names are included in FileList. The
		  full paths, including	the names of all subdirectories	within
		  the zip archive, must	be specified.

		cooked:
		  By  default,	this  function opens 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 overrides
		  the default and opens	the zip	file without option  raw.  The
		  same applies for the files extracted.

		keep_old_files:
		  By default, all files	with the same name as files in the zip
		  archive are overwritten.  With  option  keep_old_files  set,
		  function  unzip/2  does not overwrite	existing files.	Notice
		  that even with option	memory specified, which	means that  no
		  files	 are overwritten, existing files are excluded from the
		  result.

		verbose:
		  Prints an informational message for each extracted file.

		memory:
		  Instead of extracting	to the current directory,  the	result
		  is  given  as	a list of tuples {Filename, Binary}, where Bi-
		  nary is a binary containing the extracted data of file File-
		  name in the zip archive.

		{cwd, CWD}:
		  Uses	the  specified	directory  as current directory. It is
		  prepended to filenames when extracting them from the zip ar-
		  chive.  (Acting  like	 file:set_cwd/1	in Kernel, but without
		  changing the global cwd property.)

       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	= create_option()
		 RetValue =
		     {ok, FileName :: filename()} |
		     {ok, {FileName :: filename(), binary()}} |
		     {error, Reason :: term()}

	      Creates  a  zip  archive	containing  the	 files	specified   in
	      FileList.

	      create/2	and create/3 are provided as synonyms to resemble mod-
	      ule erl_tar.

	      FileList is a list of files, with	paths relative to the  current
	      directory, which are stored with this path in the	archive. Files
	      can also be specified with data in binaries to create an archive
	      directly from data.

	      Files are	compressed using the DEFLATE compression, as described
	      in the "Appnote.txt" file. However,  files  are  stored  without
	      compression  if  they  are  already  compressed. zip/2 and zip/3
	      check the	file extension to determine  if	 the  file  is	to  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 control what
	      types  of	files that are to be compressed	by using options {com-
	      press, What} and {uncompress, What}. It is also possible to  use
	      many compress and	uncompress options.

	      To  trigger  file	compression, 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  extension  "gif"  are  com-
	      pressed.

	      Options:

		cooked:
		  By  default,	this  function opens the zip file in mode raw,
		  which	is faster but does not allow a	remote	(Erlang)  file
		  server  to be	used. Adding cooked to the mode	list overrides
		  the default and opens	the zip	file without the  raw  option.
		  The same applies for the files added.

		verbose:
		  Prints an informational message about	each added file.

		memory:
		  The  output  is not to a file, but instead as	a tuple	{File-
		  Name,	binary()}. The binary  is  a  full  zip	 archive  with
		  header and can be extracted with, for	example, unzip/2.

		{comment, Comment}:
		  Adds a comment to the	zip archive.

		{cwd, CWD}:
		  Uses	the  specified	directory  as  current	work directory
		  (cwd). This is prepended to filenames	when adding them,  al-
		  though not in	the zip	archive	(acting	like file:set_cwd/1 in
		  Kernel, but without changing the global cwd property.).

		{compress, What}:
		  Controls what	types of files to be compressed.  Defaults  to
		  all. The following values of What are	allowed:

		  all:
		    All	 files are compressed (as long as they pass the	uncom-
		    press condition).

		  [Extension]:
		    Only files with exactly these extensions are compressed.

		  {add,[Extension]}:
		    Adds these extensions to the list of compress extensions.

		  {del,[Extension]}:
		    Deletes these extensions from the list of compress	exten-
		    sions.

		{uncompress, What}:
		  Controls what	types of files to be uncompressed. Defaults to
		  [".Z", ".zip", ".zoo", ".arc", ".lzh", ".arj"]. The  follow-
		  ing values of	What are allowed:

		  all:
		    No files are compressed.

		  [Extension]:
		    Files with these extensions	are uncompressed.

		  {add,[Extension]}:
		    Adds  these	 extensions  to	 the list of uncompress	exten-
		    sions.

		  {del,[Extension]}:
		    Deletes these extensions from the list of  uncompress  ex-
		    tensions.

       zip_close(ZipHandle) -> ok | {error, einval}

	      Types:

		 ZipHandle = handle()

	      Closes  a	 zip archive, previously opened	with zip_open/1,2. All
	      resources	are closed, and	the handle is not  to  be  used	 after
	      closing.

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

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

	      Types:

		 FileName = file:name()
		 ZipHandle = handle()
		 Result	= file:name() |	{file:name(), binary()}
		 Reason	= term()

	      Extracts one or all files	from an	open archive.

	      The  files  are  unzipped	to memory or to	file, depending	on the
	      options specified	to function zip_open/1,2 when opening the  ar-
	      chive.

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

	      Types:

		 Result	= [zip_comment() | zip_file()]
		 ZipHandle = handle()
		 Reason	= term()

	      Returns the file list of an open zip archive. The	first returned
	      element is the zip archive comment.

       zip_open(Archive) -> {ok, ZipHandle} | {error, Reason}

       zip_open(Archive, Options) -> {ok, ZipHandle} | {error, Reason}

	      Types:

		 Archive = file:name() | binary()
		 ZipHandle = handle()
		 Options = [Option]
		 Option	= cooked | memory | {cwd, CWD :: file:filename()}
		 Reason	= term()

	      Opens a zip archive, and reads and  saves	 its  directory.  This
	      means  that  later reading files from the	archive	is faster than
	      unzipping	files one at a time with unzip/1,2.

	      The archive must be closed with zip_close/1.

	      The ZipHandle is closed if the process  that  originally	opened
	      the archive dies.

Ericsson AB			  stdlib 3.8				zip(3)

NAME | DESCRIPTION | LIMITATIONS | DATA TYPES | EXPORTS

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=zip&sektion=3&manpath=FreeBSD+12.1-RELEASE+and+Ports>

home | help