doc/text/archive_write.3.txt

   1 ARCHIVE_WRITE(3)         BSD Library Functions Manual         ARCHIVE_WRITE(3)
   2
   3 NAME
   4      archive_write — functions for creating archives
   5
   6 LIBRARY
   7      Streaming Archive Library (libarchive, -larchive)
   8
   9 SYNOPSIS
  10      #include <archive.h>
  11
  12 DESCRIPTION
  13      These functions provide a complete API for creating streaming archive
  14      files.  The general process is to first create the struct archive object,
  15      set any desired options, initialize the archive, append entries, then
  16      close the archive and release all resources.
  17
  18    Create archive object
  19      See archive_write_new(3).
  20
  21      To write an archive, you must first obtain an initialized struct archive
  22      object from archive_write_new().
  23
  24    Enable filters and formats, configure block size and padding
  25      See archive_write_filter(3), archive_write_format(3) and
  26      archive_write_blocksize(3).
  27
  28      You can then modify this object for the desired operations with the vari‐
  29      ous archive_write_set_XXX() functions.  In particular, you will need to
  30      invoke appropriate archive_write_add_XXX() and archive_write_set_XXX()
  31      functions to enable the corresponding compression and format support.
  32
  33    Set options
  34      See archive_write_set_options(3).
  35
  36    Open archive
  37      See archive_write_open(3).
  38
  39      Once you have prepared the struct archive object, you call
  40      archive_write_open() to actually open the archive and prepare it for
  41      writing.  There are several variants of this function; the most basic ex‐
  42      pects you to provide pointers to several functions that can provide
  43      blocks of bytes from the archive.  There are convenience forms that allow
  44      you to specify a filename, file descriptor, FILE * object, or a block of
  45      memory from which to write the archive data.
  46
  47    Produce archive
  48      See archive_write_header(3) and archive_write_data(3).
  49
  50      Individual archive entries are written in a three-step process: You first
  51      initialize a struct archive_entry structure with information about the
  52      new entry.  At a minimum, you should set the pathname of the entry and
  53      provide a struct stat with a valid st_mode field, which specifies the
  54      type of object and st_size field, which specifies the size of the data
  55      portion of the object.
  56
  57    Release resources
  58      See archive_write_free(3).
  59
  60      After all entries have been written, use the archive_write_free() func‐
  61      tion to release all resources.
  62
  63 EXAMPLES
  64      The following sketch illustrates basic usage of the library.  In this ex‐
  65      ample, the callback functions are simply wrappers around the standard
  66      open(2), write(2), and close(2) system calls.
  67
  68            #ifdef __linux__
  69            #define _FILE_OFFSET_BITS 64
  70            #endif
  71            #include <sys/stat.h>
  72            #include <archive.h>
  73            #include <archive_entry.h>
  74            #include <fcntl.h>
  75            #include <stdlib.h>
  76            #include <unistd.h>
  77
  78            struct mydata {
  79              const char *name;
  80              int fd;
  81            };
  82
  83            int
  84            myopen(struct archive *a, void *client_data)
  85            {
  86              struct mydata *mydata = client_data;
  87
  88              mydata->fd = open(mydata->name, O_WRONLY | O_CREAT, 0644);
  89              if (mydata->fd >= 0)
  90                return (ARCHIVE_OK);
  91              else
  92                return (ARCHIVE_FATAL);
  93            }
  94
  95            la_ssize_t
  96            mywrite(struct archive *a, void *client_data, const void *buff, size_t n)
  97            {
  98              struct mydata *mydata = client_data;
  99
 100              return (write(mydata->fd, buff, n));
 101            }
 102
 103            int
 104            myclose(struct archive *a, void *client_data)
 105            {
 106              struct mydata *mydata = client_data;
 107
 108              if (mydata->fd > 0)
 109                close(mydata->fd);
 110              return (0);
 111            }
 112
 113            void
 114            write_archive(const char *outname, const char **filename)
 115            {
 116              struct mydata *mydata = malloc(sizeof(struct mydata));
 117              struct archive *a;
 118              struct archive_entry *entry;
 119              struct stat st;
 120              char buff[8192];
 121              int len;
 122              int fd;
 123
 124              a = archive_write_new();
 125              mydata->name = outname;
 126              /* Set archive format and filter according to output file extension.
 127               * If it fails, set default format. Platform depended function.
 128               * See supported formats in archive_write_set_format_filter_by_ext.c */
 129              if (archive_write_set_format_filter_by_ext(a, outname) != ARCHIVE_OK)  {
 130                archive_write_add_filter_gzip(a);
 131                archive_write_set_format_ustar(a);
 132              }
 133              archive_write_open(a, mydata, myopen, mywrite, myclose);
 134              while (*filename) {
 135                stat(*filename, &st);
 136                entry = archive_entry_new();
 137                archive_entry_copy_stat(entry, &st);
 138                archive_entry_set_pathname(entry, *filename);
 139                archive_write_header(a, entry);
 140                if ((fd = open(*filename, O_RDONLY)) != -1) {
 141                  len = read(fd, buff, sizeof(buff));
 142                  while (len > 0) {
 143                    archive_write_data(a, buff, len);
 144                    len = read(fd, buff, sizeof(buff));
 145                  }
 146                  close(fd);
 147                }
 148                archive_entry_free(entry);
 149                filename++;
 150              }
 151              archive_write_free(a);
 152            }
 153
 154            int main(int argc, const char **argv)
 155            {
 156              const char *outname;
 157              argv++;
 158              outname = *argv++;
 159              write_archive(outname, argv);
 160              return 0;
 161            }
 162
 163 SEE ALSO
 164      tar(1), archive_write_set_options(3), libarchive(3), cpio(5), mtree(5),
 165      tar(5)
 166
 167 HISTORY
 168      The libarchive library first appeared in FreeBSD 5.3.
 169
 170 AUTHORS
 171      The libarchive library was written by Tim Kientzle <kientzle@acm.org>.
 172
 173 BUGS
 174      There are many peculiar bugs in historic tar implementations that may
 175      cause certain programs to reject archives written by this library.  For
 176      example, several historic implementations calculated header checksums in‐
 177      correctly and will thus reject valid archives; GNU tar does not fully
 178      support pax interchange format; some old tar implementations required
 179      specific field terminations.
 180
 181      The default pax interchange format eliminates most of the historic tar
 182      limitations and provides a generic key/value attribute facility for ven‐
 183      dor-defined extensions.  One oversight in POSIX is the failure to provide
 184      a standard attribute for large device numbers.  This library uses
 185      “SCHILY.devminor” and “SCHILY.devmajor” for device numbers that exceed
 186      the range supported by the backwards-compatible ustar header.  These keys
 187      are compatible with Joerg Schilling's star archiver.  Other implementa‐
 188      tions may not recognize these keys and will thus be unable to correctly
 189      restore device nodes with large device numbers from archives created by
 190      this library.
 191
 192 BSD                            February 2, 2012                            BSD