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