doc/html/archive_write_open.3.html

   1 <!-- Creator     : groff version 1.22.4 -->
   2 <!-- CreationDate: Mon Dec 30 01:41:24 2019 -->
   3 <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"
   4 "http://www.w3.org/TR/html4/loose.dtd">
   5 <html>
   6 <head>
   7 <meta name="generator" content="groff -Thtml, see www.gnu.org">
   8 <meta http-equiv="Content-Type" content="text/html; charset=US-ASCII">
   9 <meta name="Content-Style" content="text/css">
  10 <style type="text/css">
  11        p       { margin-top: 0; margin-bottom: 0; vertical-align: top }
  12        pre     { margin-top: 0; margin-bottom: 0; vertical-align: top }
  13        table   { margin-top: 0; margin-bottom: 0; vertical-align: top }
  14        h1      { text-align: center }
  15 </style>
  16 <title></title>
  17 </head>
  18 <body>
  19
  20 <hr>
  21
  22
  23 <p>ARCHIVE_WRITE_OPEN(3) BSD Library Functions Manual
  24 ARCHIVE_WRITE_OPEN(3)</p>
  25
  26 <p style="margin-top: 1em"><b>NAME</b></p>
  27
  28 <p style="margin-left:6%;"><b>archive_write_open</b>,
  29 <b>archive_write_open_fd</b>,
  30 <b>archive_write_open_FILE</b>,
  31 <b>archive_write_open_filename</b>,
  32 <b>archive_write_open_memory</b> &mdash; functions for
  33 creating archives</p>
  34
  35 <p style="margin-top: 1em"><b>LIBRARY</b></p>
  36
  37 <p style="margin-left:6%;">Streaming Archive Library
  38 (libarchive, -larchive)</p>
  39
  40 <p style="margin-top: 1em"><b>SYNOPSIS</b></p>
  41
  42 <p style="margin-left:6%;"><b>#include
  43 &lt;archive.h&gt;</b></p>
  44
  45 <p style="margin-left:6%; margin-top: 1em"><i>int</i></p>
  46
  47
  48 <p><b>archive_write_open</b>(<i>struct&nbsp;archive&nbsp;*</i>,
  49 <i>void&nbsp;*client_data</i>,
  50 <i>archive_open_callback&nbsp;*</i>,
  51 <i>archive_write_callback&nbsp;*</i>,
  52 <i>archive_close_callback&nbsp;*</i>);</p>
  53
  54 <p style="margin-left:6%; margin-top: 1em"><i>int</i></p>
  55
  56
  57 <p style="margin-left:12%;"><b>archive_write_open_fd</b>(<i>struct&nbsp;archive&nbsp;*</i>,
  58 <i>int&nbsp;fd</i>);</p>
  59
  60 <p style="margin-left:6%; margin-top: 1em"><i>int</i></p>
  61
  62
  63 <p style="margin-left:12%;"><b>archive_write_open_FILE</b>(<i>struct&nbsp;archive&nbsp;*</i>,
  64 <i>FILE&nbsp;*file</i>);</p>
  65
  66 <p style="margin-left:6%; margin-top: 1em"><i>int</i></p>
  67
  68
  69 <p style="margin-left:12%;"><b>archive_write_open_filename</b>(<i>struct&nbsp;archive&nbsp;*</i>,
  70 <i>const&nbsp;char&nbsp;*filename</i>);</p>
  71
  72 <p style="margin-left:6%; margin-top: 1em"><i>int</i></p>
  73
  74
  75 <p><b>archive_write_open_memory</b>(<i>struct&nbsp;archive&nbsp;*</i>,
  76 <i>void&nbsp;*buffer</i>, <i>size_t&nbsp;bufferSize</i>,
  77 <i>size_t&nbsp;*outUsed</i>);</p>
  78
  79 <p style="margin-top: 1em"><b>DESCRIPTION <br>
  80 archive_write_open</b>()</p>
  81
  82 <p style="margin-left:17%;">Freeze the settings, open the
  83 archive, and prepare for writing entries. This is the most
  84 generic form of this function, which accepts pointers to
  85 three callback functions which will be invoked by the
  86 compression layer to write the constructed archive. This
  87 does not alter the default archive padding.</p>
  88
  89
  90 <p style="margin-top: 1em"><b>archive_write_open_fd</b>()</p>
  91
  92 <p style="margin-left:17%;">A convenience form of
  93 <b>archive_write_open</b>() that accepts a file descriptor.
  94 The <b>archive_write_open_fd</b>() function is safe for use
  95 with tape drives or other block-oriented devices.</p>
  96
  97
  98 <p style="margin-top: 1em"><b>archive_write_open_FILE</b>()</p>
  99
 100 <p style="margin-left:17%;">A convenience form of
 101 <b>archive_write_open</b>() that accepts a <i>FILE *</i>
 102 pointer. Note that <b>archive_write_open_FILE</b>() is not
 103 safe for writing to tape drives or other devices that
 104 require correct blocking.</p>
 105
 106
 107 <p style="margin-top: 1em"><b>archive_write_open_file</b>()</p>
 108
 109 <p style="margin-left:17%;">A deprecated synonym for
 110 <b>archive_write_open_filename</b>().</p>
 111
 112
 113 <p style="margin-top: 1em"><b>archive_write_open_filename</b>()</p>
 114
 115 <p style="margin-left:17%;">A convenience form of
 116 <b>archive_write_open</b>() that accepts a filename. A NULL
 117 argument indicates that the output should be written to
 118 standard output; an argument of &ldquo;-&rdquo; will open a
 119 file with that name. If you have not invoked
 120 <b>archive_write_set_bytes_in_last_block</b>(), then
 121 <b>archive_write_open_filename</b>() will adjust the
 122 last-block padding depending on the file: it will enable
 123 padding when writing to standard output or to a character or
 124 block device node, it will disable padding otherwise. You
 125 can override this by manually invoking
 126 <b>archive_write_set_bytes_in_last_block</b>() before
 127 calling <b>archive_write_open</b>(). The
 128 <b>archive_write_open_filename</b>() function is safe for
 129 use with tape drives or other block-oriented devices.</p>
 130
 131
 132 <p style="margin-top: 1em"><b>archive_write_open_memory</b>()</p>
 133
 134 <p style="margin-left:17%;">A convenience form of
 135 <b>archive_write_open</b>() that accepts a pointer to a
 136 block of memory that will receive the archive. The final
 137 <i>size_t *</i> argument points to a variable that will be
 138 updated after each write to reflect how much of the buffer
 139 is currently in use. You should be careful to ensure that
 140 this variable remains allocated until after the archive is
 141 closed. This function will disable padding unless you have
 142 specifically set the block size.</p>
 143
 144 <p style="margin-left:6%;">More information about the
 145 <i>struct archive</i> object and the overall design of the
 146 library can be found in the libarchive(3) overview.</p>
 147
 148 <p style="margin-left:6%; margin-top: 1em">Note that the
 149 convenience forms above vary in how they block the output.
 150 See archive_write_blocksize(3) if you need to control the
 151 block size used for writes or the end-of-file padding
 152 behavior.</p>
 153
 154 <p style="margin-top: 1em"><b>CLIENT CALLBACKS</b></p>
 155
 156 <p style="margin-left:6%;">To use this library, you will
 157 need to define and register callback functions that will be
 158 invoked to write data to the resulting archive. These
 159 functions are registered by calling
 160 <b>archive_write_open</b>():</p>
 161
 162 <p style="margin-left:14%; margin-top: 1em"><i>typedef
 163 int</i> <b>archive_open_callback</b>(<i>struct archive
 164 *</i>, <i>void *client_data</i>)</p>
 165
 166 <p style="margin-left:6%; margin-top: 1em">The open
 167 callback is invoked by <b>archive_write_open</b>(). It
 168 should return <b>ARCHIVE_OK</b> if the underlying file or
 169 data source is successfully opened. If the open fails, it
 170 should call <b>archive_set_error</b>() to register an error
 171 code and message and return <b>ARCHIVE_FATAL</b>.</p>
 172
 173 <p style="margin-left:14%; margin-top: 1em"><i>typedef
 174 la_ssize_t</i></p>
 175
 176
 177 <p><b>archive_write_callback</b>(<i>struct&nbsp;archive&nbsp;*</i>,
 178 <i>void&nbsp;*client_data</i>,
 179 <i>const&nbsp;void&nbsp;*buffer</i>,
 180 <i>size_t&nbsp;length</i>)</p>
 181
 182 <p style="margin-left:6%; margin-top: 1em">The write
 183 callback is invoked whenever the library needs to write raw
 184 bytes to the archive. For correct blocking, each call to the
 185 write callback function should translate into a single
 186 write(2) system call. This is especially critical when
 187 writing archives to tape drives. On success, the write
 188 callback should return the number of bytes actually written.
 189 On error, the callback should invoke
 190 <b>archive_set_error</b>() to register an error code and
 191 message and return -1.</p>
 192
 193 <p style="margin-left:14%; margin-top: 1em"><i>typedef
 194 int</i> <b>archive_close_callback</b>(<i>struct archive
 195 *</i>, <i>void *client_data</i>)</p>
 196
 197 <p style="margin-left:6%; margin-top: 1em">The close
 198 callback is invoked by archive_close when the archive
 199 processing is complete. The callback should return
 200 <b>ARCHIVE_OK</b> on success. On failure, the callback
 201 should invoke <b>archive_set_error</b>() to register an
 202 error code and message and return <b>ARCHIVE_FATAL</b>.</p>
 203
 204 <p style="margin-left:6%; margin-top: 1em">Note that if the
 205 client-provided write callback function returns a non-zero
 206 value, that error will be propagated back to the caller
 207 through whatever API function resulted in that call, which
 208 may include <b>archive_write_header</b>(),
 209 <b>archive_write_data</b>(), <b>archive_write_close</b>(),
 210 <b>archive_write_finish</b>(), or
 211 <b>archive_write_free</b>(). The client callback can call
 212 <b>archive_set_error</b>() to provide values that can then
 213 be retrieved by <b>archive_errno</b>() and
 214 <b>archive_error_string</b>().</p>
 215
 216 <p style="margin-top: 1em"><b>RETURN VALUES</b></p>
 217
 218 <p style="margin-left:6%;">These functions return
 219 <b>ARCHIVE_OK</b> on success, or <b>ARCHIVE_FATAL</b>.</p>
 220
 221 <p style="margin-top: 1em"><b>ERRORS</b></p>
 222
 223 <p style="margin-left:6%;">Detailed error codes and textual
 224 descriptions are available from the <b>archive_errno</b>()
 225 and <b>archive_error_string</b>() functions.</p>
 226
 227 <p style="margin-top: 1em"><b>SEE ALSO</b></p>
 228
 229 <p style="margin-left:6%;">tar(1), archive_write(3),
 230 archive_write_blocksize(3), archive_write_filter(3),
 231 archive_write_format(3), archive_write_new(3),
 232 archive_write_set_options(3), libarchive(3), cpio(5),
 233 mtree(5), tar(5)</p>
 234
 235 <p style="margin-left:6%; margin-top: 1em">BSD
 236 February&nbsp;2, 2012 BSD</p>
 237 <hr>
 238 </body>
 239 </html>