contrib/libarchive/archive_write.3

   1 .\" Copyright (c) 2003-2004 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.8 2004/11/05 05:26:30 kientzle Exp $
  26 .\"
  27 .Dd October 1, 2003
  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_set_bytes_per_block ,
  39 .Nm archive_write_set_bytes_in_last_block ,
  40 .Nm archive_write_set_compressor_gzip ,
  41 .Nm archive_write_set_compressor_bzip2 ,
  42 .Nm archive_write_open ,
  43 .Nm archive_write_open_fd ,
  44 .Nm archive_write_open_file ,
  45 .Nm archive_write_prepare ,
  46 .Nm archive_write_header ,
  47 .Nm archive_write_data ,
  48 .Nm archive_write_close ,
  49 .Nm archive_write_finish
  50 .Nd functions for creating archives
  51 .Sh SYNOPSIS
  52 .In archive.h
  53 .Ft struct archive *
  54 .Fn archive_write_new "void"
  55 .Ft int
  56 .Fn archive_write_set_bytes_per_block "archive *" "int bytes_per_block"
  57 .Ft int
  58 .Fn archive_write_set_bytes_in_last_block "archive *" "int"
  59 .Ft int
  60 .Fn archive_write_set_compressor_gzip "struct archive *"
  61 .Ft int
  62 .Fn archive_write_set_compressor_bzip2 "struct archive *"
  63 .Ft int
  64 .Fn archive_write_set_format_cpio "struct archive *"
  65 .Ft int
  66 .Fn archive_write_set_format_pax "struct archive *"
  67 .Ft int
  68 .Fn archive_write_set_format_pax_restricted "struct archive *"
  69 .Ft int
  70 .Fn archive_write_set_format_shar "struct archive *"
  71 .Ft int
  72 .Fn archive_write_set_format_shar_binary "struct archive *"
  73 .Ft int
  74 .Fn archive_write_set_format_ustar "struct archive *"
  75 .Ft int
  76 .Fn archive_write_open "struct archive *" "void *client_data" "archive_write_archive_callback *" "archive_open_archive_callback *" "archive_close_archive_callback *"
  77 .Ft int
  78 .Fn archive_write_open_fd "struct archive *" "int fd"
  79 .Ft int
  80 .Fn archive_write_open_file "struct archive *" "const char *filename"
  81 .Ft int
  82 .Fn archive_write_header "struct archive *"
  83 .Ft int
  84 .Fn archive_write_data "struct archive *" "const void *" "size_t"
  85 .Ft int
  86 .Fn archive_write_close "struct archive *"
  87 .Ft void
  88 .Fn archive_write_finish "struct archive *"
  89 .Sh DESCRIPTION
  90 These functions provide a complete API for creating streaming
  91 archive files.
  92 The general process is to first create the
  93 .Tn struct archive
  94 object, set any desired options, initialize the archive, append entries, then
  95 close the archive and release all resources.
  96 The following summary describes the functions in approximately
  97 the order they are ordinarily used:
  98 .Bl -tag -width indent
  99 .It Fn archive_write_new
 100 Allocates and initializes a
 101 .Tn struct archive
 102 object suitable for writing a tar archive.
 103 .It Fn archive_write_set_bytes_per_block
 104 Sets the block size used for writing the archive data.
 105 Every call to the write callback function, except possibly the last one, will
 106 use this value for the length.
 107 The third parameter is a boolean that specifies whether or not the final block
 108 written will be padded to the full block size.
 109 If it is zero, the last block will not be padded.
 110 If it is non-zero, padding will be added both before and after compression.
 111 The default is to use a block size of 10240 bytes and to pad the last block.
 112 .It Fn archive_write_set_bytes_in_last_block
 113 Sets the block size used for writing the last block.
 114 If this value is zero, the last block will be padded to the same size
 115 as the other blocks.
 116 Otherwise, the final block will be padded to a multiple of this size.
 117 In particular, setting it to 1 will cause the final block to not be padded.
 118 For compressed output, any padding generated by this option
 119 is applied only after the compression.
 120 The uncompressed data is always unpadded.
 121 The default is to pad the last block to the full block size (note that
 122 .Fn archive_write_open_file
 123 will set this based on the file type).
 124 Unlike the other
 125 .Dq set
 126 functions, this function can be called after the archive is opened.
 127 .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
 128 Sets the format that will be used for the archive.
 129 The library can write
 130 POSIX octet-oriented cpio format archives,
 131 POSIX-standard
 132 .Dq pax interchange
 133 format archives,
 134 traditional
 135 .Dq shar
 136 archives,
 137 enhanced
 138 .Dq binary
 139 shar archives that store a variety of file attributes and handle binary files,
 140 and
 141 POSIX-standard
 142 .Dq ustar
 143 archives.
 144 The pax interchange format is a backwards-compatible tar format that
 145 adds key/value attributes to each entry and supports arbitrary
 146 filenames, linknames, uids, sizes, etc.
 147 .Dq Restricted pax interchange format
 148 is the library default; this is the same as pax format, but suppresses
 149 the pax extended header for most normal files.
 150 In most cases, this will result in ordinary ustar archives.
 151 .It Fn archive_write_set_compression_gzip , Fn archive_write_set_compression_bzip2
 152 The resulting archive will be compressed as specified.
 153 Note that the compressed output is always properly blocked.
 154 .It Fn archive_write_open
 155 Freeze the settings, open the archive, and prepare for writing entries.
 156 This is the most generic form of this function, which accepts
 157 pointers to three callback functions which will be invoked by
 158 the compression layer to write the constructed archive.
 159 In order to support external compression programs, the compression
 160 is permitted to fork and invoke the callbacks from a separate process.
 161 In particular, clients should not assume that they can communicate
 162 between the callbacks and the mainline code using shared variables.
 163 (The standard gzip, bzip2, and "none" compression methods do not fork.)
 164 .It Fn archive_write_open_fd
 165 A convenience form of
 166 .Fn archive_write_open
 167 that accepts a file descriptor.
 168 .It Fn archive_write_open_file
 169 A convenience form of
 170 .Fn archive_write_open
 171 that accepts a filename.
 172 A NULL argument indicates that the output should be written to standard output;
 173 an argument of
 174 .Dq -
 175 will open a file with that name.
 176 If you have not invoked
 177 .Fn archive_write_set_bytes_in_last_block ,
 178 then
 179 .Fn archive_write_open_file
 180 will adjust the last-block padding depending on the file:
 181 it will enable padding when writing to standard output or
 182 to a character or block device node, it will disable padding otherwise.
 183 You can override this by manually invoking
 184 .Fn archive_write_set_bytes_in_last_block
 185 either before or after calling
 186 .Fn archive_write_open .
 187 .It Fn archive_write_header
 188 Build and write a header using the data in the provided
 189 .Tn struct archive_entry
 190 structure.
 191 .It Fn archive_write_data
 192 Write data corresponding to the header just written.
 193 Returns number of bytes written or -1 on error.
 194 .It Fn archive_write_close
 195 Complete the archive and invoke the close callback.
 196 .It Fn archive_write_finish
 197 Invokes
 198 .Fn archive_write_close
 199 if it wasn't invoked manually, then release all resources.
 200 .El
 201 .Pp
 202 The callback functions are defined as follows:
 203 .Bl -item -offset indent
 204 .It
 205 .Ft typedef ssize_t
 206 .Fn archive_write_archive_callback "struct archive *" "void *client_data" "void *buffer" "size_t length"
 207 .It
 208 .Ft typedef int
 209 .Fn archive_open_archive_callback "struct archive *" "void *client_data"
 210 .It
 211 .Ft typedef int
 212 .Fn archive_close_archive_callback "struct archive *" "void *client_data"
 213 .El
 214 For correct blocking, each call to the write callback function
 215 should translate into a single
 216 .Xr write 2
 217 system call.
 218 This is especially critical when writing tar archives to tape drives.
 219 .Pp
 220 More information about tar archive formats and blocking can be found
 221 in the
 222 .Xr tar 5
 223 manual page.
 224 .Pp
 225 More information about the
 226 .Va struct archive
 227 object and the overall design of the library can be found in the
 228 .Xr libarchive 3
 229 overview.
 230 .Sh IMPLEMENTATION
 231 Compression support is built-in to libarchive, which uses zlib and bzlib
 232 to handle gzip and bzip2 compression, respectively.
 233 .Sh EXAMPLE
 234 The following sketch illustrates basic usage of the library.
 235 In this example,
 236 the callback functions are simply wrappers around the standard
 237 .Xr open 2 ,
 238 .Xr write 2 ,
 239 and
 240 .Xr close 2
 241 system calls.
 242 .Bd -literal -offset indent
 243 void
 244 write_archive(const char **filename)
 245 {
 246   struct mydata *mydata = malloc(sizeof(struct mydata));
 247   struct archive *a;
 248   struct archive_entry *entry;
 249   struct stat st;
 250   char buff[8192];
 251   int len;
 252
 253   a = archive_write_new();
 254   mydata->name = name;
 255   archive_write_set_compression_gzip(a);
 256   archive_write_set_format_ustar(a);
 257   archive_write_open(a, mydata, myopen, mywrite, myclose);
 258   while (*filename) {
 259     stat(*filename, &st);
 260     entry = archive_entry_new();
 261     archive_entry_copy_stat(entry, &st);
 262     archive_entry_set_pathname(entry, *filename);
 263     archive_write_header(a, entry);
 264     fd = open(*filename, O_RDONLY);
 265     len = read(fd, buff, sizeof(buff));
 266     while ( len >= 0 ) {
 267         archive_write_data(a, buff, len);
 268         len = read(fd, buff, sizeof(buff));
 269     }
 270     archive_entry_free(entry);
 271     filename++;
 272   }
 273   archive_write_finish(a);
 274 }
 275
 276 int
 277 myopen(struct archive *a, void *client_data)
 278 {
 279   struct mydata *mydata = client_data;
 280
 281   mydata->fd = open(mydata->name, O_WRONLY | O_CREAT, 0644);
 282   return (mydata->fd >= 0);
 283 }
 284
 285 ssize_t
 286 mywrite(struct archive *a, void *client_data, void *buff, size_t n)
 287 {
 288   struct mydata *mydata = client_data;
 289
 290   return (write(mydata->fd, buff, n));
 291 }
 292
 293 int
 294 myclose(struct archive *a, void *client_data)
 295 {
 296   struct mydata *mydata = client_data;
 297
 298   if (mydata->fd > 0)
 299     close(mydata->fd);
 300   return (0);
 301 }
 302 .Ed
 303 .Sh RETURN VALUES
 304 Most functions return zero on success, non-zero on error.
 305 The
 306 .Fn archive_errno
 307 and
 308 .Fn archive_error_string
 309 functions can be used to retrieve an appropriate error code and a
 310 textual error message.
 311 .Pp
 312 .Fn archive_write_new
 313 returns a pointer to a newly-allocated
 314 .Tn struct archive
 315 object.
 316 .Pp
 317 .Fn archive_write_data
 318 returns a count of the number of bytes actually written.
 319 On error, -1 is returned and the
 320 .Fn archive_errno
 321 and
 322 .Fn archive_error_string
 323 functions will return appropriate values.
 324 Note that if the client-provided write callback function
 325 returns a non-zero value, that error will be propagated back to the caller
 326 through whatever API function resulted in that call, which
 327 may include
 328 .Fn archive_write_header ,
 329 .Fn archive_write_data ,
 330 or
 331 .Fn archive_write_close .
 332 The client callback can call
 333 .Fn archive_set_error
 334 to provide values that can then be retrieved by
 335 .Fn archive_errno
 336 and
 337 .Fn archive_error_string .
 338 .Sh SEE ALSO
 339 .Xr tar 1 ,
 340 .Xr libarchive 3 ,
 341 .Xr tar 5
 342 .Sh HISTORY
 343 The
 344 .Nm libarchive
 345 library first appeared in
 346 .Fx 5.3 .
 347 .Sh AUTHORS
 348 .An -nosplit
 349 The
 350 .Nm libarchive
 351 library was written by
 352 .An Tim Kientzle Aq kientzle@acm.org .
 353 .Sh BUGS
 354 There are many peculiar bugs in historic tar implementations that may cause
 355 certain programs to reject archives written by this library.
 356 For example, several historic implementations calculated header checksums
 357 incorrectly and will thus reject valid archives; GNU tar does not fully support
 358 pax interchange format; some old tar implementations required specific
 359 field terminations.
 360 .Pp
 361 The default pax interchange format eliminates most of the historic
 362 tar limitations and provides a generic key/value attribute facility
 363 for vendor-defined extensions.
 364 One oversight in POSIX is the failure to provide a standard attribute
 365 for large device numbers.
 366 This library uses
 367 .Dq SCHILY.devminor
 368 and
 369 .Dq SCHILY.devmajor
 370 for device numbers that exceed the range supported by the backwards-compatible
 371 ustar header.
 372 These keys are compatible with Joerg Schilling's
 373 .Nm star
 374 archiver.
 375 Other implementations may not recognize these keys and will thus be unable
 376 to correctly restore large device numbers archived by this library.