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