archive_write_disk(3)    BSD Library Functions Manual    archive_write_disk(3)

NAME
     archive_write_disk_new, archive_write_disk_set_options,
     archive_write_disk_set_skip_file,
     archive_write_disk_set_group_lookup,
     archive_write_disk_set_standard_lookup,
     archive_write_disk_set_user_lookup, archive_write_header,
     archive_write_data, archive_write_finish_entry,
     archive_write_close, archive_write_finish - functions for
     creating objects on disk

SYNOPSIS
     #include <archive.h>

     struct archive *
     archive_write_disk_new(void);

     int
     archive_write_disk_set_options(struct archive *,
             int flags);

     int
     archive_write_disk_set_skip_file(struct archive *, dev_t,
             ino_t);

     int
     archive_write_disk_set_group_lookup(struct archive *,
             void *,
             gid_t (*)(void *, const char *gname, gid_t gid),
             void (*cleanup)(void *));

     int
     archive_write_disk_set_standard_lookup(struct archive *);

     int
     archive_write_disk_set_user_lookup(struct archive *,
             void *,
             uid_t (*)(void *, const char *uname, uid_t uid),
             void (*cleanup)(void *));

     int
     archive_write_header(struct archive *,
             struct archive_entry *);

     ssize_t
     archive_write_data(struct archive *, const void *,
             size_t);

     int
     archive_write_finish_entry(struct archive *);

     int
     archive_write_close(struct archive *);

     int
     archive_write_finish(struct archive *);

DESCRIPTION
     These functions provide a complete API for creating
     objects on disk from struct archive_entry descriptions.
     They are most naturally used when extracting objects from
     an archive using the archive_read() interface.  The gen-
     eral process is to read struct archive_entry objects from
     an archive, then write those objects to a struct archive
     object created using the archive_write_disk() family func-
     tions.  This interface is deliberately very similar to the
     archive_write() interface used to write objects to a
     streaming archive.

     archive_write_disk_new()
             Allocates and initializes a struct archive object
             suitable for writing objects to disk.

     archive_write_disk_set_skip_file()
             Records the device and inode numbers of a file
             that should not be overwritten.  This is typically
             used to ensure that an extraction process does not
             overwrite the archive from which objects are being
             read.  This capability is technically unnecessary
             but can be a significant performance optimization
             in practice.

     archive_write_disk_set_options()
             The options field consists of a bitwise OR of one
             or more of the following values:
             ARCHIVE_EXTRACT_OWNER
                     The user and group IDs should be set on
                     the restored file.  By default, the user
                     and group IDs are not restored.
             ARCHIVE_EXTRACT_PERM
                     Full permissions (including SGID, SUID,
                     and sticky bits) should be restored
                     exactly as specified, without obeying the
                     current umask.  Note that SUID and SGID
                     bits can only be restored if the user and
                     group ID of the object on disk are cor-
                     rect.  If ARCHIVE_EXTRACT_OWNER is not
                     specified, then SUID and SGID bits will
                     only be restored if the default user and
                     group IDs of newly-created objects on disk
                     happen to match those specified in the
                     archive entry.  By default, only basic
                     permissions are restored, and umask is
                     obeyed.
             ARCHIVE_EXTRACT_TIME
                     The timestamps (mtime, ctime, and atime)
                     should be restored.  By default, they are
                     ignored.  Note that restoring of atime is
                     not currently supported.
             ARCHIVE_EXTRACT_NO_OVERWRITE
                     Existing files on disk will not be over-
                     written.  By default, existing regular
                     files are truncated and overwritten;
                     existing directories will have their per-
                     missions updated; other pre-existing
                     objects are unlinked and recreated from
                     scratch.
             ARCHIVE_EXTRACT_UNLINK
                     Existing files on disk will be unlinked
                     before any attempt to create them.  In
                     some cases, this can prove to be a signif-
                     icant performance improvement.  By
                     default, existing files are truncated and
                     rewritten, but the file is not recreated.
                     In particular, the default behavior does
                     not break existing hard links.
             ARCHIVE_EXTRACT_ACL
                     Attempt to restore ACLs.  By default,
                     extended ACLs are ignored.
             ARCHIVE_EXTRACT_FFLAGS
                     Attempt to restore extended file flags.
                     By default, file flags are ignored.
             ARCHIVE_EXTRACT_XATTR
                     Attempt to restore POSIX.1e extended
                     attributes.  By default, they are ignored.
             ARCHIVE_EXTRACT_SECURE_SYMLINKS
                     Refuse to extract any object whose final
                     location would be altered by a symlink on
                     disk.  This is intended to help guard
                     against a variety of mischief caused by
                     archives that (deliberately or otherwise)
                     extract files outside of the current
                     directory.  The default is not to perform
                     this check.  If ARCHIVE_EXTRACT_UNLINK is
                     specified together with this option, the
                     library will remove any intermediate sym-
                     links it finds and return an error only if
                     such symlink could not be removed.
             ARCHIVE_EXTRACT_SECURE_NODOTDOT
                     Refuse to extract a path that contains a
                     .. element anywhere within it.  The
                     default is to not refuse such paths.  Note
                     that paths ending in .. always cause an
                     error, regardless of this flag.

     archive_write_disk_set_group_lookup(),
             archive_write_disk_set_user_lookup()
             The struct archive_entry objects contain both
             names and ids that can be used to identify users
             and groups.  These names and ids describe the own-
             ership of the file itself and also appear in ACL
             lists.  By default, the library uses the ids and
             ignores the names, but this can be overridden by
             registering user and group lookup functions.  To
             register, you must provide a lookup function which
             accepts both a name and id and returns a suitable
             id.  You may also provide a void * pointer to a
             private data structure and a cleanup function for
             that data.  The cleanup function will be invoked
             when the struct archive object is destroyed.

     archive_write_disk_set_standard_lookup()
             This convenience function installs a standard set
             of user and group lookup functions.  These func-
             tions use getpwnam(3) and getgrnam(3) to convert
             names to ids, defaulting to the ids if the names
             cannot be looked up.  These functions also imple-
             ment a simple memory cache to reduce the number of
             calls to getpwnam(3) and getgrnam(3).

     archive_write_header()
             Build and write a header using the data in the
             provided struct archive_entry structure.  See
             archive_entry(3) for information on creating and
             populating struct archive_entry objects.

     archive_write_data()
             Write data corresponding to the header just writ-
             ten.  Returns number of bytes written or -1 on
             error.

     archive_write_finish_entry()
             Close out the entry just written.  Ordinarily,
             clients never need to call this, as it is called
             automatically by archive_write_next_header() and
             archive_write_close() as needed.

     archive_write_close()
             Set any attributes that could not be set during
             the initial restore.  For example, directory
             timestamps are not restored initially because
             restoring a subsequent file would alter that
             timestamp.  Similarly, non-writable directories
             are initially created with write permissions (so
             that their contents can be restored).  The
             archive_write_disk_new library maintains a list of
             all such deferred attributes and sets them when
             this function is invoked.

     archive_write_finish()
             Invokes archive_write_close() if it was not
             invoked manually, then releases all resources.
     More information about the struct archive object and the
     overall design of the library can be found in the
     libarchive(3) overview.  Many of these functions are also
     documented under archive_write(3).

