archivers/libarchive/files/doc/text/archive_write_disk.3.txt

   1 archive_write_disk(3)  FreeBSD Library Functions Manual  archive_write_disk(3)
   2
   3 NAME
   4      archive_write_disk_new, archive_write_disk_set_options,
   5      archive_write_disk_set_skip_file, archive_write_disk_set_group_lookup,
   6      archive_write_disk_set_standard_lookup,
   7      archive_write_disk_set_user_lookup, archive_write_header,
   8      archive_write_data, archive_write_finish_entry, archive_write_close,
   9      archive_write_finish -- functions for creating objects on disk
  10
  11 SYNOPSIS
  12      #include <archive.h>
  13
  14      struct archive *
  15      archive_write_disk_new(void);
  16
  17      int
  18      archive_write_disk_set_options(struct archive *, int flags);
  19
  20      int
  21      archive_write_disk_set_skip_file(struct archive *, dev_t, ino_t);
  22
  23      int
  24      archive_write_disk_set_group_lookup(struct archive *, void *,
  25          gid_t (*)(void *, const char *gname, gid_t gid),
  26          void (*cleanup)(void *));
  27
  28      int
  29      archive_write_disk_set_standard_lookup(struct archive *);
  30
  31      int
  32      archive_write_disk_set_user_lookup(struct archive *, void *,
  33          uid_t (*)(void *, const char *uname, uid_t uid),
  34          void (*cleanup)(void *));
  35
  36      int
  37      archive_write_header(struct archive *, struct archive_entry *);
  38
  39      ssize_t
  40      archive_write_data(struct archive *, const void *, size_t);
  41
  42      int
  43      archive_write_finish_entry(struct archive *);
  44
  45      int
  46      archive_write_close(struct archive *);
  47
  48      int
  49      archive_write_finish(struct archive *);
  50
  51 DESCRIPTION
  52      These functions provide a complete API for creating objects on disk from
  53      struct archive_entry descriptions.  They are most naturally used when
  54      extracting objects from an archive using the archive_read() interface.
  55      The general process is to read struct archive_entry objects from an ar-
  56      chive, then write those objects to a struct archive object created using
  57      the archive_write_disk() family functions.  This interface is deliber-
  58      ately very similar to the archive_write() interface used to write objects
  59      to a streaming archive.
  60
  61      archive_write_disk_new()
  62              Allocates and initializes a struct archive object suitable for
  63              writing objects to disk.
  64
  65      archive_write_disk_set_skip_file()
  66              Records the device and inode numbers of a file that should not be
  67              overwritten.  This is typically used to ensure that an extraction
  68              process does not overwrite the archive from which objects are
  69              being read.  This capability is technically unnecessary but can
  70              be a significant performance optimization in practice.
  71
  72      archive_write_disk_set_options()
  73              The options field consists of a bitwise OR of one or more of the
  74              following values:
  75              ARCHIVE_EXTRACT_OWNER
  76                      The user and group IDs should be set on the restored
  77                      file.  By default, the user and group IDs are not
  78                      restored.
  79              ARCHIVE_EXTRACT_PERM
  80                      Full permissions (including SGID, SUID, and sticky bits)
  81                      should be restored exactly as specified, without obeying
  82                      the current umask.  Note that SUID and SGID bits can only
  83                      be restored if the user and group ID of the object on
  84                      disk are correct.  If ARCHIVE_EXTRACT_OWNER is not speci-
  85                      fied, then SUID and SGID bits will only be restored if
  86                      the default user and group IDs of newly-created objects
  87                      on disk happen to match those specified in the archive
  88                      entry.  By default, only basic permissions are restored,
  89                      and umask is obeyed.
  90              ARCHIVE_EXTRACT_TIME
  91                      The timestamps (mtime, ctime, and atime) should be
  92                      restored.  By default, they are ignored.  Note that
  93                      restoring of atime is not currently supported.
  94              ARCHIVE_EXTRACT_NO_OVERWRITE
  95                      Existing files on disk will not be overwritten.  By
  96                      default, existing regular files are truncated and over-
  97                      written; existing directories will have their permissions
  98                      updated; other pre-existing objects are unlinked and
  99                      recreated from scratch.
 100              ARCHIVE_EXTRACT_UNLINK
 101                      Existing files on disk will be unlinked before any
 102                      attempt to create them.  In some cases, this can prove to
 103                      be a significant performance improvement.  By default,
 104                      existing files are truncated and rewritten, but the file
 105                      is not recreated.  In particular, the default behavior
 106                      does not break existing hard links.
 107              ARCHIVE_EXTRACT_ACL
 108                      Attempt to restore ACLs.  By default, extended ACLs are
 109                      ignored.
 110              ARCHIVE_EXTRACT_FFLAGS
 111                      Attempt to restore extended file flags.  By default, file
 112                      flags are ignored.
 113              ARCHIVE_EXTRACT_XATTR
 114                      Attempt to restore POSIX.1e extended attributes.  By
 115                      default, they are ignored.
 116              ARCHIVE_EXTRACT_SECURE_SYMLINKS
 117                      Refuse to extract any object whose final location would
 118                      be altered by a symlink on disk.  This is intended to
 119                      help guard against a variety of mischief caused by ar-
 120                      chives that (deliberately or otherwise) extract files
 121                      outside of the current directory.  The default is not to
 122                      perform this check.  If ARCHIVE_EXTRACT_UNLINK is speci-
 123                      fied together with this option, the library will remove
 124                      any intermediate symlinks it finds and return an error
 125                      only if such symlink could not be removed.
 126              ARCHIVE_EXTRACT_SECURE_NODOTDOT
 127                      Refuse to extract a path that contains a .. element any-
 128                      where within it.  The default is to not refuse such
 129                      paths.  Note that paths ending in .. always cause an
 130                      error, regardless of this flag.
 131
 132      archive_write_disk_set_group_lookup(),
 133              archive_write_disk_set_user_lookup()
 134              The struct archive_entry objects contain both names and ids that
 135              can be used to identify users and groups.  These names and ids
 136              describe the ownership of the file itself and also appear in ACL
 137              lists.  By default, the library uses the ids and ignores the
 138              names, but this can be overridden by registering user and group
 139              lookup functions.  To register, you must provide a lookup func-
 140              tion which accepts both a name and id and returns a suitable id.
 141              You may also provide a void * pointer to a private data structure
 142              and a cleanup function for that data.  The cleanup function will
 143              be invoked when the struct archive object is destroyed.
 144
 145      archive_write_disk_set_standard_lookup()
 146              This convenience function installs a standard set of user and
 147              group lookup functions.  These functions use getpwnam(3) and
 148              getgrnam(3) to convert names to ids, defaulting to the ids if the
 149              names cannot be looked up.  These functions also implement a sim-
 150              ple memory cache to reduce the number of calls to getpwnam(3) and
 151              getgrnam(3).
 152
 153      archive_write_header()
 154              Build and write a header using the data in the provided struct
 155              archive_entry structure.  See archive_entry(3) for information on
 156              creating and populating struct archive_entry objects.
 157
 158      archive_write_data()
 159              Write data corresponding to the header just written.  Returns
 160              number of bytes written or -1 on error.
 161
 162      archive_write_finish_entry()
 163              Close out the entry just written.  Ordinarily, clients never need
 164              to call this, as it is called automatically by
 165              archive_write_next_header() and archive_write_close() as needed.
 166
 167      archive_write_close()
 168              Set any attributes that could not be set during the initial
 169              restore.  For example, directory timestamps are not restored ini-
 170              tially because restoring a subsequent file would alter that time-
 171              stamp.  Similarly, non-writable directories are initially created
 172              with write permissions (so that their contents can be restored).
 173              The archive_write_disk_new library maintains a list of all such
 174              deferred attributes and sets them when this function is invoked.
 175
 176      archive_write_finish()
 177              Invokes archive_write_close() if it was not invoked manually,
 178              then releases all resources.
 179      More information about the struct archive object and the overall design
 180      of the library can be found in the libarchive(3) overview.  Many of these
 181      functions are also documented under archive_write(3).
 182
 183 RETURN VALUES
 184      Most functions return ARCHIVE_OK (zero) on success, or one of several
 185      non-zero error codes for errors.  Specific error codes include:
 186      ARCHIVE_RETRY for operations that might succeed if retried, ARCHIVE_WARN
 187      for unusual conditions that do not prevent further operations, and
 188      ARCHIVE_FATAL for serious errors that make remaining operations impossi-
 189      ble.  The archive_errno() and archive_error_string() functions can be
 190      used to retrieve an appropriate error code and a textual error message.
 191
 192      archive_write_disk_new() returns a pointer to a newly-allocated struct
 193      archive object.
 194
 195      archive_write_data() returns a count of the number of bytes actually
 196      written.  On error, -1 is returned and the archive_errno() and
 197      archive_error_string() functions will return appropriate values.
 198
 199 SEE ALSO
 200      archive_read(3), archive_write(3), tar(1), libarchive(3)
 201
 202 HISTORY
 203      The libarchive library first appeared in FreeBSD 5.3.  The
 204      archive_write_disk interface was added to libarchive 2.0 and first
 205      appeared in FreeBSD 6.3.
 206
 207 AUTHORS
 208      The libarchive library was written by Tim Kientzle <kientzle@acm.org>.
 209
 210 BUGS
 211      Directories are actually extracted in two distinct phases.  Directories
 212      are created during archive_write_header(), but final permissions are not
 213      set until archive_write_close().  This separation is necessary to cor-
 214      rectly handle borderline cases such as a non-writable directory contain-
 215      ing files, but can cause unexpected results.  In particular, directory
 216      permissions are not fully restored until the archive is closed.  If you
 217      use chdir(2) to change the current directory between calls to
 218      archive_read_extract() or before calling archive_read_close(), you may
 219      confuse the permission-setting logic with the result that directory per-
 220      missions are restored incorrectly.
 221
 222      The library attempts to create objects with filenames longer than
 223      PATH_MAX by creating prefixes of the full path and changing the current
 224      directory.  Currently, this logic is limited in scope; the fixup pass
 225      does not work correctly for such objects and the symlink security check
 226      option disables the support for very long pathnames.
 227
 228      Restoring the path aa/../bb does create each intermediate directory.  In
 229      particular, the directory aa is created as well as the final object bb.
 230      In theory, this can be exploited to create an entire directory heirarchy
 231      with a single request.  Of course, this does not work if the
 232      ARCHIVE_EXTRACT_NODOTDOT option is specified.
 233
 234      Implicit directories are always created obeying the current umask.
 235      Explicit objects are created obeying the current umask unless
 236      ARCHIVE_EXTRACT_PERM is specified, in which case they current umask is
 237      ignored.
 238
 239      SGID and SUID bits are restored only if the correct user and group could
 240      be set.  If ARCHIVE_EXTRACT_OWNER is not specified, then no attempt is
 241      made to set the ownership.  In this case, SGID and SUID bits are restored
 242      only if the user and group of the final object happen to match those
 243      specified in the entry.
 244
 245      The ``standard'' user-id and group-id lookup functions are not the
 246      defaults because getgrnam(3) and getpwnam(3) are sometimes too large for
 247      particular applications.  The current design allows the application
 248      author to use a more compact implementation when appropriate.
 249
 250      There should be a corresponding archive_read_disk interface that walks a
 251      directory heirarchy and returns archive entry objects.
 252
 253 FreeBSD 6.0                      March 2, 2007                     FreeBSD 6.0