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

FreeBSD Manual Pages

  
 
  

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

NAME
       erl_tar - Unix 'tar' utility for	reading	and writing tar	archives.

DESCRIPTION
       This  module  archives  and  extract files to and from a	tar file. This
       module supports reading most common tar formats,	namely v7,  STAR,  US-
       TAR, and	PAX, as	well as	some of	GNU tar's extensions to	the USTAR for-
       mat (sparse files most notably).	It produces tar	archives in USTAR for-
       mat, unless the files being archived require PAX	format due to restric-
       tions in	USTAR (such as unicode metadata, filename length,  and	more).
       As  such, erl_tar supports tar archives produced	by most	all modern tar
       utilities, and produces tarballs	which should be	similarly portable.

       By convention, the name of a tar	file is	to end in ".tar". To abide  to
       the convention, add ".tar" to the name.

       Tar  files  can	be created in one operation using function create/2 or
       create/3.

       Alternatively, for more control,	use  functions	open/2,	 add/3,4,  and
       close/1.

       To  extract  all	 files from a tar file,	use function extract/1.	To ex-
       tract only some files or	to be able to specify some more	 options,  use
       function	extract/2.

       To  return  a  list of the files	in a tar file, use function table/1 or
       table/2.	To print a list	of files to the	Erlang shell, use function t/1
       or tt/1.

       To  convert an error term returned from one of the functions above to a
       readable	message, use function format_error/1.

UNICODE	SUPPORT
       If file:native_name_encoding/0 returns utf8, path names are encoded  in
       UTF-8 when creating tar files, and path names are assumed to be encoded
       in UTF-8	when extracting	tar files.

       If file:native_name_encoding/0 returns latin1, no translation  of  path
       names is	done.

       Unicode metadata	stored in PAX headers is preserved

OTHER STORAGE MEDIA
       The  ftp	 module	 normally accesses the tar file	on disk	using the file
       module. When other needs	arise, you can define your own	low-level  Er-
       lang functions to perform the writing and reading on the	storage	media;
       use function init/3.

       An example of this is the SFTP  support	in  ssh_sftp:open_tar/3.  This
       function	opens a	tar file on a remote machine using an SFTP channel.

LIMITATIONS
	 * If  you  must remain	compatible with	the USTAR tar format, you must
	   ensure file paths being stored are less than	255  bytes  in	total,
	   with	a maximum filename component length of 100 bytes. USTAR	uses a
	   header field	(prefix) in addition to	the  name  field,  and	splits
	   file	paths longer than 100 bytes into two parts. This split is done
	   on a	directory boundary, and	is done	in such	a way to make the best
	   use	of  the	 space	available in those two fields, but in practice
	   this	will often mean	that you have less than	255 bytes for a	 path.
	   erl_tar  will  automatically	 upgrade  the  format to PAX to	handle
	   longer filenames, so	this is	only an	issue if you need  to  extract
	   the	archive	 with  an older	implementation of erl_tar or tar which
	   does	not support PAX. In this case, the PAX	headers	 will  be  ex-
	   tracted as regular files, and you will need to apply	them manually.

	 * Like	 the above, if you must	remain USTAR compatible, you must also
	   ensure than paths for symbolic/hard links  are  no  more  than  100
	   bytes, otherwise PAX	headers	will be	used.

