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