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_free
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_free "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.
172 .It Cm ARCHIVE_EXTRACT_SPARSE
173 Scan data for blocks of NUL bytes and try to recreate them with holes.
174 This results in sparse files, independent of whether the archive format
175 supports or uses them.
178 .Fn archive_write_disk_set_group_lookup ,
179 .Fn archive_write_disk_set_user_lookup
182 .Tn struct archive_entry
183 objects contain both names and ids that can be used to identify users
185 These names and ids describe the ownership of the file itself and
186 also appear in ACL lists.
187 By default, the library uses the ids and ignores the names, but
188 this can be overridden by registering user and group lookup functions.
189 To register, you must provide a lookup function which
190 accepts both a name and id and returns a suitable id.
191 You may also provide a
193 pointer to a private data structure and a cleanup function for
195 The cleanup function will be invoked when the
198 .It Fn archive_write_disk_set_standard_lookup
199 This convenience function installs a standard set of user
200 and group lookup functions.
205 to convert names to ids, defaulting to the ids if the names cannot
207 These functions also implement a simple memory cache to reduce
208 the number of calls to
212 .It Fn archive_write_header
213 Build and write a header using the data in the provided
214 .Tn struct archive_entry
218 for information on creating and populating
219 .Tn struct archive_entry
221 .It Fn archive_write_data
222 Write data corresponding to the header just written.
223 Returns number of bytes written or -1 on error.
224 .It Fn archive_write_finish_entry
225 Close out the entry just written.
226 Ordinarily, clients never need to call this, as it
227 is called automatically by
228 .Fn archive_write_next_header
230 .Fn archive_write_close
232 .It Fn archive_write_close
233 Set any attributes that could not be set during the initial restore.
234 For example, directory timestamps are not restored initially because
235 restoring a subsequent file would alter that timestamp.
236 Similarly, non-writable directories are initially created with
237 write permissions (so that their contents can be restored).
240 library maintains a list of all such deferred attributes and
241 sets them when this function is invoked.
242 .It Fn archive_write_free
244 .Fn archive_write_close
245 if it was not invoked manually, then releases all resources.
247 More information about the
249 object and the overall design of the library can be found in the
252 Many of these functions are also documented under
253 .Xr archive_write 3 .
255 Most functions return
257 (zero) on success, or one of several non-zero
258 error codes for errors.
259 Specific error codes include:
261 for operations that might succeed if retried,
263 for unusual conditions that do not prevent further operations, and
265 for serious errors that make remaining operations impossible.
269 .Fn archive_error_string
270 functions can be used to retrieve an appropriate error code and a
271 textual error message.
273 .Fn archive_write_disk_new
274 returns a pointer to a newly-allocated
278 .Fn archive_write_data
279 returns a count of the number of bytes actually written.
280 On error, -1 is returned and the
283 .Fn archive_error_string
284 functions will return appropriate values.
287 .Xr archive_write 3 ,
293 library first appeared in
296 .Nm archive_write_disk
297 interface was added to
299 and first appeared in
305 library was written by
306 .An Tim Kientzle Aq kientzle@acm.org .
308 Directories are actually extracted in two distinct phases.
309 Directories are created during
310 .Fn archive_write_header ,
311 but final permissions are not set until
312 .Fn archive_write_close .
313 This separation is necessary to correctly handle borderline
314 cases such as a non-writable directory containing
315 files, but can cause unexpected results.
316 In particular, directory permissions are not fully
317 restored until the archive is closed.
320 to change the current directory between calls to
321 .Fn archive_read_extract
323 .Fn archive_read_close ,
324 you may confuse the permission-setting logic with
325 the result that directory permissions are restored
328 The library attempts to create objects with filenames longer than
330 by creating prefixes of the full path and changing the current directory.
331 Currently, this logic is limited in scope; the fixup pass does
332 not work correctly for such objects and the symlink security check
333 option disables the support for very long pathnames.
337 does create each intermediate directory.
338 In particular, the directory
340 is created as well as the final object
342 In theory, this can be exploited to create an entire directory hierarchy
343 with a single request.
344 Of course, this does not work if the
345 .Cm ARCHIVE_EXTRACT_NODOTDOT
348 Implicit directories are always created obeying the current umask.
349 Explicit objects are created obeying the current umask unless
350 .Cm ARCHIVE_EXTRACT_PERM
351 is specified, in which case they current umask is ignored.
353 SGID and SUID bits are restored only if the correct user and
356 .Cm ARCHIVE_EXTRACT_OWNER
357 is not specified, then no attempt is made to set the ownership.
358 In this case, SGID and SUID bits are restored only if the
359 user and group of the final object happen to match those specified
364 user-id and group-id lookup functions are not the defaults because
368 are sometimes too large for particular applications.
369 The current design allows the application author to use a more
370 compact implementation when appropriate.
372 There should be a corresponding
373 .Nm archive_read_disk
374 interface that walks a directory hierarchy and returns archive