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
25
.\" $FreeBSD: src/lib/libarchive/archive_write_disk.3,v 1.4 2008/09/04 05:22:00 kientzle Exp $
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.
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_finish
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 heirarchy
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 heirarchy and returns archive
b'\\ No newline at end of file'
added
removed
src/libarchive/libarchive/archive_write_disk.3
