Provided by: erlang-manpages_16.b.3-dfsg-1ubuntu2_all bug

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}}
                 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}}
                 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 compressed 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 function 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 compressed 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".)