Skip site navigation (1)Skip section navigation (2)

FreeBSD Man Pages

Man Page or Keyword Search:
Man Architecture
Apropos Keyword Search (all sections) Output format
home | help
archive_write(3)       FreeBSD Library Functions Manual       archive_write(3)

NAME
     archive_write_new, archive_write_set_format_cpio,
     archive_write_set_format_pax, archive_write_set_format_pax_restricted,
     archive_write_set_format_shar, archive_write_set_format_shar_binary,
     archive_write_set_format_ustar, archive_write_set_bytes_per_block,
     archive_write_set_bytes_in_last_block, archive_write_set_compressor_gzip,
     archive_write_set_compressor_bzip2, archive_write_open,
     archive_write_open_fd, archive_write_open_file, archive_write_prepare,
     archive_write_header, archive_write_data, archive_write_close,
     archive_write_finish - functions for creating archives

SYNOPSIS
     #include <archive.h>

     struct archive *
     archive_write_new(void);

     int
     archive_write_set_bytes_per_block(archive *, int bytes_per_block);

     int
     archive_write_set_bytes_in_last_block(archive *, int);

     int
     archive_write_set_compressor_gzip(struct archive *);

     int
     archive_write_set_compressor_bzip2(struct archive *);

     int
     archive_write_set_format_cpio(struct archive *);

     int
     archive_write_set_format_pax(struct archive *);

     int
     archive_write_set_format_pax_restricted(struct archive *);

     int
     archive_write_set_format_shar(struct archive *);

     int
     archive_write_set_format_shar_binary(struct archive *);

     int
     archive_write_set_format_ustar(struct archive *);

     int
     archive_write_open(struct archive *, void *client_data,
         archive_write_archive_callback *, archive_open_archive_callback *,
         archive_close_archive_callback *);

     int
     archive_write_open_fd(struct archive *, int fd);

     int
     archive_write_open_file(struct archive *, const char *filename);

     int
     archive_write_header(struct archive *);

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

     int
     archive_write_close(struct archive *);

     void
     archive_write_finish(struct archive *);

DESCRIPTION
     These functions provide a complete API for creating streaming archive
     files.  The general process is to first create the struct archive object,
     set any desired options, initialize the archive, append entries, then
     close the archive and release all resources.  The following summary
     describes the functions in approximately the order they are ordinarily
     used:

     archive_write_new()
             Allocates and initializes a struct archive object suitable for
             writing a tar archive.

     archive_write_set_bytes_per_block()
             Sets the block size used for writing the archive data.  Every
             call to the write callback function, except possibly the last
             one, will use this value for the length.  The third parameter is
             a boolean that specifies whether or not the final block written
             will be padded to the full block size.  If it is zero, the last
             block will not be padded.  If it is non-zero, padding will be
             added both before and after compression.  The default is to use a
             block size of 10240 bytes and to pad the last block.

     archive_write_set_bytes_in_last_block()
             Sets the block size used for writing the last block.  If this
             value is zero, the last block will be padded to the same size as
             the other blocks.  Otherwise, the final block will be padded to a
             multiple of this size.  In particular, setting it to 1 will cause
             the final block to not be padded.  For compressed output, any
             padding generated by this option is applied only after the
             compression.  The uncompressed data is always unpadded.  The
             default is to pad the last block to the full block size (note
             that archive_write_open_file() will set this based on the file
             type).  Unlike the other ``set'' functions, this function can be
             called after the archive is opened.

     archive_write_set_format_cpio(), archive_write_set_format_pax(),
             archive_write_set_format_pax_restricted(),
             archive_write_set_format_shar(),
             archive_write_set_format_shar_binary(),
             archive_write_set_format_ustar()
             Sets the format that will be used for the archive.  The library
             can write POSIX octet-oriented cpio format archives, POSIX-
             standard ``pax interchange'' format archives, traditional
             ``shar'' archives, enhanced ``binary'' shar archives that store a
             variety of file attributes and handle binary files, and POSIX-
             standard ``ustar'' archives.  The pax interchange format is a
             backwards-compatible tar format that adds key/value attributes to
             each entry and supports arbitrary filenames, linknames, uids,
             sizes, etc.  ``Restricted pax interchange format'' is the library
             default; this is the same as pax format, but suppresses the pax
             extended header for most normal files.  In most cases, this will
             result in ordinary ustar archives.

     archive_write_set_compression_gzip(),
             archive_write_set_compression_bzip2()
             The resulting archive will be compressed as specified.  Note that
             the compressed output is always properly blocked.

     archive_write_open()
             Freeze the settings, open the archive, and prepare for writing
             entries.  This is the most generic form of this function, which
             accepts pointers to three callback functions which will be
             invoked by the compression layer to write the constructed
             archive.  In order to support external compression programs, the
             compression is permitted to fork and invoke the callbacks from a
             separate process.  In particular, clients should not assume that
             they can communicate between the callbacks and the mainline code
             using shared variables.  (The standard gzip, bzip2, and "none"
             compression methods do not fork.)

     archive_write_open_fd()
             A convenience form of archive_write_open() that accepts a file
             descriptor.

     archive_write_open_file()
             A convenience form of archive_write_open() that accepts a
             filename.  A NULL argument indicates that the output should be
             written to standard output; an argument of ``-'' will open a file
             with that name.  If you have not invoked
             archive_write_set_bytes_in_last_block(), then
             archive_write_open_file() will adjust the last-block padding
             depending on the file: it will enable padding when writing to
             standard output or to a character or block device node, it will
             disable padding otherwise.  You can override this by manually
             invoking archive_write_set_bytes_in_last_block() either before or
             after calling archive_write_open().

     archive_write_header()
             Build and write a header using the data in the provided struct
             archive_entry structure.

     archive_write_data()
             Write data corresponding to the header just written.

     archive_write_close()
             Complete the archive and invoke the close callback.

     archive_write_finish()
             Invokes archive_write_close() if it wasn't invoked manually, then
             release all resources.

     The callback functions are defined as follows:

           typedef ssize_t archive_write_archive_callback(struct archive *,
           void *client_data, void *buffer, size_t length)

           typedef int archive_open_archive_callback(struct archive *, void
           *client_data)

           typedef int archive_close_archive_callback(struct archive *, void
           *client_data)
     For correct blocking, each call to the write callback function should
     translate into a single write(2) system call.  This is especially
     critical when writing tar archives to tape drives.

     More information about tar archive formats and blocking can be found in
     the tar(5) manual page.

     More information about the struct archive object and the overall design
     of the library can be found in the libarchive(3) overview.

