Provided by: erlang-manpages_22.0.7+dfsg-1_all bug

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, USTAR, and PAX, as well as some  of  GNU
       tar's extensions to the USTAR format (sparse files most notably). It produces tar archives
       in USTAR format, unless the files being archived require PAX format due to restrictions 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 extract 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 Erlang 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 extracted 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 option dereference.

                verbose:
                  Prints an informational message about the added file.

                {chunks,ChunkSize}:
                  Reads data in parts from the file. This is intended for memory-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 written. 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  specified  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 specified 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 option 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 writing the  file.  That
              is,  absolute  paths  will  be  turned  into  relative 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|verbose|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 (Erlang) 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,Reason}

              Types:

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

              The  Fun  is  the  definition  of  what to do when the different storage 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 function.

                (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 writing  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 default and opens the tar file without option raw.

              To add one file at the time into an opened tar file, use function 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").