libtar/doc/tar_open.3

.TH tar_open 3 "Jan 2001" "University of Illinois" "C Library Calls"
.SH NAME
tar_open, tar_close \- access a tar archive via a handle
.SH SYNOPSIS
.B #include <libtar.h>
.P
.BI "int tar_open(TAR **" t ", char *" pathname ","
.BI "tartype_t *" type ", int " oflags ","
.BI "int " mode ", int " options ");"

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

.BI "int tar_fd(TAR *" t");"

.BI "int tar_close(TAR *" t");"
.SH VERSION
This man page documents version 1.2 of \fBlibtar\fP.
.SH DESCRIPTION
The \fBtar_open\fP() function opens a tar archive file corresponding to
the filename named by the \fIpathname\fP argument.  The \fIoflags\fP
argument must be either \fBO_RDONLY\fP or \fBO_WRONLY\fP.

The \fItype\fP argument specifies the access methods for the given file
type.  The \fItartype_t\fP structure has members named \fIopenfunc\fP,
\fIclosefunc\fP, \fIreadfunc\fP() and \fIwritefunc\fP(), which are
pointers to the functions for opening, closing, reading, and writing
the file, respectively.  If \fItype\fP is \fINULL\fP, the file type
defaults to a normal file, and the standard \fIopen\fP(), \fIclose\fP(),
\fIread\fP(), and \fIwrite\fP() functions are used.

The \fIoptions\fP argument is a logical-or'ed combination of zero or more
of the following:
.IP \fBTAR_GNU\fP
Use GNU extensions.
.IP \fBTAR_VERBOSE\fP
Send status messages to \fIstdout\fP.
.IP \fBTAR_NOOVERWRITE\fP
Do not overwrite pre-existing files.
.IP \fBTAR_IGNORE_EOT\fP
Skip all-zero blocks instead of treating them as EOT.
.IP \fBTAR_IGNORE_MAGIC\fP
Do not validate the magic field in file headers.
.IP \fBTAR_CHECK_VERSION\fP
Check the version field in file headers.  (This field is normally ignored.)
.IP \fBTAR_IGNORE_CRC\fP
Do not validate the CRC of file headers.
.PP

The \fBtar_open\fP() function allocates memory for a \fITAR\fP handle,
and a pointer to the allocated memory is saved in the location specified
by \fIt\fP.  The \fITAR\fP handle may be passed to other \fIlibtar\fP
calls to modify the opened tar archive.  The \fITAR\fP handle maintains
all of the information about the open tar archive, including the archive
\fItype\fP, \fIoptions\fP, and \fIoflags\fP selected when \fBtar_open\fP()
was called.

The \fITAR\fP handle generated by \fBtar_open\fP() 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 \fITAR\fP 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 \fBtar_fdopen\fP() function is identical to the \fBtar_open\fP() function,
except that \fIfd\fP is used as the previously-opened file descriptor for
the tar file instead of calling \fItype->openfunc\fP() to open the file.

The \fBtar_fd\fP() function returns the file descriptor associated with
the \fITAR\fP handle \fIt\fP.

The \fBtar_close\fP() function closes the file descriptor associated
with the \fITAR\fP handle \fIt\fP and frees all dynamically-allocated
memory.
.SH RETURN VALUE
The \fBtar_open\fP(), \fBtar_fdopen\fP(), and \fBtar_close\fP() functions
return 0 on success.  On failure, they return \-1 and set \fIerrno\fP.

The \fBtar_fd\fP() function returns the file descriptor associated with
the \fITAR\fP handle \fIt\fP.
.SH ERRORS
\fBtar_open\fP() will fail if:
.IP \fBEINVAL\fP
The \fIoflags\fP argument was something other than \fBO_RDONLY\fP or \fBO_WRONLY\fP.
.PP
In addition, \fBtar_open\fP() and \fBtar_close\fP() may fail if it
cannot allocate memory using \fBcalloc\fP(), or if the
open or close functions for the specified tar archive \fItype\fP fail.
.SH SEE ALSO
.BR open (2),
.BR close (2),
.BR calloc (3)