doc/wiki/ManPageArchiveWriteOpen3.wiki

   1 ARCHIVE_WRITE_OPEN(3) manual page
   2 == NAME ==
   3 '''archive_write_open''',
   4 '''archive_write_open_fd''',
   5 '''archive_write_open_FILE''',
   6 '''archive_write_open_filename''',
   7 '''archive_write_open_memory'''
   8 - functions for creating archives
   9 == LIBRARY ==
  10 Streaming Archive Library (libarchive, -larchive)
  11 == SYNOPSIS ==
  12 '''<nowiki>#include <archive.h></nowiki>'''
  13 <br>
  14 ''int''
  15 <br>
  16 '''archive_write_open'''(''struct archive *'', ''void *client_data'', ''archive_open_callback *'', ''archive_write_callback *'', ''archive_close_callback *'');
  17 <br>
  18 ''int''
  19 <br>
  20 '''archive_write_open_fd'''(''struct archive *'', ''int fd'');
  21 <br>
  22 ''int''
  23 <br>
  24 '''archive_write_open_FILE'''(''struct archive *'', ''FILE *file'');
  25 <br>
  26 ''int''
  27 <br>
  28 '''archive_write_open_filename'''(''struct archive *'', ''const char *filename'');
  29 <br>
  30 ''int''
  31 <br>
  32 '''archive_write_open_memory'''(''struct archive *'', ''void *buffer'', ''size_t bufferSize'', ''size_t *outUsed'');
  33 == DESCRIPTION ==
  34 <dl>
  35 <dt>'''archive_write_open'''()</dt><dd>
  36 Freeze the settings, open the archive, and prepare for writing entries.
  37 This is the most generic form of this function, which accepts
  38 pointers to three callback functions which will be invoked by
  39 the compression layer to write the constructed archive.
  40 This does not alter the default archive padding.
  41 </dd><dt>'''archive_write_open_fd'''()</dt><dd>
  42 A convenience form of
  43 '''archive_write_open'''()
  44 that accepts a file descriptor.
  45 The
  46 '''archive_write_open_fd'''()
  47 function is safe for use with tape drives or other
  48 block-oriented devices.
  49 </dd><dt>'''archive_write_open_FILE'''()</dt><dd>
  50 A convenience form of
  51 '''archive_write_open'''()
  52 that accepts a
  53 ''FILE *''
  54 pointer.
  55 Note that
  56 '''archive_write_open_FILE'''()
  57 is not safe for writing to tape drives or other devices
  58 that require correct blocking.
  59 </dd><dt>'''archive_write_open_file'''()</dt><dd>
  60 A deprecated synonym for
  61 '''archive_write_open_filename'''().
  62 </dd><dt>'''archive_write_open_filename'''()</dt><dd>
  63 A convenience form of
  64 '''archive_write_open'''()
  65 that accepts a filename.
  66 A NULL argument indicates that the output should be written to standard output;
  67 an argument of
  68 "-"
  69 will open a file with that name.
  70 If you have not invoked
  71 '''archive_write_set_bytes_in_last_block'''(),
  72 then
  73 '''archive_write_open_filename'''()
  74 will adjust the last-block padding depending on the file:
  75 it will enable padding when writing to standard output or
  76 to a character or block device node, it will disable padding otherwise.
  77 You can override this by manually invoking
  78 '''archive_write_set_bytes_in_last_block'''()
  79 before calling
  80 '''archive_write_open'''().
  81 The
  82 '''archive_write_open_filename'''()
  83 function is safe for use with tape drives or other
  84 block-oriented devices.
  85 </dd><dt>'''archive_write_open_memory'''()</dt><dd>
  86 A convenience form of
  87 '''archive_write_open'''()
  88 that accepts a pointer to a block of memory that will receive
  89 the archive.
  90 The final
  91 ''size_t *''
  92 argument points to a variable that will be updated
  93 after each write to reflect how much of the buffer
  94 is currently in use.
  95 You should be careful to ensure that this variable
  96 remains allocated until after the archive is
  97 closed.
  98 This function will disable padding unless you
  99 have specifically set the block size.
 100 </dd></dl>
 101 More information about the
 102 ''struct'' archive
 103 object and the overall design of the library can be found in the
 104 [[ManPageibarchive3]]
 105 overview.
 106
 107 Note that the convenience forms above vary in how
 108 they block the output.
 109 See
 110 [[ManPagerchiveritelocksize3]]
 111 if you need to control the block size used for writes
 112 or the end-of-file padding behavior.
 113 == CLIENT CALLBACKS ==
 114 To use this library, you will need to define and register
 115 callback functions that will be invoked to write data to the
 116 resulting archive.
 117 These functions are registered by calling
 118 '''archive_write_open'''():
 119 <ul>
 120 <li>
 121 ''typedef int''
 122 '''archive_open_callback'''(''struct archive *'', ''void *client_data'')
 123 </li></ul>
 124
 125 The open callback is invoked by
 126 '''archive_write_open'''().
 127 It should return
 128 '''ARCHIVE_OK'''
 129 if the underlying file or data source is successfully
 130 opened.
 131 If the open fails, it should call
 132 '''archive_set_error'''()
 133 to register an error code and message and return
 134 '''ARCHIVE_FATAL'''.
 135 <ul>
 136 <li>
 137 ''typedef la_ssize_t''
 138 '''archive_write_callback'''(''struct archive *'', ''void *client_data'', ''const void *buffer'', ''size_t length'')
 139 </li></ul>
 140
 141 The write callback is invoked whenever the library
 142 needs to write raw bytes to the archive.
 143 For correct blocking, each call to the write callback function
 144 should translate into a single
 145 [[write(2)|http://www.freebsd.org/cgi/man.cgi?query=write&sektion=2]]
 146 system call.
 147 This is especially critical when writing archives to tape drives.
 148 On success, the write callback should return the
 149 number of bytes actually written.
 150 On error, the callback should invoke
 151 '''archive_set_error'''()
 152 to register an error code and message and return -1.
 153 <ul>
 154 <li>
 155 ''typedef int''
 156 '''archive_close_callback'''(''struct archive *'', ''void *client_data'')
 157 </li></ul>
 158
 159 The close callback is invoked by archive_close when
 160 the archive processing is complete.
 161 The callback should return
 162 '''ARCHIVE_OK'''
 163 on success.
 164 On failure, the callback should invoke
 165 '''archive_set_error'''()
 166 to register an error code and message and
 167 return
 168 '''ARCHIVE_FATAL.'''
 169
 170 Note that if the client-provided write callback function
 171 returns a non-zero value, that error will be propagated back to the caller
 172 through whatever API function resulted in that call, which
 173 may include
 174 '''archive_write_header'''(),
 175 '''archive_write_data'''(),
 176 '''archive_write_close'''(),
 177 '''archive_write_finish'''(),
 178 or
 179 '''archive_write_free'''().
 180 The client callback can call
 181 '''archive_set_error'''()
 182 to provide values that can then be retrieved by
 183 '''archive_errno'''()
 184 and
 185 '''archive_error_string'''().
 186 == RETURN VALUES ==
 187 These functions return
 188 '''ARCHIVE_OK'''
 189 on success, or
 190 '''ARCHIVE_FATAL'''.
 191 == ERRORS ==
 192 Detailed error codes and textual descriptions are available from the
 193 '''archive_errno'''()
 194 and
 195 '''archive_error_string'''()
 196 functions.
 197 == SEE ALSO ==
 198 [[ManPageBsdtar1]],
 199 [[ManPageibarchive3]],
 200 [[ManPagerchiverite3]],
 201 [[ManPagerchiveritelocksize3]],
 202 [[ManPagerchiveriteilter3]],
 203 [[ManPagerchiveriteormat3]],
 204 [[ManPagerchiveriteew3]],
 205 [[ManPagerchiveriteetptions3]],
 206 [[ManPageCpio5]],
 207 [[ManPageMtree5]],
 208 [[ManPageTar5]]