erl_tar(3erl)						     Erlang Module Definition						     erl_tar(3erl)

NAME

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

DESCRIPTION

       The  erl_tar  module archives and extract files to and from a tar file. The tar file format is the POSIX extended tar file format specified
       in IEEE Std 1003.1 and ISO/IEC 9945-1. That is the same format as used by tar program on Solaris, but is not the same as used  by  the  GNU
       tar program.

       By convention, the name of a tar file should end in " .tar ". To abide to the convention, you'll need to add " .tar " yourself to the name.

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

       Alternatively, for more control, the open , add/3,4 , and close/1 functions can be used.

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

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

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

LIMITATIONS

       For maximum compatibility, it is safe to archive files with names up to 100 characters in length. Such tar files can generally be extracted
       by any tar program.

       If filenames exceed 100 characters in length, the resulting tar file can only be correctly extracted  by  a  POSIX-compatible  tar  program
       (such as Solaris tar ), not by GNU tar.

       File have longer names than 256 bytes cannot be stored at all.

       The filename of the file a symbolic link points is always limited to 100 characters.

EXPORTS

       add(TarDescriptor, Filename, Options) -> RetValue

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

	      The add/3 function adds a file to a tar file that has been opened for writing by open/1 .

		dereference :
		  By  default, symbolic links will be stored as symbolic links in the tar file. Use the dereference option to override the default
		  and store the file that the symbolic link points to into the tar file.

		verbose :
		  Print an informational message about the file being added.

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

	      The add/4 function adds a file to a tar file that has been opened for writing by open/1 . It accepts the same options as add/3 .

	      NameInArchive is the name under which the file will be stored in the tar file. That is the name that the file will get when it  will
	      be extracted from the tar file.

       close(TarDescriptor)

	      Types  TarDescriptor = term()

	      The close/1 function closes a tar file opened by open/1 .

       create(Name, FileList) ->RetValue

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

	      The  create/2  function creates a tar file and archives the files whose names are given in FileList into it. The files may either be
	      read from disk or given as binaries.

       create(Name, FileList, OptionList)

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

	      The create/3 function creates a tar file and archives the files whose names are given in FileList into it. The files may	either	be
	      read from disk or given as binaries.

	      The options in OptionList modify the defaults as follows.

		compressed :
		  The  entire  tar file will be compressed, as if it has been run through the gzip program. To abide to the convention that a com-
		  pressed tar file should end in " .tar.gz " or " .tgz ", you'll need to add the appropriate extension yourself.

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

		dereference :
		  By  default, symbolic links will be stored as symbolic links in the tar file. Use the dereference option to override the default
		  and store the file that the symbolic link points to into the tar file.

		verbose :
		  Print an informational message about each file being added.

       extract(Name) -> RetValue

	      Types  Name = filename()
		     RetValue = ok|{error,{Name,Reason}}
		     Reason = term()

	      The extract/1 function extracts all files from a tar archive.

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

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

	      Otherwise, Name should be a filename.

       extract(Name, OptionList)

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

	      The extract/2 function extracts files from a tar archive.

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

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

	      Otherwise, Name should be a filename.

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

		{cwd,Cwd} :
		  Files with relative filenames will by default be extracted to the current working directory. Given  the  {cwd,Cwd}  option,  the
		  extract/2 function will extract into the directory Cwd instead of to the current working directory.

		{files,FileList} :
		  By  default,	all  files  will  be extracted from the tar file. Given the {files,Files} option, the extract/2 function will only
		  extract the files whose names are included in FileList .

		compressed :
		  Given the compressed option, the extract/2 function will uncompress the file while extracting If the tar file  is  not  actually
		  compressed, the compressed will effectively be ignored.

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

		memory :
		  Instead of extracting to a 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 tar file.

		keep_old_files :
		  By  default,	all existing files with the same name as file in the tar file will be overwritten Given the keep_old_files option,
		  the extract/2 function will not overwrite any existing files.

		verbose :
		  Print an informational message as each file is being extracted.

       format_error(Reason) -> string()

	      Types  Reason = term()

	      The format_error/1 converts an error reason term to a human-readable error message string.

       open(Name, OpenModeList) -> RetValue

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

	      The open/2 function creates a tar file for writing. (Any existing file with the same name will be truncated.)

	      By convention, the name of a tar file should end in " .tar ". To abide to the convention, you'll need to add " .tar  "  yourself	to
	      the name.

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

		compressed :
		  The  entire  tar file will be compressed, as if it has been run through the gzip program. To abide to the convention that a com-
		  pressed tar file should end in " .tar.gz " or " .tgz ", you'll need to add the appropriate extension yourself.

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

	      Use  the	add/3,4  functions  to add one file at the time into an opened tar file. When you are finished adding files, use the close
	      function to close the tar file.

   Warning:
       The TarDescriptor term is not a file descriptor. You should not rely on the specific contents of the TarDescriptor term, as it  may  change
       in future versions as more features are added to the erl_tar module.

       table(Name) -> RetValue

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

	      The table/1 function retrieves the names of all files in the tar file Name .

       table(Name, Options)

	      Types  Name = filename()

	      The table/2 function retrieves the names of all files in the tar file Name .

       t(Name)

	      Types  Name = filename()

	      The t/1 function prints the names of all files in the tar file Name to the Erlang shell. (Similar to " tar t ".)

       tt(Name)

	      Types  Name = filename()

	      The tt/1 function prints names and information about all files in the tar file Name to the Erlang shell. (Similar to " tar tv ".)

Ericsson AB							   stdlib 1.17.3						     erl_tar(3erl)