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