contrib/libarchive/archive_write.3

   1 .\" Copyright (c) 2003-2005 Tim Kientzle
   2 .\" All rights reserved.
   3 .\"
   4 .\" Redistribution and use in source and binary forms, with or without
   5 .\" modification, are permitted provided that the following conditions
   6 .\" are met:
   7 .\" 1. Redistributions of source code must retain the above copyright
   8 .\"    notice, this list of conditions and the following disclaimer.
   9 .\" 2. Redistributions in binary form must reproduce the above copyright
  10 .\"    notice, this list of conditions and the following disclaimer in the
  11 .\"    documentation and/or other materials provided with the distribution.
  12 .\"
  13 .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
  14 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  15 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  16 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
  17 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  18 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  19 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  20 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  21 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  22 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  23 .\" SUCH DAMAGE.
  24 .\"
  25 .\" $FreeBSD: src/lib/libarchive/archive_write.3,v 1.11 2005/02/13 22:25:11 ru Exp $
  26 .\"
  27 .Dd January 8, 2005
  28 .Dt archive_write 3
  29 .Os
  30 .Sh NAME
  31 .Nm archive_write_new ,
  32 .Nm archive_write_set_format_cpio ,
  33 .Nm archive_write_set_format_pax ,
  34 .Nm archive_write_set_format_pax_restricted ,
  35 .Nm archive_write_set_format_shar ,
  36 .Nm archive_write_set_format_shar_binary ,
  37 .Nm archive_write_set_format_ustar ,
  38 .Nm archive_write_set_bytes_per_block ,
  39 .Nm archive_write_set_bytes_in_last_block ,
  40 .Nm archive_write_set_compressor_gzip ,
  41 .Nm archive_write_set_compressor_bzip2 ,
  42 .Nm archive_write_open ,
  43 .Nm archive_write_open_fd ,
  44 .Nm archive_write_open_file ,
  45 .Nm archive_write_prepare ,
  46 .Nm archive_write_header ,
  47 .Nm archive_write_data ,
  48 .Nm archive_write_close ,
  49 .Nm archive_write_finish
  50 .Nd functions for creating archives
  51 .Sh SYNOPSIS
  52 .In archive.h
  53 .Ft struct archive *
  54 .Fn archive_write_new "void"
  55 .Ft int
  56 .Fn archive_write_set_bytes_per_block "archive *" "int bytes_per_block"
  57 .Ft int
  58 .Fn archive_write_set_bytes_in_last_block "archive *" "int"
  59 .Ft int
  60 .Fn archive_write_set_compressor_gzip "struct archive *"
  61 .Ft int
  62 .Fn archive_write_set_compressor_bzip2 "struct archive *"
  63 .Ft int
  64 .Fn archive_write_set_format_cpio "struct archive *"
  65 .Ft int
  66 .Fn archive_write_set_format_pax "struct archive *"
  67 .Ft int
  68 .Fn archive_write_set_format_pax_restricted "struct archive *"
  69 .Ft int
  70 .Fn archive_write_set_format_shar "struct archive *"
  71 .Ft int
  72 .Fn archive_write_set_format_shar_binary "struct archive *"
  73 .Ft int
  74 .Fn archive_write_set_format_ustar "struct archive *"
  75 .Ft int
  76 .Fn archive_write_open "struct archive *" "void *client_data" "archive_open_archive_callback *" "archive_write_archive_callback *" "archive_close_archive_callback *"
  77 .Ft int
  78 .Fn archive_write_open_fd "struct archive *" "int fd"
  79 .Ft int
  80 .Fn archive_write_open_file "struct archive *" "const char *filename"
  81 .Ft int
  82 .Fn archive_write_header "struct archive *"
  83 .Ft int
  84 .Fn archive_write_data "struct archive *" "const void *" "size_t"
  85 .Ft int
  86 .Fn archive_write_close "struct archive *"
  87 .Ft void
  88 .Fn archive_write_finish "struct archive *"
  89 .Sh DESCRIPTION
  90 These functions provide a complete API for creating streaming
  91 archive files.
  92 The general process is to first create the
  93 .Tn struct archive
  94 object, set any desired options, initialize the archive, append entries, then
  95 close the archive and release all resources.
  96 The following summary describes the functions in approximately
  97 the order they are ordinarily used:
  98 .Bl -tag -width indent
  99 .It Fn archive_write_new
 100 Allocates and initializes a
 101 .Tn struct archive
 102 object suitable for writing a tar archive.
 103 .It Fn archive_write_set_bytes_per_block
 104 Sets the block size used for writing the archive data.
 105 Every call to the write callback function, except possibly the last one, will
 106 use this value for the length.
 107 The third parameter is a boolean that specifies whether or not the final block
 108 written will be padded to the full block size.
 109 If it is zero, the last block will not be padded.
 110 If it is non-zero, padding will be added both before and after compression.
 111 The default is to use a block size of 10240 bytes and to pad the last block.
 112 .It Fn archive_write_set_bytes_in_last_block
 113 Sets the block size used for writing the last block.
 114 If this value is zero, the last block will be padded to the same size
 115 as the other blocks.
 116 Otherwise, the final block will be padded to a multiple of this size.
 117 In particular, setting it to 1 will cause the final block to not be padded.
 118 For compressed output, any padding generated by this option
 119 is applied only after the compression.
 120 The uncompressed data is always unpadded.
 121 The default is to pad the last block to the full block size (note that
 122 .Fn archive_write_open_file
 123 will set this based on the file type).
 124 Unlike the other
 125 .Dq set
 126 functions, this function can be called after the archive is opened.
 127 .It Fn archive_write_set_format_cpio , Fn archive_write_set_format_pax , Fn archive_write_set_format_pax_restricted , Fn archive_write_set_format_shar , Fn archive_write_set_format_shar_binary , Fn archive_write_set_format_ustar
 128 Sets the format that will be used for the archive.
 129 The library can write
 130 POSIX octet-oriented cpio format archives,
 131 POSIX-standard
 132 .Dq pax interchange
 133 format archives,
 134 traditional
 135 .Dq shar
 136 archives,
 137 enhanced
 138 .Dq binary
 139 shar archives that store a variety of file attributes and handle binary files,
 140 and
 141 POSIX-standard
 142 .Dq ustar
 143 archives.
 144 The pax interchange format is a backwards-compatible tar format that
 145 adds key/value attributes to each entry and supports arbitrary
 146 filenames, linknames, uids, sizes, etc.
 147 .Dq Restricted pax interchange format
 148 is the library default; this is the same as pax format, but suppresses
 149 the pax extended header for most normal files.
 150 In most cases, this will result in ordinary ustar archives.
 151 .It Fn archive_write_set_compression_gzip , Fn archive_write_set_compression_bzip2
 152 The resulting archive will be compressed as specified.
 153 Note that the compressed output is always properly blocked.
 154 .It Fn archive_write_open
 155 Freeze the settings, open the archive, and prepare for writing entries.
 156 This is the most generic form of this function, which accepts
 157 pointers to three callback functions which will be invoked by
 158 the compression layer to write the constructed archive.
 159 In order to support external compression programs, the compression
 160 is permitted to fork and invoke the callbacks from a separate process.
 161 In particular, clients should not assume that they can communicate
 162 between the callbacks and the mainline code using shared variables.
 163 (The standard gzip, bzip2, and "none" compression methods do not fork.)
 164 .It Fn archive_write_open_fd
 165 A convenience form of
 166 .Fn archive_write_open
 167 that accepts a file descriptor.
 168 .It Fn archive_write_open_file
 169 A convenience form of
 170 .Fn archive_write_open
 171 that accepts a filename.
 172 A NULL argument indicates that the output should be written to standard output;
 173 an argument of
 174 .Dq -
 175 will open a file with that name.
 176 If you have not invoked
 177 .Fn archive_write_set_bytes_in_last_block ,
 178 then
 179 .Fn archive_write_open_file
 180 will adjust the last-block padding depending on the file:
 181 it will enable padding when writing to standard output or
 182 to a character or block device node, it will disable padding otherwise.
 183 You can override this by manually invoking
 184 .Fn archive_write_set_bytes_in_last_block
 185 either before or after calling
 186 .Fn archive_write_open .
 187 .It Fn archive_write_header
 188 Build and write a header using the data in the provided
 189 .Tn struct archive_entry
 190 structure.
 191 .It Fn archive_write_data
 192 Write data corresponding to the header just written.
 193 Returns number of bytes written or -1 on error.
 194 .It Fn archive_write_close
 195 Complete the archive and invoke the close callback.
 196 .It Fn archive_write_finish
 197 Invokes
 198 .Fn archive_write_close
 199 if it was not invoked manually, then release all resources.
 200 .El
 201 More information about the
 202 .Va struct archive
 203 object and the overall design of the library can be found in the
 204 .Xr libarchive 3
 205 overview.
 206 .Sh IMPLEMENTATION
 207 Compression support is built-in to libarchive, which uses zlib and bzlib
 208 to handle gzip and bzip2 compression, respectively.
 209 .Sh CLIENT CALLBACKS
 210 To use this library, you will need to define and register
 211 callback functions that will be invoked to write data to the
 212 resulting archive.
 213 These functions are registered by calling
 214 .Fn archive_write_open :
 215 .Bl -item -offset indent
 216 .It
 217 .Ft typedef int
 218 .Fn archive_open_archive_callback "struct archive *" "void *client_data"
 219 .El
 220 .Pp
 221 The open callback is invoked by
 222 .Fn archive_write_open .
 223 It should return
 224 .Cm ARCHIVE_OK
 225 if the underlying file or data source is successfully
 226 opened.
 227 If the open fails, it should call
 228 .Fn archive_set_error
 229 to register an error code and message and return
 230 .Cm ARCHIVE_FATAL .
 231 .Bl -item -offset indent
 232 .It
 233 .Ft typedef ssize_t
 234 .Fn archive_write_archive_callback "struct archive *" "void *client_data" "void *buffer" "size_t length"
 235 .El
 236 .Pp
 237 The write callback is invoked whenever the library
 238 needs to write raw bytes to the archive.
 239 For correct blocking, each call to the write callback function
 240 should translate into a single
 241 .Xr write 2
 242 system call.
 243 This is especially critical when writing archives to tape drives.
 244 On success, the write callback should return the
 245 number of bytes actually written.
 246 On error, the callback should invoke
 247 .Fn archive_set_error
 248 to register an error code and message and return -1.
 249 .Bl -item -offset indent
 250 .It
 251 .Ft typedef int
 252 .Fn archive_close_archive_callback "struct archive *" "void *client_data"
 253 .El
 254 .Pp
 255 The close callback is invoked by archive_close when
 256 the archive processing is complete.
 257 The callback should return
 258 .Cm ARCHIVE_OK
 259 on success.
 260 On failure, the callback should invoke
 261 .Fn archive_set_error
 262 to register an error code and message and
 263 regurn
 264 .Cm ARCHIVE_FATAL.
 265 .Sh EXAMPLE
 266 The following sketch illustrates basic usage of the library.
 267 In this example,
 268 the callback functions are simply wrappers around the standard
 269 .Xr open 2 ,
 270 .Xr write 2 ,
 271 and
 272 .Xr close 2
 273 system calls.
 274 .Bd -literal -offset indent
 275 void
 276 write_archive(const char **filename)
 277 {
 278   struct mydata *mydata = malloc(sizeof(struct mydata));
 279   struct archive *a;
 280   struct archive_entry *entry;
 281   struct stat st;
 282   char buff[8192];
 283   int len;
 284
 285   a = archive_write_new();
 286   mydata->name = name;
 287   archive_write_set_compression_gzip(a);
 288   archive_write_set_format_ustar(a);
 289   archive_write_open(a, mydata, myopen, mywrite, myclose);
 290   while (*filename) {
 291     stat(*filename, &st);
 292     entry = archive_entry_new();
 293     archive_entry_copy_stat(entry, &st);
 294     archive_entry_set_pathname(entry, *filename);
 295     archive_write_header(a, entry);
 296     fd = open(*filename, O_RDONLY);
 297     len = read(fd, buff, sizeof(buff));
 298     while ( len >= 0 ) {
 299         archive_write_data(a, buff, len);
 300         len = read(fd, buff, sizeof(buff));
 301     }
 302     archive_entry_free(entry);
 303     filename++;
 304   }
 305   archive_write_finish(a);
 306 }
 307
 308 int
 309 myopen(struct archive *a, void *client_data)
 310 {
 311   struct mydata *mydata = client_data;
 312
 313   mydata->fd = open(mydata->name, O_WRONLY | O_CREAT, 0644);
 314   return (mydata->fd >= 0);
 315 }
 316
 317 ssize_t
 318 mywrite(struct archive *a, void *client_data, void *buff, size_t n)
 319 {
 320   struct mydata *mydata = client_data;
 321
 322   return (write(mydata->fd, buff, n));
 323 }
 324
 325 int
 326 myclose(struct archive *a, void *client_data)
 327 {
 328   struct mydata *mydata = client_data;
 329
 330   if (mydata->fd > 0)
 331     close(mydata->fd);
 332   return (0);
 333 }
 334 .Ed
 335 .Sh RETURN VALUES
 336 Most functions return zero on success, non-zero on error.
 337 The
 338 .Fn archive_errno
 339 and
 340 .Fn archive_error_string
 341 functions can be used to retrieve an appropriate error code and a
 342 textual error message.
 343 .Pp
 344 .Fn archive_write_new
 345 returns a pointer to a newly-allocated
 346 .Tn struct archive
 347 object.
 348 .Pp
 349 .Fn archive_write_data
 350 returns a count of the number of bytes actually written.
 351 On error, -1 is returned and the
 352 .Fn archive_errno
 353 and
 354 .Fn archive_error_string
 355 functions will return appropriate values.
 356 Note that if the client-provided write callback function
 357 returns a non-zero value, that error will be propagated back to the caller
 358 through whatever API function resulted in that call, which
 359 may include
 360 .Fn archive_write_header ,
 361 .Fn archive_write_data ,
 362 or
 363 .Fn archive_write_close .
 364 The client callback can call
 365 .Fn archive_set_error
 366 to provide values that can then be retrieved by
 367 .Fn archive_errno
 368 and
 369 .Fn archive_error_string .
 370 .Sh SEE ALSO
 371 .Xr tar 1 ,
 372 .Xr libarchive 3 ,
 373 .Xr tar 5
 374 .Sh HISTORY
 375 The
 376 .Nm libarchive
 377 library first appeared in
 378 .Fx 5.3 .
 379 .Sh AUTHORS
 380 .An -nosplit
 381 The
 382 .Nm libarchive
 383 library was written by
 384 .An Tim Kientzle Aq kientzle@acm.org .
 385 .Sh BUGS
 386 There are many peculiar bugs in historic tar implementations that may cause
 387 certain programs to reject archives written by this library.
 388 For example, several historic implementations calculated header checksums
 389 incorrectly and will thus reject valid archives; GNU tar does not fully support
 390 pax interchange format; some old tar implementations required specific
 391 field terminations.
 392 .Pp
 393 The default pax interchange format eliminates most of the historic
 394 tar limitations and provides a generic key/value attribute facility
 395 for vendor-defined extensions.
 396 One oversight in POSIX is the failure to provide a standard attribute
 397 for large device numbers.
 398 This library uses
 399 .Dq SCHILY.devminor
 400 and
 401 .Dq SCHILY.devmajor
 402 for device numbers that exceed the range supported by the backwards-compatible
 403 ustar header.
 404 These keys are compatible with Joerg Schilling's
 405 .Nm star
 406 archiver.
 407 Other implementations may not recognize these keys and will thus be unable
 408 to correctly restore large device numbers archived by this library.