contrib/libarchive-2/libarchive/archive_write.3

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