1 .\" Copyright (c) 2003-2007 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
28 .Dt archive_write_disk 3
31 .Nm archive_write_disk_new ,
32 .Nm archive_write_disk_set_options ,
33 .Nm archive_write_disk_set_skip_file ,
34 .Nm archive_write_disk_set_group_lookup ,
35 .Nm archive_write_disk_set_standard_lookup ,
36 .Nm archive_write_disk_set_user_lookup ,
37 .Nm archive_write_header ,
38 .Nm archive_write_data ,
39 .Nm archive_write_finish_entry ,
40 .Nm archive_write_close ,
41 .Nm archive_write_finish
42 .Nd functions for creating objects on disk
46 .Fn archive_write_disk_new "void"
48 .Fn archive_write_disk_set_options "struct archive *" "int flags"
50 .Fn archive_write_disk_set_skip_file "struct archive *" "dev_t" "ino_t"
52 .Fo archive_write_disk_set_group_lookup
53 .Fa "struct archive *"
55 .Fa "gid_t (*)(void *, const char *gname, gid_t gid)"
56 .Fa "void (*cleanup)(void *)"
59 .Fn archive_write_disk_set_standard_lookup "struct archive *"
61 .Fo archive_write_disk_set_user_lookup
62 .Fa "struct archive *"
64 .Fa "uid_t (*)(void *, const char *uname, uid_t uid)"
65 .Fa "void (*cleanup)(void *)"
68 .Fn archive_write_header "struct archive *" "struct archive_entry *"
70 .Fn archive_write_data "struct archive *" "const void *" "size_t"
72 .Fn archive_write_finish_entry "struct archive *"
74 .Fn archive_write_close "struct archive *"
76 .Fn archive_write_finish "struct archive *"
78 These functions provide a complete API for creating objects on
80 .Tn struct archive_entry
82 They are most naturally used when extracting objects from an archive
86 The general process is to read
87 .Tn struct archive_entry
88 objects from an archive, then write those objects to a
90 object created using the
91 .Fn archive_write_disk
93 This interface is deliberately very similar to the
95 interface used to write objects to a streaming archive.
96 .Bl -tag -width indent
97 .It Fn archive_write_disk_new
98 Allocates and initializes a
100 object suitable for writing objects to disk.
101 .It Fn archive_write_disk_set_skip_file
102 Records the device and inode numbers of a file that should not be
104 This is typically used to ensure that an extraction process does not
105 overwrite the archive from which objects are being read.
106 This capability is technically unnecessary but can be a significant
107 performance optimization in practice.
108 .It Fn archive_write_disk_set_options
109 The options field consists of a bitwise OR of one or more of the
111 .Bl -tag -compact -width "indent"
112 .It Cm ARCHIVE_EXTRACT_OWNER
113 The user and group IDs should be set on the restored file.
114 By default, the user and group IDs are not restored.
115 .It Cm ARCHIVE_EXTRACT_PERM
116 Full permissions (including SGID, SUID, and sticky bits) should
117 be restored exactly as specified, without obeying the
119 Note that SUID and SGID bits can only be restored if the
120 user and group ID of the object on disk are correct.
122 .Cm ARCHIVE_EXTRACT_OWNER
123 is not specified, then SUID and SGID bits will only be restored
124 if the default user and group IDs of newly-created objects on disk
125 happen to match those specified in the archive entry.
126 By default, only basic permissions are restored, and umask is obeyed.
127 .It Cm ARCHIVE_EXTRACT_TIME
128 The timestamps (mtime, ctime, and atime) should be restored.
129 By default, they are ignored.
130 Note that restoring of atime is not currently supported.
131 .It Cm ARCHIVE_EXTRACT_NO_OVERWRITE
132 Existing files on disk will not be overwritten.
133 By default, existing regular files are truncated and overwritten;
134 existing directories will have their permissions updated;
135 other pre-existing objects are unlinked and recreated from scratch.
136 .It Cm ARCHIVE_EXTRACT_UNLINK
137 Existing files on disk will be unlinked before any attempt to
139 In some cases, this can prove to be a significant performance improvement.
140 By default, existing files are truncated and rewritten, but
141 the file is not recreated.
142 In particular, the default behavior does not break existing hard links.
143 .It Cm ARCHIVE_EXTRACT_ACL
144 Attempt to restore ACLs.
145 By default, extended ACLs are ignored.
146 .It Cm ARCHIVE_EXTRACT_FFLAGS
147 Attempt to restore extended file flags.
148 By default, file flags are ignored.
149 .It Cm ARCHIVE_EXTRACT_XATTR
150 Attempt to restore POSIX.1e extended attributes.
151 By default, they are ignored.
152 .It Cm ARCHIVE_EXTRACT_SECURE_SYMLINKS
153 Refuse to extract any object whose final location would be altered
154 by a symlink on disk.
155 This is intended to help guard against a variety of mischief
156 caused by archives that (deliberately or otherwise) extract
157 files outside of the current directory.
158 The default is not to perform this check.
160 .Cm ARCHIVE_EXTRACT_UNLINK
161 is specified together with this option, the library will
162 remove any intermediate symlinks it finds and return an
163 error only if such symlink could not be removed.
164 .It Cm ARCHIVE_EXTRACT_SECURE_NODOTDOT
165 Refuse to extract a path that contains a
167 element anywhere within it.
168 The default is to not refuse such paths.
169 Note that paths ending in
171 always cause an error, regardless of this flag.
174 .Fn archive_write_disk_set_group_lookup ,
175 .Fn archive_write_disk_set_user_lookup
178 .Tn struct archive_entry
179 objects contain both names and ids that can be used to identify users
181 These names and ids describe the ownership of the file itself and
182 also appear in ACL lists.
183 By default, the library uses the ids and ignores the names, but
184 this can be overridden by registering user and group lookup functions.
185 To register, you must provide a lookup function which
186 accepts both a name and id and returns a suitable id.
187 You may also provide a
189 pointer to a private data structure and a cleanup function for
191 The cleanup function will be invoked when the
194 .It Fn archive_write_disk_set_standard_lookup
195 This convenience function installs a standard set of user
196 and group lookup functions.
201 to convert names to ids, defaulting to the ids if the names cannot
203 These functions also implement a simple memory cache to reduce
204 the number of calls to
208 .It Fn archive_write_header
209 Build and write a header using the data in the provided
210 .Tn struct archive_entry
214 for information on creating and populating
215 .Tn struct archive_entry
217 .It Fn archive_write_data
218 Write data corresponding to the header just written.
219 Returns number of bytes written or -1 on error.
220 .It Fn archive_write_finish_entry
221 Close out the entry just written.
222 Ordinarily, clients never need to call this, as it
223 is called automatically by
224 .Fn archive_write_next_header
226 .Fn archive_write_close
228 .It Fn archive_write_close
229 Set any attributes that could not be set during the initial restore.
230 For example, directory timestamps are not restored initially because
231 restoring a subsequent file would alter that timestamp.
232 Similarly, non-writable directories are initially created with
233 write permissions (so that their contents can be restored).
236 library maintains a list of all such deferred attributes and
237 sets them when this function is invoked.
238 .It Fn archive_write_finish
240 .Fn archive_write_close
241 if it was not invoked manually, then releases all resources.
243 More information about the
245 object and the overall design of the library can be found in the
248 Many of these functions are also documented under
249 .Xr archive_write 3 .
251 Most functions return
253 (zero) on success, or one of several non-zero
254 error codes for errors.
255 Specific error codes include:
257 for operations that might succeed if retried,
259 for unusual conditions that do not prevent further operations, and
261 for serious errors that make remaining operations impossible.
265 .Fn archive_error_string
266 functions can be used to retrieve an appropriate error code and a
267 textual error message.
269 .Fn archive_write_disk_new
270 returns a pointer to a newly-allocated
274 .Fn archive_write_data
275 returns a count of the number of bytes actually written.
276 On error, -1 is returned and the
279 .Fn archive_error_string
280 functions will return appropriate values.
283 .Xr archive_write 3 ,
289 library first appeared in
292 .Nm archive_write_disk
293 interface was added to
295 and first appeared in
301 library was written by
302 .An Tim Kientzle Aq kientzle@acm.org .
304 Directories are actually extracted in two distinct phases.
305 Directories are created during
306 .Fn archive_write_header ,
307 but final permissions are not set until
308 .Fn archive_write_close .
309 This separation is necessary to correctly handle borderline
310 cases such as a non-writable directory containing
311 files, but can cause unexpected results.
312 In particular, directory permissions are not fully
313 restored until the archive is closed.
316 to change the current directory between calls to
317 .Fn archive_read_extract
319 .Fn archive_read_close ,
320 you may confuse the permission-setting logic with
321 the result that directory permissions are restored
324 The library attempts to create objects with filenames longer than
326 by creating prefixes of the full path and changing the current directory.
327 Currently, this logic is limited in scope; the fixup pass does
328 not work correctly for such objects and the symlink security check
329 option disables the support for very long pathnames.
333 does create each intermediate directory.
334 In particular, the directory
336 is created as well as the final object
338 In theory, this can be exploited to create an entire directory heirarchy
339 with a single request.
340 Of course, this does not work if the
341 .Cm ARCHIVE_EXTRACT_NODOTDOT
344 Implicit directories are always created obeying the current umask.
345 Explicit objects are created obeying the current umask unless
346 .Cm ARCHIVE_EXTRACT_PERM
347 is specified, in which case they current umask is ignored.
349 SGID and SUID bits are restored only if the correct user and
352 .Cm ARCHIVE_EXTRACT_OWNER
353 is not specified, then no attempt is made to set the ownership.
354 In this case, SGID and SUID bits are restored only if the
355 user and group of the final object happen to match those specified
360 user-id and group-id lookup functions are not the defaults because
364 are sometimes too large for particular applications.
365 The current design allows the application author to use a more
366 compact implementation when appropriate.
368 There should be a corresponding
369 .Nm archive_read_disk
370 interface that walks a directory heirarchy and returns archive