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)