DragonFly On-Line Manual Pages

tar_open(3)                     C Library Calls                    tar_open(3)

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)

University of Illinois             Jan 2001                        tar_open(3)