1 .\" Copyright (c) 2003-2011 Tim Kientzle
2 .\" All rights reserved.
4 .\" Redistribution and use in source and binary forms, with or without
5 .\" modification, are permitted provided that the following conditions
7 .\" 1. Redistributions of source code must retain the above copyright
8 .\" notice, this list of conditions and the following disclaimer.
9 .\" 2. Redistributions in binary form must reproduce the above copyright
10 .\" notice, this list of conditions and the following disclaimer in the
11 .\" documentation and/or other materials provided with the distribution.
13 .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
14 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
15 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
16 .\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
17 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
18 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
19 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
20 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
21 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
22 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
25 .\" $FreeBSD: head/lib/libarchive/archive_write.3 201110 2009-12-28 03:31:29Z kientzle $
31 .Nm archive_write_open ,
32 .Nm archive_write_open_fd ,
33 .Nm archive_write_open_FILE ,
34 .Nm archive_write_open_filename ,
35 .Nm archive_write_open_memory
36 .Nd functions for creating archives
40 .Fo archive_write_open
41 .Fa "struct archive *"
42 .Fa "void *client_data"
43 .Fa "archive_open_callback *"
44 .Fa "archive_write_callback *"
45 .Fa "archive_close_callback *"
48 .Fn archive_write_open_fd "struct archive *" "int fd"
50 .Fn archive_write_open_FILE "struct archive *" "FILE *file"
52 .Fn archive_write_open_filename "struct archive *" "const char *filename"
54 .Fo archive_write_open_memory
55 .Fa "struct archive *"
57 .Fa "size_t bufferSize"
61 .Bl -tag -width indent
62 .It Fn archive_write_open
63 Freeze the settings, open the archive, and prepare for writing entries.
64 This is the most generic form of this function, which accepts
65 pointers to three callback functions which will be invoked by
66 the compression layer to write the constructed archive.
67 .It Fn archive_write_open_fd
69 .Fn archive_write_open
70 that accepts a file descriptor.
72 .Fn archive_write_open_fd
73 function is safe for use with tape drives or other
74 block-oriented devices.
75 .It Fn archive_write_open_FILE
77 .Fn archive_write_open
82 .Fn archive_write_open_FILE
83 is not safe for writing to tape drives or other devices
84 that require correct blocking.
85 .It Fn archive_write_open_file
86 A deprecated synonym for
87 .Fn archive_write_open_filename .
88 .It Fn archive_write_open_filename
90 .Fn archive_write_open
91 that accepts a filename.
92 A NULL argument indicates that the output should be written to standard output;
95 will open a file with that name.
96 If you have not invoked
97 .Fn archive_write_set_bytes_in_last_block ,
99 .Fn archive_write_open_filename
100 will adjust the last-block padding depending on the file:
101 it will enable padding when writing to standard output or
102 to a character or block device node, it will disable padding otherwise.
103 You can override this by manually invoking
104 .Fn archive_write_set_bytes_in_last_block
106 .Fn archive_write_open .
108 .Fn archive_write_open_filename
109 function is safe for use with tape drives or other
110 block-oriented devices.
111 .It Fn archive_write_open_memory
112 A convenience form of
113 .Fn archive_write_open
114 that accepts a pointer to a block of memory that will receive
118 argument points to a variable that will be updated
119 after each write to reflect how much of the buffer
121 You should be careful to ensure that this variable
122 remains allocated until after the archive is
125 More information about the
127 object and the overall design of the library can be found in the
132 To use this library, you will need to define and register
133 callback functions that will be invoked to write data to the
135 These functions are registered by calling
136 .Fn archive_write_open :
137 .Bl -item -offset indent
140 .Fn archive_open_callback "struct archive *" "void *client_data"
143 The open callback is invoked by
144 .Fn archive_write_open .
147 if the underlying file or data source is successfully
149 If the open fails, it should call
150 .Fn archive_set_error
151 to register an error code and message and return
153 .Bl -item -offset indent
156 .Fo archive_write_callback
157 .Fa "struct archive *"
158 .Fa "void *client_data"
159 .Fa "const void *buffer"
164 The write callback is invoked whenever the library
165 needs to write raw bytes to the archive.
166 For correct blocking, each call to the write callback function
167 should translate into a single
170 This is especially critical when writing archives to tape drives.
171 On success, the write callback should return the
172 number of bytes actually written.
173 On error, the callback should invoke
174 .Fn archive_set_error
175 to register an error code and message and return -1.
176 .Bl -item -offset indent
179 .Fn archive_close_callback "struct archive *" "void *client_data"
182 The close callback is invoked by archive_close when
183 the archive processing is complete.
184 The callback should return
187 On failure, the callback should invoke
188 .Fn archive_set_error
189 to register an error code and message and
193 Note that if the client-provided write callback function
194 returns a non-zero value, that error will be propagated back to the caller
195 through whatever API function resulted in that call, which
197 .Fn archive_write_header ,
198 .Fn archive_write_data ,
199 .Fn archive_write_close ,
200 .Fn archive_write_finish ,
202 .Fn archive_write_free .
203 The client callback can call
204 .Fn archive_set_error
205 to provide values that can then be retrieved by
208 .Fn archive_error_string .
211 These functions return
217 Detailed error codes and textual descriptions are available from the
220 .Fn archive_error_string
226 .Xr archive_write 3 ,
227 .Xr archive_write_filter 3 ,
228 .Xr archive_write_format 3 ,
229 .Xr archive_write_new 3 ,
230 .Xr archive_write_set_options 3 ,