NAME

       tar_open, tar_close - access a tar archive via a handle

SYNOPSIS

       #include <libtar.h>

       int tar_open(TAR **t, char *pathname, tartype_t *type, int oflags, int mode, int options);

       int tar_fdopen(TAR **t, int fd, char *pathname, tartype_t *type, int oflags, int mode, int options);

       int tar_fd(TAR *t");"

       int tar_close(TAR *t");"

VERSION

       This man page documents version 1.2 of libtar.

DESCRIPTION

       The  tar_open()  function  opens  a  tar archive file corresponding to the filename named by the pathname
       argument.  The oflags argument must be either O_RDONLY or O_WRONLY.

       The type argument specifies the access methods for the given file  type.   The  tartype_t  structure  has
       members  named  openfunc,  closefunc, readfunc() and writefunc(), which are pointers to the functions for
       opening, closing, reading, and writing the file, respectively.  If type is NULL, the file  type  defaults
       to a normal file, and the standard open(), close(), read(), and write() functions are used.

       The options argument is a logical-or'ed combination of zero or more of the following:

       TAR_GNU
              Use GNU extensions.

       TAR_VERBOSE
              Send status messages to stdout.

       TAR_NOOVERWRITE
              Do not overwrite pre-existing files.

       TAR_IGNORE_EOT
              Skip all-zero blocks instead of treating them as EOT.

       TAR_IGNORE_MAGIC
              Do not validate the magic field in file headers.

       TAR_CHECK_VERSION
              Check the version field in file headers.  (This field is normally ignored.)

       TAR_IGNORE_CRC
              Do not validate the CRC of file headers.

       The tar_open() function allocates memory for a TAR handle, and a pointer to the allocated memory is saved
       in the location specified by t.  The TAR handle may be passed to other libtar calls to modify the  opened
       tar  archive.   The TAR handle maintains all of the information about the open tar archive, including the
       archive type, options, and oflags selected when tar_open() was called.

       The TAR handle generated by tar_open() contains a file header structure.  When  reading  a  tar  archive,
       this structure contains the last file header read from the tar archive.  When writing a tar archive, this
       structure is used as a staging area to construct the next file header to be written to the  archive.   In
       addition,  the  TAR  handle  contains  a  hash  table which is used to keep track of the device and inode
       information for each file which gets written to the tar archive.  This is used to detect hard  links,  so
       that files do not need to be duplicated in the archive.

       The  tar_fdopen()  function  is  identical  to  the  tar_open()  function,  except that fd is used as the
       previously-opened file descriptor for the tar file instead of calling type->openfunc() to open the file.

       The tar_fd() function returns the file descriptor associated with the TAR handle t.

       The tar_close() function closes the file descriptor associated with  the  TAR  handle  t  and  frees  all
       dynamically-allocated memory.

RETURN VALUE

       The  tar_open(), tar_fdopen(), and tar_close() functions return 0 on success.  On failure, they return -1
       and set errno.

       The tar_fd() function returns the file descriptor associated with the TAR handle t.

ERRORS

       tar_open() will fail if:

       EINVAL The oflags argument was something other than O_RDONLY or O_WRONLY.

       In addition, tar_open() and tar_close() may fail if it cannot allocate memory using calloc(), or  if  the
       open or close functions for the specified tar archive type fail.

SEE ALSO

       open(2), close(2), calloc(3)