archivers/libarchive/files/doc/text/archive_write.3

   1 archive_write(3)       FreeBSD Library Functions Manual       archive_write(3)
   2
   3 NAME
   4      archive_write_new, archive_write_set_format_cpio,
   5      archive_write_set_format_pax, archive_write_set_format_pax_restricted,
   6      archive_write_set_format_shar, archive_write_set_format_shar_binary,
   7      archive_write_set_format_ustar, archive_write_get_bytes_per_block,
   8      archive_write_set_bytes_per_block, archive_write_set_bytes_in_last_block,
   9      archive_write_set_compression_bzip2,
  10      archive_write_set_compression_compress,
  11      archive_write_set_compression_gzip, archive_write_set_compression_none,
  12      archive_write_set_compression_program, archive_write_open,
  13      archive_write_open_fd, archive_write_open_FILE,
  14      archive_write_open_filename, archive_write_open_memory,
  15      archive_write_header, archive_write_data, archive_write_finish_entry,
  16      archive_write_close, archive_write_finish -- functions for creating ar-
  17      chives
  18
  19 SYNOPSIS
  20      #include <archive.h>
  21
  22      struct archive *
  23      archive_write_new(void);
  24
  25      int
  26      archive_write_get_bytes_per_block(struct archive *);
  27
  28      int
  29      archive_write_set_bytes_per_block(struct archive *, int bytes_per_block);
  30
  31      int
  32      archive_write_set_bytes_in_last_block(struct archive *, int);
  33
  34      int
  35      archive_write_set_compression_bzip2(struct archive *);
  36
  37      int
  38      archive_write_set_compression_compress(struct archive *);
  39
  40      int
  41      archive_write_set_compression_gzip(struct archive *);
  42
  43      int
  44      archive_write_set_compression_none(struct archive *);
  45
  46      int
  47      archive_write_set_compression_program(struct archive *,
  48          const char * cmd);
  49
  50      int
  51      archive_write_set_format_cpio(struct archive *);
  52
  53      int
  54      archive_write_set_format_pax(struct archive *);
  55
  56      int
  57      archive_write_set_format_pax_restricted(struct archive *);
  58
  59      int
  60      archive_write_set_format_shar(struct archive *);
  61
  62      int
  63      archive_write_set_format_shar_binary(struct archive *);
  64
  65      int
  66      archive_write_set_format_ustar(struct archive *);
  67
  68      int
  69      archive_write_open(struct archive *, void *client_data,
  70          archive_open_callback *, archive_write_callback *,
  71          archive_close_callback *);
  72
  73      int
  74      archive_write_open_fd(struct archive *, int fd);
  75
  76      int
  77      archive_write_open_FILE(struct archive *, FILE *file);
  78
  79      int
  80      archive_write_open_filename(struct archive *, const char *filename);
  81
  82      int
  83      archive_write_open_memory(struct archive *, void *buffer,
  84          size_t bufferSize, size_t *outUsed);
  85
  86      int
  87      archive_write_header(struct archive *, struct archive_entry *);
  88
  89      ssize_t
  90      archive_write_data(struct archive *, const void *, size_t);
  91
  92      int
  93      archive_write_finish_entry(struct archive *);
  94
  95      int
  96      archive_write_close(struct archive *);
  97
  98      int
  99      archive_write_finish(struct archive *);
 100
 101 DESCRIPTION
 102      These functions provide a complete API for creating streaming archive
 103      files.  The general process is to first create the struct archive object,
 104      set any desired options, initialize the archive, append entries, then
 105      close the archive and release all resources.  The following summary
 106      describes the functions in approximately the order they are ordinarily
 107      used:
 108
 109      archive_write_new()
 110              Allocates and initializes a struct archive object suitable for
 111              writing a tar archive.
 112
 113      archive_write_set_bytes_per_block()
 114              Sets the block size used for writing the archive data.  Every
 115              call to the write callback function, except possibly the last
 116              one, will use this value for the length.  The third parameter is
 117              a boolean that specifies whether or not the final block written
 118              will be padded to the full block size.  If it is zero, the last
 119              block will not be padded.  If it is non-zero, padding will be
 120              added both before and after compression.  The default is to use a
 121              block size of 10240 bytes and to pad the last block.  Note that a
 122              block size of zero will suppress internal blocking and cause
 123              writes to be sent directly to the write callback as they occur.
 124
 125      archive_write_get_bytes_per_block()
 126              Retrieve the block size to be used for writing.  A value of -1
 127              here indicates that the library should use default values.  A
 128              value of zero indicates that internal blocking is suppressed.
 129
 130      archive_write_set_bytes_in_last_block()
 131              Sets the block size used for writing the last block.  If this
 132              value is zero, the last block will be padded to the same size as
 133              the other blocks.  Otherwise, the final block will be padded to a
 134              multiple of this size.  In particular, setting it to 1 will cause
 135              the final block to not be padded.  For compressed output, any
 136              padding generated by this option is applied only after the com-
 137              pression.  The uncompressed data is always unpadded.  The default
 138              is to pad the last block to the full block size (note that
 139              archive_write_open_filename() will set this based on the file
 140              type).  Unlike the other ``set'' functions, this function can be
 141              called after the archive is opened.
 142
 143      archive_write_get_bytes_in_last_block()
 144              Retrieve the currently-set value for last block size.  A value of
 145              -1 here indicates that the library should use default values.
 146
 147      archive_write_set_format_cpio(), archive_write_set_format_pax(),
 148              archive_write_set_format_pax_restricted(),
 149              archive_write_set_format_shar(),
 150              archive_write_set_format_shar_binary(),
 151              archive_write_set_format_ustar()
 152              Sets the format that will be used for the archive.  The library
 153              can write POSIX octet-oriented cpio format archives, POSIX-stan-
 154              dard ``pax interchange'' format archives, traditional ``shar''
 155              archives, enhanced ``binary'' shar archives that store a variety
 156              of file attributes and handle binary files, and POSIX-standard
 157              ``ustar'' archives.  The pax interchange format is a backwards-
 158              compatible tar format that adds key/value attributes to each
 159              entry and supports arbitrary filenames, linknames, uids, sizes,
 160              etc.  ``Restricted pax interchange format'' is the library
 161              default; this is the same as pax format, but suppresses the pax
 162              extended header for most normal files.  In most cases, this will
 163              result in ordinary ustar archives.
 164
 165      archive_write_set_compression_bzip2(),
 166              archive_write_set_compression_compress(),
 167              archive_write_set_compression_gzip(),
 168              archive_write_set_compression_none()
 169              The resulting archive will be compressed as specified.  Note that
 170              the compressed output is always properly blocked.
 171
 172      archive_write_set_compression_program()
 173              The archive will be fed into the specified compression program.
 174              The output of that program is blocked and written to the client
 175              write callbacks.
 176
 177      archive_write_open()
 178              Freeze the settings, open the archive, and prepare for writing
 179              entries.  This is the most generic form of this function, which
 180              accepts pointers to three callback functions which will be
 181              invoked by the compression layer to write the constructed ar-
 182              chive.
 183
 184      archive_write_open_fd()
 185              A convenience form of archive_write_open() that accepts a file
 186              descriptor.  The archive_write_open_fd() function is safe for use
 187              with tape drives or other block-oriented devices.
 188
 189      archive_write_open_FILE()
 190              A convenience form of archive_write_open() that accepts a FILE *
 191              pointer.  Note that archive_write_open_FILE() is not safe for
 192              writing to tape drives or other devices that require correct
 193              blocking.
 194
 195      archive_write_open_file()
 196              A deprecated synonym for archive_write_open_filename().
 197
 198      archive_write_open_filename()
 199              A convenience form of archive_write_open() that accepts a file-
 200              name.  A NULL argument indicates that the output should be writ-
 201              ten to standard output; an argument of ``-'' will open a file
 202              with that name.  If you have not invoked
 203              archive_write_set_bytes_in_last_block(), then
 204              archive_write_open_filename() will adjust the last-block padding
 205              depending on the file: it will enable padding when writing to
 206              standard output or to a character or block device node, it will
 207              disable padding otherwise.  You can override this by manually
 208              invoking archive_write_set_bytes_in_last_block() before calling
 209              archive_write_open().  The archive_write_open_filename() function
 210              is safe for use with tape drives or other block-oriented devices.
 211
 212      archive_write_open_memory()
 213              A convenience form of archive_write_open() that accepts a pointer
 214              to a block of memory that will receive the archive.  The final
 215              size_t * argument points to a variable that will be updated after
 216              each write to reflect how much of the buffer is currently in use.
 217              You should be careful to ensure that this variable remains allo-
 218              cated until after the archive is closed.
 219
 220      archive_write_header()
 221              Build and write a header using the data in the provided struct
 222              archive_entry structure.  See archive_entry(3) for information on
 223              creating and populating struct archive_entry objects.
 224
 225      archive_write_data()
 226              Write data corresponding to the header just written.  Returns
 227              number of bytes written or -1 on error.
 228
 229      archive_write_finish_entry()
 230              Close out the entry just written.  In particular, this writes out
 231              the final padding required by some formats.  Ordinarily, clients
 232              never need to call this, as it is called automatically by
 233              archive_write_next_header() and archive_write_close() as needed.
 234
 235      archive_write_close()
 236              Complete the archive and invoke the close callback.
 237
 238      archive_write_finish()
 239              Invokes archive_write_close() if it was not invoked manually,
 240              then releases all resources.  Note that this function was
 241              declared to return void in libarchive 1.x, which made it impossi-
 242              ble to detect errors when archive_write_close() was invoked
 243              implicitly from this function.  This is corrected beginning with
 244              libarchive 2.0.
 245      More information about the struct archive object and the overall design
 246      of the library can be found in the libarchive(3) overview.
 247
 248 IMPLEMENTATION
 249      Compression support is built-in to libarchive, which uses zlib and bzlib
 250      to handle gzip and bzip2 compression, respectively.
 251
 252 CLIENT CALLBACKS
 253      To use this library, you will need to define and register callback func-
 254      tions that will be invoked to write data to the resulting archive.  These
 255      functions are registered by calling archive_write_open():
 256
 257            typedef int archive_open_callback(struct archive *, void
 258            *client_data)
 259
 260      The open callback is invoked by archive_write_open().  It should return
 261      ARCHIVE_OK if the underlying file or data source is successfully opened.
 262      If the open fails, it should call archive_set_error() to register an
 263      error code and message and return ARCHIVE_FATAL.
 264
 265            typedef ssize_t archive_write_callback(struct archive *,
 266            void *client_data, void *buffer, size_t length)
 267
 268      The write callback is invoked whenever the library needs to write raw
 269      bytes to the archive.  For correct blocking, each call to the write call-
 270      back function should translate into a single write(2) system call.  This
 271      is especially critical when writing archives to tape drives.  On success,
 272      the write callback should return the number of bytes actually written.
 273      On error, the callback should invoke archive_set_error() to register an
 274      error code and message and return -1.
 275
 276            typedef int archive_close_callback(struct archive *, void
 277            *client_data)
 278
 279      The close callback is invoked by archive_close when the archive process-
 280      ing is complete.  The callback should return ARCHIVE_OK on success.  On
 281      failure, the callback should invoke archive_set_error() to register an
 282      error code and message and return ARCHIVE_FATAL.
 283
 284 EXAMPLE
 285      The following sketch illustrates basic usage of the library.  In this
 286      example, the callback functions are simply wrappers around the standard
 287      open(2), write(2), and close(2) system calls.
 288
 289            #include <sys/stat.h>
 290            #include <archive.h>
 291            #include <archive_entry.h>
 292            #include <fcntl.h>
 293            #include <stdlib.h>
 294            #include <unistd.h>
 295
 296            struct mydata {
 297                    const char *name;
 298                    int fd;
 299            };
 300
 301            int
 302            myopen(struct archive *a, void *client_data)
 303            {
 304              struct mydata *mydata = client_data;
 305
 306              mydata->fd = open(mydata->name, O_WRONLY | O_CREAT, 0644);
 307              if (mydata->fd >= 0)
 308                return (ARCHIVE_OK);
 309              else
 310                return (ARCHIVE_FATAL);
 311            }
 312
 313            ssize_t
 314            mywrite(struct archive *a, void *client_data, void *buff, size_t n)
 315            {
 316              struct mydata *mydata = client_data;
 317
 318              return (write(mydata->fd, buff, n));
 319            }
 320
 321            int
 322            myclose(struct archive *a, void *client_data)
 323            {
 324              struct mydata *mydata = client_data;
 325
 326              if (mydata->fd > 0)
 327                close(mydata->fd);
 328              return (0);
 329            }
 330
 331            void
 332            write_archive(const char *outname, const char **filename)
 333            {
 334              struct mydata *mydata = malloc(sizeof(struct mydata));
 335              struct archive *a;
 336              struct archive_entry *entry;
 337              struct stat st;
 338              char buff[8192];
 339              int len;
 340              int fd;
 341
 342              a = archive_write_new();
 343              mydata->name = outname;
 344              archive_write_set_compression_gzip(a);
 345              archive_write_set_format_ustar(a);
 346              archive_write_open(a, mydata, myopen, mywrite, myclose);
 347              while (*filename) {
 348                stat(*filename, &st);
 349                entry = archive_entry_new();
 350                archive_entry_copy_stat(entry, &st);
 351                archive_entry_set_pathname(entry, *filename);
 352                archive_write_header(a, entry);
 353                fd = open(*filename, O_RDONLY);
 354                len = read(fd, buff, sizeof(buff));
 355                while ( len > 0 ) {
 356                    archive_write_data(a, buff, len);
 357                    len = read(fd, buff, sizeof(buff));
 358                }
 359                archive_entry_free(entry);
 360                filename++;
 361              }
 362              archive_write_finish(a);
 363            }
 364
 365            int main(int argc, const char **argv)
 366            {
 367                    const char *outname;
 368                    argv++;
 369                    outname = argv++;
 370                    write_archive(outname, argv);
 371                    return 0;
 372            }
 373
 374 RETURN VALUES
 375      Most functions return ARCHIVE_OK (zero) on success, or one of several
 376      non-zero error codes for errors.  Specific error codes include:
 377      ARCHIVE_RETRY for operations that might succeed if retried, ARCHIVE_WARN
 378      for unusual conditions that do not prevent further operations, and
 379      ARCHIVE_FATAL for serious errors that make remaining operations impossi-
 380      ble.  The archive_errno() and archive_error_string() functions can be
 381      used to retrieve an appropriate error code and a textual error message.
 382
 383      archive_write_new() returns a pointer to a newly-allocated struct archive
 384      object.
 385
 386      archive_write_data() returns a count of the number of bytes actually
 387      written.  On error, -1 is returned and the archive_errno() and
 388      archive_error_string() functions will return appropriate values.  Note
 389      that if the client-provided write callback function returns a non-zero
 390      value, that error will be propagated back to the caller through whatever
 391      API function resulted in that call, which may include
 392      archive_write_header(), archive_write_data(), archive_write_close(), or
 393      archive_write_finish().  The client callback can call archive_set_error()
 394      to provide values that can then be retrieved by archive_errno() and
 395      archive_error_string().
 396
 397 SEE ALSO
 398      tar(1), libarchive(3), tar(5)
 399
 400 HISTORY
 401      The libarchive library first appeared in FreeBSD 5.3.
 402
 403 AUTHORS
 404      The libarchive library was written by Tim Kientzle <kientzle@acm.org>.
 405
 406 BUGS
 407      There are many peculiar bugs in historic tar implementations that may
 408      cause certain programs to reject archives written by this library.  For
 409      example, several historic implementations calculated header checksums
 410      incorrectly and will thus reject valid archives; GNU tar does not fully
 411      support pax interchange format; some old tar implementations required
 412      specific field terminations.
 413
 414      The default pax interchange format eliminates most of the historic tar
 415      limitations and provides a generic key/value attribute facility for ven-
 416      dor-defined extensions.  One oversight in POSIX is the failure to provide
 417      a standard attribute for large device numbers.  This library uses
 418      ``SCHILY.devminor'' and ``SCHILY.devmajor'' for device numbers that
 419      exceed the range supported by the backwards-compatible ustar header.
 420      These keys are compatible with Joerg Schilling's star archiver.  Other
 421      implementations may not recognize these keys and will thus be unable to
 422      correctly restore device nodes with large device numbers from archives
 423      created by this library.
 424
 425 FreeBSD 6.0                      May 11, 2008                      FreeBSD 6.0