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 .Nd functions for creating objects on disk
39 Streaming Archive Library (libarchive, -larchive)
43 .Fn archive_write_disk_new "void"
45 .Fn archive_write_disk_set_options "struct archive *" "int flags"
47 .Fn archive_write_disk_set_skip_file "struct archive *" "dev_t" "ino_t"
49 .Fo archive_write_disk_set_group_lookup
50 .Fa "struct archive *"
52 .Fa "gid_t (*)(void *, const char *gname, gid_t gid)"
53 .Fa "void (*cleanup)(void *)"
56 .Fn archive_write_disk_set_standard_lookup "struct archive *"
58 .Fo archive_write_disk_set_user_lookup
59 .Fa "struct archive *"
61 .Fa "uid_t (*)(void *, const char *uname, uid_t uid)"
62 .Fa "void (*cleanup)(void *)"
65 These functions provide a complete API for creating objects on
67 .Tn struct archive_entry
69 They are most naturally used when extracting objects from an archive
73 The general process is to read
74 .Tn struct archive_entry
75 objects from an archive, then write those objects to a
77 object created using the
78 .Fn archive_write_disk
80 This interface is deliberately very similar to the
82 interface used to write objects to a streaming archive.
83 .Bl -tag -width indent
84 .It Fn archive_write_disk_new
85 Allocates and initializes a
87 object suitable for writing objects to disk.
88 .It Fn archive_write_disk_set_skip_file
89 Records the device and inode numbers of a file that should not be
91 This is typically used to ensure that an extraction process does not
92 overwrite the archive from which objects are being read.
93 This capability is technically unnecessary but can be a significant
94 performance optimization in practice.
95 .It Fn archive_write_disk_set_options
96 The options field consists of a bitwise OR of one or more of the
98 .Bl -tag -compact -width "indent"
99 .It Cm ARCHIVE_EXTRACT_ACL
100 Attempt to restore Access Control Lists.
101 By default, extended ACLs are ignored.
102 .It Cm ARCHIVE_EXTRACT_CLEAR_NOCHANGE_FFLAGS
103 Before removing a file system object prior to replacing it, clear
104 platform-specific file flags which might prevent its removal.
105 .It Cm ARCHIVE_EXTRACT_FFLAGS
106 Attempt to restore file attributes (file flags).
107 By default, file attributes are ignored.
113 .Pq FreeBSD, Mac OS X
114 for more information on file attributes.
115 .It Cm ARCHIVE_EXTRACT_MAC_METADATA
117 Restore metadata using
122 .It Cm ARCHIVE_EXTRACT_NO_OVERWRITE
123 Existing files on disk will not be overwritten.
124 By default, existing regular files are truncated and overwritten;
125 existing directories will have their permissions updated;
126 other pre-existing objects are unlinked and recreated from scratch.
127 .It Cm ARCHIVE_EXTRACT_OWNER
128 The user and group IDs should be set on the restored file.
129 By default, the user and group IDs are not restored.
130 .It Cm ARCHIVE_EXTRACT_PERM
131 Full permissions (including SGID, SUID, and sticky bits) should
132 be restored exactly as specified, without obeying the
134 Note that SUID and SGID bits can only be restored if the
135 user and group ID of the object on disk are correct.
137 .Cm ARCHIVE_EXTRACT_OWNER
138 is not specified, then SUID and SGID bits will only be restored
139 if the default user and group IDs of newly-created objects on disk
140 happen to match those specified in the archive entry.
141 By default, only basic permissions are restored, and umask is obeyed.
142 .It Cm ARCHIVE_EXTRACT_SAFE_WRITES
143 Extract files atomically, by first creating a unique temporary file and then
144 renaming it to its required destination name.
145 This avoids a race where an application might see a partial file (or no
146 file) during extraction.
147 .It Cm ARCHIVE_EXTRACT_SECURE_NOABSOLUTEPATHS
148 Refuse to extract an absolute path.
149 The default is to not refuse such paths.
150 .It Cm ARCHIVE_EXTRACT_SECURE_NODOTDOT
151 Refuse to extract a path that contains a
153 element anywhere within it.
154 The default is to not refuse such paths.
155 Note that paths ending in
157 always cause an error, regardless of this flag.
158 .It Cm ARCHIVE_EXTRACT_SECURE_SYMLINKS
159 Refuse to extract any object whose final location would be altered
160 by a symlink on disk.
161 This is intended to help guard against a variety of mischief
162 caused by archives that (deliberately or otherwise) extract
163 files outside of the current directory.
164 The default is not to perform this check.
166 .It Cm ARCHIVE_EXTRACT_SPARSE
167 Scan data for blocks of NUL bytes and try to recreate them with holes.
168 This results in sparse files, independent of whether the archive format
169 supports or uses them.
170 .Cm ARCHIVE_EXTRACT_UNLINK
171 is specified together with this option, the library will
172 remove any intermediate symlinks it finds and return an
173 error only if such symlink could not be removed.
174 .It Cm ARCHIVE_EXTRACT_TIME
175 The timestamps (mtime, ctime, and atime) should be restored.
176 By default, they are ignored.
177 Note that restoring of atime is not currently supported.
178 .It Cm ARCHIVE_EXTRACT_UNLINK
179 Existing files on disk will be unlinked before any attempt to
181 In some cases, this can prove to be a significant performance improvement.
182 By default, existing files are truncated and rewritten, but
183 the file is not recreated.
184 In particular, the default behavior does not break existing hard links.
185 .It Cm ARCHIVE_EXTRACT_XATTR
186 Attempt to restore extended file attributes.
187 By default, they are ignored.
196 for more information on extended file attributes.
199 .Fn archive_write_disk_set_group_lookup ,
200 .Fn archive_write_disk_set_user_lookup
203 .Tn struct archive_entry
204 objects contain both names and ids that can be used to identify users
206 These names and ids describe the ownership of the file itself and
207 also appear in ACL lists.
208 By default, the library uses the ids and ignores the names, but
209 this can be overridden by registering user and group lookup functions.
210 To register, you must provide a lookup function which
211 accepts both a name and id and returns a suitable id.
212 You may also provide a
214 pointer to a private data structure and a cleanup function for
216 The cleanup function will be invoked when the
219 .It Fn archive_write_disk_set_standard_lookup
220 This convenience function installs a standard set of user
221 and group lookup functions.
226 to convert names to ids, defaulting to the ids if the names cannot
228 These functions also implement a simple memory cache to reduce
229 the number of calls to
234 More information about the
236 object and the overall design of the library can be found in the
239 Many of these functions are also documented under
240 .Xr archive_write 3 .
242 Most functions return
244 (zero) on success, or one of several non-zero
245 error codes for errors.
246 Specific error codes include:
248 for operations that might succeed if retried,
250 for unusual conditions that do not prevent further operations, and
252 for serious errors that make remaining operations impossible.
254 .Fn archive_write_disk_new
255 returns a pointer to a newly-allocated
259 .Fn archive_write_data
260 returns a count of the number of bytes actually written,
266 Detailed error codes and textual descriptions are available from the
269 .Fn archive_error_string
275 .Xr archive_write 3 ,
280 library first appeared in
283 .Nm archive_write_disk
284 interface was added to
286 and first appeared in
292 library was written by
293 .An Tim Kientzle Aq kientzle@acm.org .
295 Directories are actually extracted in two distinct phases.
296 Directories are created during
297 .Fn archive_write_header ,
298 but final permissions are not set until
299 .Fn archive_write_close .
300 This separation is necessary to correctly handle borderline
301 cases such as a non-writable directory containing
302 files, but can cause unexpected results.
303 In particular, directory permissions are not fully
304 restored until the archive is closed.
307 to change the current directory between calls to
308 .Fn archive_read_extract
310 .Fn archive_read_close ,
311 you may confuse the permission-setting logic with
312 the result that directory permissions are restored
315 The library attempts to create objects with filenames longer than
317 by creating prefixes of the full path and changing the current directory.
318 Currently, this logic is limited in scope; the fixup pass does
319 not work correctly for such objects and the symlink security check
320 option disables the support for very long pathnames.
324 does create each intermediate directory.
325 In particular, the directory
327 is created as well as the final object
329 In theory, this can be exploited to create an entire directory hierarchy
330 with a single request.
331 Of course, this does not work if the
332 .Cm ARCHIVE_EXTRACT_NODOTDOT
335 Implicit directories are always created obeying the current umask.
336 Explicit objects are created obeying the current umask unless
337 .Cm ARCHIVE_EXTRACT_PERM
338 is specified, in which case they current umask is ignored.
340 SGID and SUID bits are restored only if the correct user and
343 .Cm ARCHIVE_EXTRACT_OWNER
344 is not specified, then no attempt is made to set the ownership.
345 In this case, SGID and SUID bits are restored only if the
346 user and group of the final object happen to match those specified
351 user-id and group-id lookup functions are not the defaults because
355 are sometimes too large for particular applications.
356 The current design allows the application author to use a more
357 compact implementation when appropriate.
359 There should be a corresponding
360 .Nm archive_read_disk
361 interface that walks a directory hierarchy and returns archive