contrib/libarchive/libarchive/archive_write.3

   1 .\" Copyright (c) 2003-2011 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$
  26 .\"
  27 .Dd February 2, 2012
  28 .Dt ARCHIVE_WRITE 3
  29 .Os
  30 .Sh NAME
  31 .Nm archive_write
  32 .Nd functions for creating archives
  33 .Sh LIBRARY
  34 Streaming Archive Library (libarchive, -larchive)
  35 .Sh SYNOPSIS
  36 .In archive.h
  37 .Sh DESCRIPTION
  38 These functions provide a complete API for creating streaming
  39 archive files.
  40 The general process is to first create the
  41 .Tn struct archive
  42 object, set any desired options, initialize the archive, append entries, then
  43 close the archive and release all resources.
  44 .\"
  45 .Ss Create archive object
  46 See
  47 .Xr archive_write_new 3 .
  48 .Pp
  49 To write an archive, you must first obtain an initialized
  50 .Tn struct archive
  51 object from
  52 .Fn archive_write_new .
  53 .\"
  54 .Ss Enable filters and formats, configure block size and padding
  55 See
  56 .Xr archive_write_filter 3 ,
  57 .Xr archive_write_format 3
  58 and
  59 .Xr archive_write_blocksize 3 .
  60 .Pp
  61 You can then modify this object for the desired operations with the
  62 various
  63 .Fn archive_write_set_XXX
  64 functions.
  65 In particular, you will need to invoke appropriate
  66 .Fn archive_write_add_XXX
  67 and
  68 .Fn archive_write_set_XXX
  69 functions to enable the corresponding compression and format
  70 support.
  71 .\"
  72 .Ss Set options
  73 See
  74 .Xr archive_read_set_options 3 .
  75 .\"
  76 .Ss Open archive
  77 See
  78 .Xr archive_write_open 3 .
  79 .Pp
  80 Once you have prepared the
  81 .Tn struct archive
  82 object, you call
  83 .Fn archive_write_open
  84 to actually open the archive and prepare it for writing.
  85 There are several variants of this function;
  86 the most basic expects you to provide pointers to several
  87 functions that can provide blocks of bytes from the archive.
  88 There are convenience forms that allow you to
  89 specify a filename, file descriptor,
  90 .Ft "FILE *"
  91 object, or a block of memory from which to write the archive data.
  92 .\"
  93 .Ss Produce archive
  94 See
  95 .Xr archive_write_header 3
  96 and
  97 .Xr archive_write_data 3 .
  98 .Pp
  99 Individual archive entries are written in a three-step
 100 process:
 101 You first initialize a
 102 .Tn struct archive_entry
 103 structure with information about the new entry.
 104 At a minimum, you should set the pathname of the
 105 entry and provide a
 106 .Va struct stat
 107 with a valid
 108 .Va st_mode
 109 field, which specifies the type of object and
 110 .Va st_size
 111 field, which specifies the size of the data portion of the object.
 112 .\"
 113 .Ss Release resources
 114 See
 115 .Xr archive_write_free 3 .
 116 .Pp
 117 After all entries have been written, use the
 118 .Fn archive_write_free
 119 function to release all resources.
 120 .\"
 121 .Sh EXAMPLE
 122 The following sketch illustrates basic usage of the library.
 123 In this example,
 124 the callback functions are simply wrappers around the standard
 125 .Xr open 2 ,
 126 .Xr write 2 ,
 127 and
 128 .Xr close 2
 129 system calls.
 130 .Bd -literal -offset indent
 131 #ifdef __linux__
 132 #define _FILE_OFFSET_BITS 64
 133 #endif
 134 #include <sys/stat.h>
 135 #include <archive.h>
 136 #include <archive_entry.h>
 137 #include <fcntl.h>
 138 #include <stdlib.h>
 139 #include <unistd.h>
 140
 141 struct mydata {
 142   const char *name;
 143   int fd;
 144 };
 145
 146 int
 147 myopen(struct archive *a, void *client_data)
 148 {
 149   struct mydata *mydata = client_data;
 150
 151   mydata->fd = open(mydata->name, O_WRONLY | O_CREAT, 0644);
 152   if (mydata->fd >= 0)
 153     return (ARCHIVE_OK);
 154   else
 155     return (ARCHIVE_FATAL);
 156 }
 157
 158 la_ssize_t
 159 mywrite(struct archive *a, void *client_data, const void *buff, size_t n)
 160 {
 161   struct mydata *mydata = client_data;
 162
 163   return (write(mydata->fd, buff, n));
 164 }
 165
 166 int
 167 myclose(struct archive *a, void *client_data)
 168 {
 169   struct mydata *mydata = client_data;
 170
 171   if (mydata->fd > 0)
 172     close(mydata->fd);
 173   return (0);
 174 }
 175
 176 void
 177 write_archive(const char *outname, const char **filename)
 178 {
 179   struct mydata *mydata = malloc(sizeof(struct mydata));
 180   struct archive *a;
 181   struct archive_entry *entry;
 182   struct stat st;
 183   char buff[8192];
 184   int len;
 185   int fd;
 186
 187   a = archive_write_new();
 188   mydata->name = outname;
 189   /* Set archive format and filter according to output file extension.
 190    * If it fails, set default format. Platform depended function.
 191    * See supported formats in archive_write_set_format_filter_by_ext.c */
 192   if (archive_write_set_format_filter_by_ext(a, outname) != ARCHIVE_OK)  {
 193     archive_write_add_filter_gzip(a);
 194     archive_write_set_format_ustar(a);
 195   }
 196   archive_write_open(a, mydata, myopen, mywrite, myclose);
 197   while (*filename) {
 198     stat(*filename, &st);
 199     entry = archive_entry_new();
 200     archive_entry_copy_stat(entry, &st);
 201     archive_entry_set_pathname(entry, *filename);
 202     archive_write_header(a, entry);
 203     if ((fd = open(*filename, O_RDONLY)) != -1) {
 204       len = read(fd, buff, sizeof(buff));
 205       while (len > 0) {
 206         archive_write_data(a, buff, len);
 207         len = read(fd, buff, sizeof(buff));
 208       }
 209       close(fd);
 210     }
 211     archive_entry_free(entry);
 212     filename++;
 213   }
 214   archive_write_free(a);
 215 }
 216
 217 int main(int argc, const char **argv)
 218 {
 219   const char *outname;
 220   argv++;
 221   outname = *argv++;
 222   write_archive(outname, argv);
 223   return 0;
 224 }
 225 .Ed
 226 .Sh SEE ALSO
 227 .Xr tar 1 ,
 228 .Xr libarchive 3 ,
 229 .Xr archive_write_set_options 3 ,
 230 .Xr cpio 5 ,
 231 .Xr mtree 5 ,
 232 .Xr tar 5
 233 .Sh HISTORY
 234 The
 235 .Nm libarchive
 236 library first appeared in
 237 .Fx 5.3 .
 238 .Sh AUTHORS
 239 .An -nosplit
 240 The
 241 .Nm libarchive
 242 library was written by
 243 .An Tim Kientzle Aq kientzle@acm.org .
 244 .Sh BUGS
 245 There are many peculiar bugs in historic tar implementations that may cause
 246 certain programs to reject archives written by this library.
 247 For example, several historic implementations calculated header checksums
 248 incorrectly and will thus reject valid archives; GNU tar does not fully support
 249 pax interchange format; some old tar implementations required specific
 250 field terminations.
 251 .Pp
 252 The default pax interchange format eliminates most of the historic
 253 tar limitations and provides a generic key/value attribute facility
 254 for vendor-defined extensions.
 255 One oversight in POSIX is the failure to provide a standard attribute
 256 for large device numbers.
 257 This library uses
 258 .Dq SCHILY.devminor
 259 and
 260 .Dq SCHILY.devmajor
 261 for device numbers that exceed the range supported by the backwards-compatible
 262 ustar header.
 263 These keys are compatible with Joerg Schilling's
 264 .Nm star
 265 archiver.
 266 Other implementations may not recognize these keys and will thus be unable
 267 to correctly restore device nodes with large device numbers from archives
 268 created by this library.