RETURN VALUES
     Most functions return ARCHIVE_OK (zero) on success, or one
     of several non-zero error codes for errors.  Specific
     error codes include: ARCHIVE_RETRY for operations that
     might succeed if retried, ARCHIVE_WARN for unusual condi-
     tions that do not prevent further operations, and
     ARCHIVE_FATAL for serious errors that make remaining oper-
     ations impossible.  The archive_errno() and
     archive_error_string() functions can be used to retrieve
     an appropriate error code and a textual error message.

     archive_write_disk_new() returns a pointer to a newly-
     allocated struct archive object.

     archive_write_data() returns a count of the number of
     bytes actually written.  On error, -1 is returned and the
     archive_errno() and archive_error_string() functions will
     return appropriate values.

SEE ALSO
     archive_read(3), archive_write(3), tar(1), libarchive(3)

HISTORY
     The libarchive library first appeared in FreeBSD 5.3.  The
     archive_write_disk interface was added to libarchive 2.0
     and first appeared in FreeBSD 6.3.

AUTHORS
     The libarchive library was written by Tim Kientzle
     <kientzle@acm.org>.

BUGS
     Directories are actually extracted in two distinct phases.
     Directories are created during archive_write_header(), but
     final permissions are not set until archive_write_close().
     This separation is necessary to correctly handle border-
     line cases such as a non-writable directory containing
     files, but can cause unexpected results.  In particular,
     directory permissions are not fully restored until the
     archive is closed.  If you use chdir(2) to change the cur-
     rent directory between calls to archive_read_extract() or
     before calling archive_read_close(), you may confuse the
     permission-setting logic with the result that directory
     permissions are restored incorrectly.

     The library attempts to create objects with filenames
     longer than PATH_MAX by creating prefixes of the full path
     and changing the current directory.  Currently, this logic
     is limited in scope; the fixup pass does not work cor-
     rectly for such objects and the symlink security check
     option disables the support for very long pathnames.

     Restoring the path aa/../bb does create each intermediate
     directory.  In particular, the directory aa is created as
     well as the final object bb.  In theory, this can be
     exploited to create an entire directory heirarchy with a
     single request.  Of course, this does not work if the
     ARCHIVE_EXTRACT_NODOTDOT option is specified.

     Implicit directories are always created obeying the cur-
     rent umask.  Explicit objects are created obeying the cur-
     rent umask unless ARCHIVE_EXTRACT_PERM is specified, in
     which case they current umask is ignored.

     SGID and SUID bits are restored only if the correct user
     and group could be set.  If ARCHIVE_EXTRACT_OWNER is not
     specified, then no attempt is made to set the ownership.
     In this case, SGID and SUID bits are restored only if the
     user and group of the final object happen to match those
     specified in the entry.

     The ``standard'' user-id and group-id lookup functions are
     not the defaults because getgrnam(3) and getpwnam(3) are
     sometimes too large for particular applications.  The cur-
     rent design allows the application author to use a more
     compact implementation when appropriate.

     There should be a corresponding archive_read_disk inter-
     face that walks a directory heirarchy and returns archive
     entry objects.

BSD                              March 2, 2007                             BSD