IMPLEMENTATION
     Compression support is built-in to libarchive, which uses zlib and bzlib
     to handle gzip and bzip2 compression, respectively.

EXAMPLE
     The following sketch illustrates basic usage of the library.  In this
     example, the callback functions are simply wrappers around the standard
     open(2), write(2), and close(2) system calls.

           void
           write_archive(const char **filename)
           {
             struct mydata *mydata = malloc(sizeof(struct mydata));
             struct archive *a;
             struct archive_entry *entry;
             struct stat st;
             char buff[8192];
             int len;

             a = archive_write_new();
             mydata->name = name;
             archive_write_set_compression_gzip(a);
             archive_write_set_format_ustar(a);
             archive_write_open(a, mydata, myopen, mywrite, myclose);
             while (*filename) {
               stat(*filename, &st);
               entry = archive_entry_new();
               archive_entry_copy_stat(entry, &st);
               archive_entry_set_pathname(entry, *filename);
               archive_write_header(a, entry);
               fd = open(*filename, O_RDONLY);
               len = read(fd, buff, sizeof(buff));
               while ( len >= 0 ) {
                   archive_write_data(a, buff, len);
                   len = read(fd, buff, sizeof(buff));
               }
               archive_entry_free(entry);
               filename++;
             }
             archive_write_finish(a);
           }

           int
           myopen(struct archive *a, void *client_data)
           {
             struct mydata *mydata = client_data;

             mydata->fd = open(mydata->name, O_WRONLY | O_CREAT, 0644);
             return (mydata->fd >= 0);
           }

           ssize_t
           mywrite(struct archive *a, void *client_data, void *buff, size_t n)
           {
             struct mydata *mydata = client_data;

             return (write(mydata->fd, buff, n));
           }

           int
           myclose(struct archive *a, void *client_data)
           {
             struct mydata *mydata = client_data;

             if (mydata->fd > 0)
               close(mydata->fd);
             return (0);
           }

RETURN VALUES
     Most functions return zero on success, non-zero on error.  The
     archive_errno() and archive_error_string() functions can be used to
     retrieve an appropriate error code and a textual error message.

     archive_write_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.  Note
     that if the client-provided write callback function returns -1, that
     error will be propagated back to the caller through whatever API function
     resulted in that call, which may include archive_write_header(),
     archive_write_data(), or archive_write_close().  In such a case, the
     archive_errno() or archive_error_string() fields will not return useful
     information; you should use client-private data to return error
     information back to your mainline code.

SEE ALSO
     tar(1), libarchive(3), tar(5)

HISTORY
     The libarchive library first appeared in FreeBSD 5.3.

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

BUGS
     There are many peculiar bugs in historic tar implementations that may
     cause certain programs to reject archives written by this library.  For
     example, several historic implementations calculated header checksums
     incorrectly and will thus reject valid archives; GNU tar does not fully
     support pax interchange format; some old tar implementations required
     specific field terminations.

     The default pax interchange format eliminates most of the historic tar
     limitations and provides a generic key/value attribute facility for
     vendor-defined extensions.  One oversight in POSIX is the failure to
     provide a standard attribute for large device numbers.  This library uses
     ``SCHILY.devminor'' and ``SCHILY.devmajor'' for device numbers that
     exceed the range supported by the backwards-compatible ustar header.
     These keys are compatible with Joerg Schilling's star archiver.  Other
     implementations may not recognize these keys and will thus be unable to
     correctly restore large device numbers archived by this library.

FreeBSD 11.0-PRERELEASE         October 1, 2003        FreeBSD 11.0-PRERELEASE

NAME | SYNOPSIS | DESCRIPTION | IMPLEMENTATION | EXAMPLE | RETURN VALUES | SEE ALSO | HISTORY | AUTHORS | BUGS

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=archive_write&sektion=3&manpath=FreeBSD+5.3-RELEASE>

home | help