Utilities/cmlibarchive/libarchive/archive_write_open.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_open ,
  32 .Nm archive_write_open_fd ,
  33 .Nm archive_write_open_FILE ,
  34 .Nm archive_write_open_filename ,
  35 .Nm archive_write_open_memory
  36 .Nd functions for creating archives
  37 .Sh SYNOPSIS
  38 .In archive.h
  39 .Ft int
  40 .Fo archive_write_open
  41 .Fa "struct archive *"
  42 .Fa "void *client_data"
  43 .Fa "archive_open_callback *"
  44 .Fa "archive_write_callback *"
  45 .Fa "archive_close_callback *"
  46 .Fc
  47 .Ft int
  48 .Fn archive_write_open_fd "struct archive *" "int fd"
  49 .Ft int
  50 .Fn archive_write_open_FILE "struct archive *" "FILE *file"
  51 .Ft int
  52 .Fn archive_write_open_filename "struct archive *" "const char *filename"
  53 .Ft int
  54 .Fo archive_write_open_memory
  55 .Fa "struct archive *"
  56 .Fa "void *buffer"
  57 .Fa "size_t bufferSize"
  58 .Fa "size_t *outUsed"
  59 .Fc
  60 .Sh DESCRIPTION
  61 .Bl -tag -width indent
  62 .It Fn archive_write_open
  63 Freeze the settings, open the archive, and prepare for writing entries.
  64 This is the most generic form of this function, which accepts
  65 pointers to three callback functions which will be invoked by
  66 the compression layer to write the constructed archive.
  67 .It Fn archive_write_open_fd
  68 A convenience form of
  69 .Fn archive_write_open
  70 that accepts a file descriptor.
  71 The
  72 .Fn archive_write_open_fd
  73 function is safe for use with tape drives or other
  74 block-oriented devices.
  75 .It Fn archive_write_open_FILE
  76 A convenience form of
  77 .Fn archive_write_open
  78 that accepts a
  79 .Ft "FILE *"
  80 pointer.
  81 Note that
  82 .Fn archive_write_open_FILE
  83 is not safe for writing to tape drives or other devices
  84 that require correct blocking.
  85 .It Fn archive_write_open_file
  86 A deprecated synonym for
  87 .Fn archive_write_open_filename .
  88 .It Fn archive_write_open_filename
  89 A convenience form of
  90 .Fn archive_write_open
  91 that accepts a filename.
  92 A NULL argument indicates that the output should be written to standard output;
  93 an argument of
  94 .Dq -
  95 will open a file with that name.
  96 If you have not invoked
  97 .Fn archive_write_set_bytes_in_last_block ,
  98 then
  99 .Fn archive_write_open_filename
 100 will adjust the last-block padding depending on the file:
 101 it will enable padding when writing to standard output or
 102 to a character or block device node, it will disable padding otherwise.
 103 You can override this by manually invoking
 104 .Fn archive_write_set_bytes_in_last_block
 105 before calling
 106 .Fn archive_write_open .
 107 The
 108 .Fn archive_write_open_filename
 109 function is safe for use with tape drives or other
 110 block-oriented devices.
 111 .It Fn archive_write_open_memory
 112 A convenience form of
 113 .Fn archive_write_open
 114 that accepts a pointer to a block of memory that will receive
 115 the archive.
 116 The final
 117 .Ft "size_t *"
 118 argument points to a variable that will be updated
 119 after each write to reflect how much of the buffer
 120 is currently in use.
 121 You should be careful to ensure that this variable
 122 remains allocated until after the archive is
 123 closed.
 124 .El
 125 More information about the
 126 .Va struct archive
 127 object and the overall design of the library can be found in the
 128 .Xr libarchive 3
 129 overview.
 130 .\"
 131 .Sh CLIENT CALLBACKS
 132 To use this library, you will need to define and register
 133 callback functions that will be invoked to write data to the
 134 resulting archive.
 135 These functions are registered by calling
 136 .Fn archive_write_open :
 137 .Bl -item -offset indent
 138 .It
 139 .Ft typedef int
 140 .Fn archive_open_callback "struct archive *" "void *client_data"
 141 .El
 142 .Pp
 143 The open callback is invoked by
 144 .Fn archive_write_open .
 145 It should return
 146 .Cm ARCHIVE_OK
 147 if the underlying file or data source is successfully
 148 opened.
 149 If the open fails, it should call
 150 .Fn archive_set_error
 151 to register an error code and message and return
 152 .Cm ARCHIVE_FATAL .
 153 .Bl -item -offset indent
 154 .It
 155 .Ft typedef ssize_t
 156 .Fo archive_write_callback
 157 .Fa "struct archive *"
 158 .Fa "void *client_data"
 159 .Fa "const void *buffer"
 160 .Fa "size_t length"
 161 .Fc
 162 .El
 163 .Pp
 164 The write callback is invoked whenever the library
 165 needs to write raw bytes to the archive.
 166 For correct blocking, each call to the write callback function
 167 should translate into a single
 168 .Xr write 2
 169 system call.
 170 This is especially critical when writing archives to tape drives.
 171 On success, the write callback should return the
 172 number of bytes actually written.
 173 On error, the callback should invoke
 174 .Fn archive_set_error
 175 to register an error code and message and return -1.
 176 .Bl -item -offset indent
 177 .It
 178 .Ft typedef int
 179 .Fn archive_close_callback "struct archive *" "void *client_data"
 180 .El
 181 .Pp
 182 The close callback is invoked by archive_close when
 183 the archive processing is complete.
 184 The callback should return
 185 .Cm ARCHIVE_OK
 186 on success.
 187 On failure, the callback should invoke
 188 .Fn archive_set_error
 189 to register an error code and message and
 190 return
 191 .Cm ARCHIVE_FATAL.
 192 .Pp
 193 Note that if the client-provided write callback function
 194 returns a non-zero value, that error will be propagated back to the caller
 195 through whatever API function resulted in that call, which
 196 may include
 197 .Fn archive_write_header ,
 198 .Fn archive_write_data ,
 199 .Fn archive_write_close ,
 200 .Fn archive_write_finish ,
 201 or
 202 .Fn archive_write_free .
 203 The client callback can call
 204 .Fn archive_set_error
 205 to provide values that can then be retrieved by
 206 .Fn archive_errno
 207 and
 208 .Fn archive_error_string .
 209 .\" .Sh EXAMPLE
 210 .Sh RETURN VALUES
 211 These functions return
 212 .Cm ARCHIVE_OK
 213 on success, or
 214 .Cm ARCHIVE_FATAL .
 215 .\"
 216 .Sh ERRORS
 217 Detailed error codes and textual descriptions are available from the
 218 .Fn archive_errno
 219 and
 220 .Fn archive_error_string
 221 functions.
 222 .\"
 223 .Sh SEE ALSO
 224 .Xr tar 1 ,
 225 .Xr libarchive 3 ,
 226 .Xr archive_write 3 ,
 227 .Xr archive_write_filter 3 ,
 228 .Xr archive_write_format 3 ,
 229 .Xr archive_write_new 3 ,
 230 .Xr archive_write_set_options 3 ,
 231 .Xr cpio 5 ,
 232 .Xr mtree 5 ,
 233 .Xr tar 5