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