doc/tar_append_file.3

   1 .TH tar_append_file 3 "Jan 2001" "University of Illinois" "C Library Calls"
   2 .SH NAME
   3 tar_append_file, tar_append_eof, tar_append_regfile \- append data to tar archives
   4 .SH SYNOPSIS
   5 .B #include <libtar.h>
   6 .P
   7 .BI "int tar_append_file(TAR *" t ", char *" realname ","
   8 .BI "char *" savename ");"
   9
  10 .BI "int tar_append_regfile(TAR *" t ", char *" realname ");"
  11
  12 .BI "int tar_append_eof(TAR *" t ");"
  13 .SH VERSION
  14 This man page documents version 1.2 of \fBlibtar\fP.
  15 .SH DESCRIPTION
  16 The \fBtar_append_file\fP() function creates a tar file header block
  17 describing the file named by the \fIrealname\fP argument, but with
  18 the encoded filename of \fIsavename\fP.  It then sets the current
  19 header associated with the \fITAR\fP handle \fIt\fP to the newly created
  20 header block, and writes this block to the tar archive associated with
  21 \fIt\fP.  If the file named by \fIrealname\fP is a regular file (and
  22 is not encoded as a hard link), \fBtar_append_file\fP() will call
  23 \fBtar_append_regfile\fP() to append the contents of the file.
  24
  25 The \fBtar_append_regfile\fP() function appends the contents of a regular
  26 file to the tar archive associated with \fIt\fP.  Since this function is
  27 called by \fBtar_append_file\fP(), it should only be necessary for
  28 applications that construct and write the tar file header on their own.
  29
  30 The \fBtar_append_eof\fP() function writes an EOF marker (two blocks of
  31 all zeros) to the tar file associated with \fIt\fP.
  32 .SH RETURN VALUES
  33 On successful completion, these functions will return 0.  On failure,
  34 they will return \-1 and set \fIerrno\fP to an appropriate value.
  35 .SH ERRORS
  36 The \fBtar_append_*\fP() functions will fail if:
  37 .IP \fBEINVAL\fP
  38 Less than \fBT_BLOCKSIZE\fP bytes were written to the tar archive.
  39 .IP \fBEINVAL\fP
  40 Less than \fBT_BLOCKSIZE\fP bytes were read from the \fIrealname\fP file.
  41 .PP
  42 They may also fail if any of the following functions fail: \fBlstat\fP(),
  43 \fBmalloc\fP(), \fBopen\fP(), \fBread\fP(), \fBth_write\fP(), or the
  44 write function for the file type associated with the \fITAR\fP handle
  45 \fIt\fP.
  46 .SH SEE ALSO
  47 .BR read (2),
  48 .BR open (2),
  49 .BR lstat (2),
  50 .BR th_write (3)