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