doc/tar_open.3

   1 .TH tar_open 3 "Jan 2001" "University of Illinois" "C Library Calls"
   2 .SH NAME
   3 tar_open, tar_close \- access a tar archive via a handle
   4 .SH SYNOPSIS
   5 .B #include <libtar.h>
   6 .P
   7 .BI "int tar_open(TAR **" t ", char *" pathname ","
   8 .BI "tartype_t *" type ", int " oflags ","
   9 .BI "int " mode ", int " options ");"
  10
  11 .BI "int tar_fdopen(TAR **" t ", int " fd ","
  12 .BI "char *" pathname ", tartype_t *" type ","
  13 .BI "int " oflags ", int " mode ","
  14 .BI "int " options ");"
  15
  16 .BI "int tar_fd(TAR *" t");"
  17
  18 .BI "int tar_close(TAR *" t");"
  19 .SH VERSION
  20 This man page documents version 1.2 of \fBlibtar\fP.
  21 .SH DESCRIPTION
  22 The \fBtar_open\fP() function opens a tar archive file corresponding to
  23 the filename named by the \fIpathname\fP argument.  The \fIoflags\fP
  24 argument must be either \fBO_RDONLY\fP or \fBO_WRONLY\fP.
  25
  26 The \fItype\fP argument specifies the access methods for the given file
  27 type.  The \fItartype_t\fP structure has members named \fIopenfunc\fP,
  28 \fIclosefunc\fP, \fIreadfunc\fP() and \fIwritefunc\fP(), which are
  29 pointers to the functions for opening, closing, reading, and writing
  30 the file, respectively.  If \fItype\fP is \fINULL\fP, the file type
  31 defaults to a normal file, and the standard \fIopen\fP(), \fIclose\fP(),
  32 \fIread\fP(), and \fIwrite\fP() functions are used.
  33
  34 The \fIoptions\fP argument is a logical-or'ed combination of zero or more
  35 of the following:
  36 .IP \fBTAR_GNU\fP
  37 Use GNU extensions.
  38 .IP \fBTAR_VERBOSE\fP
  39 Send status messages to \fIstdout\fP.
  40 .IP \fBTAR_NOOVERWRITE\fP
  41 Do not overwrite pre-existing files.
  42 .IP \fBTAR_IGNORE_EOT\fP
  43 Skip all-zero blocks instead of treating them as EOT.
  44 .IP \fBTAR_IGNORE_MAGIC\fP
  45 Do not validate the magic field in file headers.
  46 .IP \fBTAR_CHECK_VERSION\fP
  47 Check the version field in file headers.  (This field is normally ignored.)
  48 .IP \fBTAR_IGNORE_CRC\fP
  49 Do not validate the CRC of file headers.
  50 .PP
  51
  52 The \fBtar_open\fP() function allocates memory for a \fITAR\fP handle,
  53 and a pointer to the allocated memory is saved in the location specified
  54 by \fIt\fP.  The \fITAR\fP handle may be passed to other \fIlibtar\fP
  55 calls to modify the opened tar archive.  The \fITAR\fP handle maintains
  56 all of the information about the open tar archive, including the archive
  57 \fItype\fP, \fIoptions\fP, and \fIoflags\fP selected when \fBtar_open\fP()
  58 was called.
  59
  60 The \fITAR\fP handle generated by \fBtar_open\fP() contains a file header
  61 structure.  When reading a tar archive, this structure contains the last
  62 file header read from the tar archive.  When writing a tar archive,
  63 this structure is used as a staging area to construct the next file
  64 header to be written to the archive.  In addition, the \fITAR\fP handle
  65 contains a hash table which is used to keep track of the device and
  66 inode information for each file which gets written to the tar archive.
  67 This is used to detect hard links, so that files do not need to be
  68 duplicated in the archive.
  69
  70 The \fBtar_fdopen\fP() function is identical to the \fBtar_open\fP() function,
  71 except that \fIfd\fP is used as the previously-opened file descriptor for
  72 the tar file instead of calling \fItype->openfunc\fP() to open the file.
  73
  74 The \fBtar_fd\fP() function returns the file descriptor associated with
  75 the \fITAR\fP handle \fIt\fP.
  76
  77 The \fBtar_close\fP() function closes the file descriptor associated
  78 with the \fITAR\fP handle \fIt\fP and frees all dynamically-allocated
  79 memory.
  80 .SH RETURN VALUE
  81 The \fBtar_open\fP(), \fBtar_fdopen\fP(), and \fBtar_close\fP() functions
  82 return 0 on success.  On failure, they return \-1 and set \fIerrno\fP.
  83
  84 The \fBtar_fd\fP() function returns the file descriptor associated with
  85 the \fITAR\fP handle \fIt\fP.
  86 .SH ERRORS
  87 \fBtar_open\fP() will fail if:
  88 .IP \fBEINVAL\fP
  89 The \fIoflags\fP argument was something other than \fBO_RDONLY\fP or \fBO_WRONLY\fP.
  90 .PP
  91 In addition, \fBtar_open\fP() and \fBtar_close\fP() may fail if it
  92 cannot allocate memory using \fBcalloc\fP(), or if the
  93 open or close functions for the specified tar archive \fItype\fP fail.
  94 .SH SEE ALSO
  95 .BR open (2),
  96 .BR close (2),
  97 .BR calloc (3)