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