doc/tar_extract_file.3

   1 .TH tar_extract_file 3 "Jan 2001" "University of Illinois" "C Library Calls"
   2 .SH NAME
   3 tar_extract_file, tar_extract_regfile, tar_extract_hardlink,
   4 tar_extract_symlink, tar_extract_chardev, tar_extract_blockdev,
   5 tar_extract_dir, tar_extract_fifo, tar_skip_regfile, tar_set_file_perms \-
   6 extract files from a tar archive
   7 .SH SYNOPSIS
   8 .B #include <libtar.h>
   9 .P
  10 .BI "int tar_extract_file(TAR *" t ", char *" realname ");"
  11
  12 .BI "int tar_extract_regfile(TAR *" t ", char *" realname ");"
  13
  14 .BI "int tar_skip_regfile(TAR *" t ");"
  15
  16 .BI "int tar_extract_dir(TAR *" t ", char *" realname ");"
  17
  18 .BI "int tar_extract_hardlink(TAR *" t ", char *" realname ");"
  19
  20 .BI "int tar_extract_symlink(TAR *" t ", char *" realname ");"
  21
  22 .BI "int tar_extract_blockdev(TAR *" t ", char *" realname ");"
  23
  24 .BI "int tar_extract_chardev(TAR *" t ", char *" realname ");"
  25
  26 .BI "int tar_extract_fifo(TAR *" t ", char *" realname ");"
  27
  28 .BI "int tar_set_file_perms(TAR *" t ", char *" realname ");"
  29 .SH VERSION
  30 This man page documents version 1.2 of \fBlibtar\fP.
  31 .SH DESCRIPTION
  32 The \fBtar_extract_file\fP() function acts as a front-end to the other
  33 \fBtar_extract_*\fP() functions.  It checks the current tar header
  34 associated with the \fITAR\fP handle \fIt\fP (which must be initialized
  35 first by calling \fBth_read\fP()) to determine what kind of file the
  36 header refers to.  It then calls the appropriate \fBtar_extract_*\fP()
  37 function to extract that kind of file.
  38
  39 The \fBtar_skip_regfile\fP() function skips over the
  40 file content blocks and positions the file pointer at the expected
  41 location of the next tar header block.
  42
  43 The \fBtar_set_file_perms\fP() function sets the attributes of the
  44 extracted file to match the encoded values.  This includes the file's
  45 modification time, mode, owner, and group.  This function is automatically
  46 called by \fBtar_extract_file\fP(), but applications which call the
  47 other \fBtar_extract_*\fP() functions directly will need to call
  48 \fBtar_set_file_perms\fP() manually if this behavior is desired.
  49 .SH RETURN VALUES
  50 On successful completion, the functions documented here will
  51 return 0.  On failure, they will return \-1 and set \fIerrno\fP to an
  52 appropriate value.
  53
  54 The \fBtar_extract_dir\fP() function will return 1 if the directory
  55 already exists.
  56 .SH ERRORS
  57 The \fBtar_extract_file\fP() function will fail if:
  58 .IP \fBEEXIST\fP
  59 If the \fBO_NOOVERWRITE\fP flag is set and the file already exists.
  60 .PP
  61 The \fBtar_extract_*\fP() functions will fail if:
  62 .IP \fBEINVAL\fP
  63 An entry could not be added to the internal file hash.
  64 .IP \fBEINVAL\fP
  65 Less than \fBT_BLOCKSIZE\fP bytes were read from the tar archive.
  66 .IP \fBEINVAL\fP
  67 The current file header associated with \fIt\fP refers to a kind of file
  68 other than the one which the called function knows about.
  69 .PP
  70 They may also fail if any of the following functions fail: \fBmkdir\fP(),
  71 \fBwrite\fP(), \fBlink\fP(), \fBsymlink\fP(), \fBmknod\fP(), \fBmkfifo\fP(),
  72 \fButime\fP(), \fBchown\fP(), \fBlchown\fP(), \fBchmod\fP(), or \fBlstat\fP().
  73 .SH SEE ALSO
  74 .BR mkdir (2),
  75 .BR write (2),
  76 .BR link (2),
  77 .BR symlink (2),
  78 .BR mknod (2),
  79 .BR mkfifo (2),
  80 .BR utime (2),
  81 .BR chown (2),
  82 .BR lchown (2),
  83 .BR chmod (2),
  84 .BR lstat (2)