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