EXPORTS
       add(TarDescriptor, Filename, Options) ->	RetValue

	      Types:

		 TarDescriptor = term()
		 FilenameOrBin = filename()|binary()
		 NameInArchive = filename()
		 Filename = filename()|{NameInArchive,FilenameOrBin}
		 Options = [Option]
		 Option	= dereference|verbose|{chunks,ChunkSize}
		 |{atime,non_neg_integer()}|{mtime,non_neg_integer()}
		 |{ctime,non_neg_integer()}|{uid,non_neg_integer()}
		 |{gid,non_neg_integer()}
		 ChunkSize = positive_integer()
		 RetValue = ok|{error,{Filename,Reason}}
		 Reason	= term()

	      Adds  a  file  to	a tar file that	has been opened	for writing by
	      open/1.

	      NameInArchive is the name	under which the	file becomes stored in
	      the  tar file. The file gets this	name when it is	extracted from
	      the tar file.

	      Options:

		dereference:
		  By default, symbolic links are stored	as symbolic  links  in
		  the  tar  file.  To  override	the default and	store the file
		  that the symbolic link points	to into	the tar	file, use  op-
		  tion dereference.

		verbose:
		  Prints an informational message about	the added file.

		{chunks,ChunkSize}:
		  Reads	data in	parts from the file. This is intended for mem-
		  ory-limited machines that, for example, builds a tar file on
		  a remote machine over	SFTP, see ssh_sftp:open_tar/3.

		{atime,non_neg_integer()}:
		  Sets	the last time, as  POSIX time, when the	file was read.
		  See also file:read_file_info/1.

		{mtime,non_neg_integer()}:
		  Sets the last	time, as  POSIX	time, when the file was	 writ-
		  ten. See also	file:read_file_info/1.

		{ctime,non_neg_integer()}:
		  Sets	the  time,  as	POSIX time, when the file was created.
		  See also file:read_file_info/1.

		{uid,non_neg_integer()}:
		  Sets the file	owner. file:read_file_info/1.

		{gid,non_neg_integer()}:
		  Sets	the  group   that   the	  file	 owner	 belongs   to.
		  file:read_file_info/1.

       add(TarDescriptor, FilenameOrBin, NameInArchive,	Options) -> RetValue

	      Types:

		 TarDescriptor = term()
		 FilenameOrBin = filename()|binary()
		 Filename = filename()
		 NameInArchive = filename()
		 Options = [Option]
		 Option	= dereference|verbose
		 RetValue = ok|{error,{Filename,Reason}}
		 Reason	= term()

	      Adds  a  file  to	a tar file that	has been opened	for writing by
	      open/2. This function accepts the	same options as	add/3.

       close(TarDescriptor)

	      Types:

		 TarDescriptor = term()

	      Closes a tar file	opened by open/2.

       create(Name, FileList) ->RetValue

	      Types:

		 Name =	filename()
		 FileList = [Filename|{NameInArchive, FilenameOrBin}]
		 FilenameOrBin = filename()|binary()
		 Filename = filename()
		 NameInArchive = filename()
		 RetValue = ok|{error,{Name,Reason}}
		 Reason	= term()

	      Creates a	tar file and archives the files	whose names are	speci-
	      fied in FileList into it.	The files can either be	read from disk
	      or be specified as binaries.

       create(Name, FileList, OptionList)

	      Types:

		 Name =	filename()
		 FileList = [Filename|{NameInArchive, FilenameOrBin}]
		 FilenameOrBin = filename()|binary()
		 Filename = filename()
		 NameInArchive = filename()
		 OptionList = [Option]
		 Option	= compressed|cooked|dereference|verbose
		 RetValue = ok|{error,{Name,Reason}}
		 Reason	= term()

	      Creates a	tar file and archives the files	whose names are	speci-
	      fied in FileList into it.	The files can either be	read from disk
	      or be specified as binaries.

	      The options in OptionList	modify the defaults as follows:

		compressed:
		  The entire tar file is compressed, as	if  it	has  been  run
		  through  the gzip program. To	abide to the convention	that a
		  compressed tar file is to end	in ".tar.gz"  or  ".tgz",  add
		  the appropriate extension.

		cooked:
		  By  default, function	open/2 opens the tar 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 tar	file without option raw.

		dereference:
		  By default, symbolic links are stored	as symbolic  links  in
		  the  tar  file.  To  override	the default and	store the file
		  that the symbolic link points	to into	the tar	file, use  op-
		  tion dereference.

		verbose:
		  Prints an informational message about	each added file.

       extract(Name) ->	RetValue

	      Types:

		 Name =	filename() | {binary,binary()} | {file,Fd}
		 Fd = file_descriptor()
		 RetValue = ok|{error,{Name,Reason}}
		 Reason	= term()

	      Extracts all files from a	tar archive.

	      If  argument  Name is specified as {binary,Binary}, the contents
	      of the binary is assumed to be a tar archive.

	      If argument Name is specified as {file,Fd}, Fd is	assumed	to  be
	      a	file descriptor	returned from function file:open/2.

	      Otherwise, Name is to be a filename.

	  Note:
	      Leading slashes in tar member names will be removed before writ-
	      ing the file. That is, absolute paths will be turned into	 rela-
	      tive  paths.  There will be an info message written to the error
	      logger when paths	are changed in this way.

       extract(Name, OptionList)

	      Types:

		 Name =	filename() | {binary,binary()} | {file,Fd}
		 Fd = file_descriptor()
		 OptionList = [Option]
		 Option	   =	{cwd,Cwd}|{files,FileList}|keep_old_files|ver-
		 bose|memory
		 Cwd = [dirname()]
		 FileList = [filename()]
		 RetValue = ok|MemoryRetValue|{error,{Name,Reason}}
		 MemoryRetValue	= {ok, [{NameInArchive,binary()}]}
		 NameInArchive = filename()
		 Reason	= term()

	      Extracts files from a tar	archive.

	      If  argument  Name is specified as {binary,Binary}, the contents
	      of the binary is assumed to be a tar archive.

	      If argument Name is specified as {file,Fd}, Fd is	assumed	to  be
	      a	file descriptor	returned from function file:open/2.

	      Otherwise, Name is to be a filename.

	      The  following options modify the	defaults for the extraction as
	      follows:

		{cwd,Cwd}:
		  Files	with relative filenames	are by	default	 extracted  to
		  the  current	working	directory. With	this option, files are
		  instead extracted into directory Cwd.

		{files,FileList}:
		  By default, all files	are extracted from the tar file.  With
		  this	option,	only those files are extracted whose names are
		  included in FileList.

		compressed:
		  With this option, the	file is	uncompressed while extracting.
		  If the tar file is not compressed, this option is ignored.

		cooked:
		  By  default,	function open/2	function opens the tar file in
		  raw mode, which is faster but	does not allow a  remote  (Er-
		  lang)	file server to be used.	Adding cooked to the mode list
		  overrides the	default	and opens the tar file without	option
		  raw.

		memory:
		  Instead  of extracting to a directory, this option gives 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 tar file.

		keep_old_files:
		  By default, all existing files with the same name  as	 files
		  in  the tar file are overwritten. With this option, existing
		  files	are not	overwriten.

		verbose:
		  Prints an informational message for each extracted file.

       format_error(Reason) -> string()

	      Types:

		 Reason	= term()

	      Converts an error	reason term to a human-readable	error  message
	      string.

       init(UserPrivate,  AccessMode, Fun) -> {ok,TarDescriptor} | {error,Rea-
       son}

	      Types:

		 UserPrivate = term()
		 AccessMode = [write] |	[read]
		 Fun  when  AccessMode	is  [write]  =	fun(write,   {UserPri-
		 vate,DataToWrite})->...;	  (position,{UserPrivate,Posi-
		 tion})->...; (close, UserPrivate)->...	end
		 Fun  when  AccessMode	is  [read]  =	fun(read2,   {UserPri-
		 vate,Size})->...;     (position,{UserPrivate,Position})->...;
		 (close, UserPrivate)->... end
		 TarDescriptor = term()
		 Reason	= term()

	      The Fun is the definition	of what	to do when the different stor-
	      age  operations  functions  are to be called from	the higher tar
	      handling functions (such as add/3, add/4,	and close/1).

	      The Fun is called	when the tar function wants to do a  low-level
	      operation,  like writing a block to a file. The Fun is called as
	      Fun(Op, {UserPrivate,Parameters...}), where Op is	the  operation
	      name,  UserPrivate  is  the term passed as the first argument to
	      init/1 and Parameters... are the data added by the tar  function
	      to be passed down	to the storage handling	function.

	      Parameter	 UserPrivate is	typically the result of	opening	a low-
	      level structure like a file descriptor or	an  SFTP  channel  id.
	      The different Fun	clauses	operate	on that	very term.

	      The following are	the fun	clauses	parameter lists:

		(write,	{UserPrivate,DataToWrite}):
		  Writes term DataToWrite using	UserPrivate.

		(close,	UserPrivate):
		  Closes the access.

		(read2,	{UserPrivate,Size}):
		  Reads	 using	UserPrivate  but  only Size bytes. Notice that
		  there	is only	an arity-2 read	function, not an arity-1 func-
		  tion.

		(position,{UserPrivate,Position}):
		  Sets	the  position  of  UserPrivate as defined for files in
		  file:position/2

	      Example:

	      The following is a complete Fun parameter	for reading and	 writ-
	      ing on files using the file module:

	      ExampleFun =
		 fun(write, {Fd,Data}) ->  file:write(Fd, Data);
		    (position, {Fd,Pos}) -> file:position(Fd, Pos);
		    (read2, {Fd,Size}) -> file:read(Fd,	Size);
		    (close, Fd)	-> file:close(Fd)
		 end

	      Here Fd was specified to function	init/3 as:

	      {ok,Fd} =	file:open(Name,	...).
	      {ok,TarDesc} = erl_tar:init(Fd, [write], ExampleFun),

	      TarDesc is then used:

	      erl_tar:add(TarDesc, SomeValueIwantToAdd,	FileNameInTarFile),
	      erl_tar:close(TarDesc)

	      When  the	 erl_tar  core wants to, for example, write a piece of
	      Data, it would call ExampleFun(write, {UserPrivate,Data}).

	  Note:
	      This example with	the file module	operations is not necessary to
	      use directly, as that is what function open/2 in principle does.

	  Warning:
	      The TarDescriptor	term is	not a file descriptor. You are advised
	      not to rely on the specific contents of this  term,  as  it  can
	      change  in  future  Erlang/OTP  releases	when more features are
	      added to this module.

       open(Name, OpenModeList)	-> RetValue

	      Types:

		 Name =	filename()
		 OpenModeList =	[OpenMode]
		 Mode =	write|compressed|cooked
		 RetValue = {ok,TarDescriptor}|{error,{Name,Reason}}
		 TarDescriptor = term()
		 Reason	= term()

	      Creates a	tar file for writing (any existing file	with the  same
	      name is truncated).

	      By  convention,  the  name of a tar file is to end in ".tar". To
	      abide to the convention, add ".tar" to the name.

	      Except for the write atom, the following atoms can be  added  to
	      OpenModeList:

		compressed:
		  The  entire  tar  file  is compressed, as if it has been run
		  through the gzip program. To abide to	the convention that  a
		  compressed  tar  file	 is to end in ".tar.gz"	or ".tgz", add
		  the appropriate extension.

		cooked:
		  By default, the tar file is opened 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  de-
		  fault	and opens the tar file without option raw.

	      To  add  one file	at the time into an opened tar file, use func-
	      tion add/3,4. When you are finished adding files,	 use  function
	      close/1 to close the tar file.

	  Warning:
	      The TarDescriptor	term is	not a file descriptor. You are advised
	      not to rely on the specific contents of this  term,  as  it  can
	      change  in  future  Erlang/OTP  releases	when more features are
	      added to this module..

       table(Name) -> RetValue

	      Types:

		 Name =	filename()|{binary,binary()}|{file,file_descriptor()}
		 RetValue = {ok,[string()]}|{error,{Name,Reason}}
		 Reason	= term()

	      Retrieves	the names of all files in the tar file Name.

       table(Name, Options)

	      Types:

		 Name =	filename()|{binary,binary()}|{file,file_descriptor()}

	      Retrieves	the names of all files in the tar file Name.

       t(Name)

	      Types:

		 Name =	filename()|{binary,binary()}|{file,file_descriptor()}

	      Prints the names of all files in the tar file Name to the	Erlang
	      shell (similar to	"tar t").

       tt(Name)

	      Types:

		 Name =	filename()|{binary,binary()}|{file,file_descriptor()}

	      Prints  names  and  information  about all files in the tar file
	      Name to the Erlang shell (similar	to "tar	tv").

Ericsson AB			  stdlib 3.8			    erl_tar(3)

NAME | DESCRIPTION | UNICODE SUPPORT | OTHER STORAGE MEDIA | LIMITATIONS | EXPORTS

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

home | help