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