1ARCHIVE_WRITE_DISK(3) BSD Library Functions Manual ARCHIVE_WRITE_DISK(3)
2
4 archive_write_disk_new, archive_write_disk_set_options,
5 archive_write_disk_set_skip_file, archive_write_disk_set_group_lookup,
6 archive_write_disk_set_standard_lookup,
7 archive_write_disk_set_user_lookup, archive_write_header,
8 archive_write_data, archive_write_data_block, archive_write_finish_entry,
9 archive_write_close, archive_write_finish archive_write_free — functions
10 for creating objects on disk
11
13 Streaming Archive Library (libarchive, -larchive)
14
16 #include <archive.h>
17 struct archive *
19 archive_write_disk_new(void);
20 int
22 archive_write_disk_set_options(struct archive *, int flags);
23 int
25 archive_write_disk_set_skip_file(struct archive *, dev_t, ino_t);
26 int
28 archive_write_disk_set_group_lookup(struct archive *, void *,
29 gid_t (*)(void *, const char *gname, gid_t gid),
30 void (*cleanup)(void *));
31 int
33 archive_write_disk_set_standard_lookup(struct archive *);
34 int
36 archive_write_disk_set_user_lookup(struct archive *, void *,
37 uid_t (*)(void *, const char *uname, uid_t uid),
38 void (*cleanup)(void *));
39 int
41 archive_write_header(struct archive *, struct archive_entry *);
42 ssize_t
44 archive_write_data(struct archive *, const void *, size_t);
45 ssize_t
47 archive_write_data_block(struct archive *, const void *, size_t size,
48 int64_t offset);
49 int
51 archive_write_finish_entry(struct archive *);
52 int
54 archive_write_close(struct archive *);
55 int
57 archive_write_finish(struct archive *);
58 int
60 archive_write_free(struct archive *);
61
63 These functions provide a complete API for creating objects on disk from
64 struct archive_entry descriptions. They are most naturally used when
65 extracting objects from an archive using the archive_read() interface.
66 The general process is to read struct archive_entry objects from an ar‐
67 chive, then write those objects to a struct archive object created using
68 the archive_write_disk() family functions. This interface is deliber‐
69 ately very similar to the archive_write() interface used to write objects
70 to a streaming archive.
71 archive_write_disk_new()
73 Allocates and initializes a struct archive object suitable for
74 writing objects to disk.
75 archive_write_disk_set_skip_file()
77 Records the device and inode numbers of a file that should not be
78 overwritten. This is typically used to ensure that an extraction
79 process does not overwrite the archive from which objects are
80 being read. This capability is technically unnecessary but can
81 be a significant performance optimization in practice.
82 archive_write_disk_set_options()
84 The options field consists of a bitwise OR of one or more of the
85 following values:
86 ARCHIVE_EXTRACT_OWNER
87 The user and group IDs should be set on the restored
88 file. By default, the user and group IDs are not
89 restored.
90 ARCHIVE_EXTRACT_PERM
91 Full permissions (including SGID, SUID, and sticky bits)
92 should be restored exactly as specified, without obeying
93 the current umask. Note that SUID and SGID bits can only
94 be restored if the user and group ID of the object on
95 disk are correct. If ARCHIVE_EXTRACT_OWNER is not speci‐
96 fied, then SUID and SGID bits will only be restored if
97 the default user and group IDs of newly-created objects
98 on disk happen to match those specified in the archive
99 entry. By default, only basic permissions are restored,
100 and umask is obeyed.
101 ARCHIVE_EXTRACT_TIME
102 The timestamps (mtime, ctime, and atime) should be
103 restored. By default, they are ignored. Note that
104 restoring of atime is not currently supported.
105 ARCHIVE_EXTRACT_NO_OVERWRITE
106 Existing files on disk will not be overwritten. By
107 default, existing regular files are truncated and over‐
108 written; existing directories will have their permissions
109 updated; other pre-existing objects are unlinked and
110 recreated from scratch.
111 ARCHIVE_EXTRACT_UNLINK
112 Existing files on disk will be unlinked before any
113 attempt to create them. In some cases, this can prove to
114 be a significant performance improvement. By default,
115 existing files are truncated and rewritten, but the file
116 is not recreated. In particular, the default behavior
117 does not break existing hard links.
118 ARCHIVE_EXTRACT_ACL
119 Attempt to restore ACLs. By default, extended ACLs are
120 ignored.
121 ARCHIVE_EXTRACT_FFLAGS
122 Attempt to restore extended file flags. By default, file
123 flags are ignored.
124 ARCHIVE_EXTRACT_XATTR
125 Attempt to restore POSIX.1e extended attributes. By
126 default, they are ignored.
127 ARCHIVE_EXTRACT_SECURE_SYMLINKS
128 Refuse to extract any object whose final location would
129 be altered by a symlink on disk. This is intended to
130 help guard against a variety of mischief caused by ar‐
131 chives that (deliberately or otherwise) extract files
132 outside of the current directory. The default is not to
133 perform this check. If ARCHIVE_EXTRACT_UNLINK is speci‐
134 fied together with this option, the library will remove
135 any intermediate symlinks it finds and return an error
136 only if such symlink could not be removed.
137 ARCHIVE_EXTRACT_SECURE_NODOTDOT
138 Refuse to extract a path that contains a .. element any‐
139 where within it. The default is to not refuse such
140 paths. Note that paths ending in .. always cause an
141 error, regardless of this flag.
142 ARCHIVE_EXTRACT_SPARSE
143 Scan data for blocks of NUL bytes and try to recreate
144 them with holes. This results in sparse files, indepen‐
145 dent of whether the archive format supports or uses them.
146 archive_write_disk_set_group_lookup(),
148 archive_write_disk_set_user_lookup()
149 The struct archive_entry objects contain both names and ids that
150 can be used to identify users and groups. These names and ids
151 describe the ownership of the file itself and also appear in ACL
152 lists. By default, the library uses the ids and ignores the
153 names, but this can be overridden by registering user and group
154 lookup functions. To register, you must provide a lookup func‐
155 tion which accepts both a name and id and returns a suitable id.
156 You may also provide a void * pointer to a private data structure
157 and a cleanup function for that data. The cleanup function will
158 be invoked when the struct archive object is destroyed.
159 archive_write_disk_set_standard_lookup()
161 This convenience function installs a standard set of user and
162 group lookup functions. These functions use getpwnam(3) and
163 getgrnam(3) to convert names to ids, defaulting to the ids if the
164 names cannot be looked up. These functions also implement a sim‐
165 ple memory cache to reduce the number of calls to getpwnam(3) and
166 getgrnam(3).
167 archive_write_header()
169 Build and write a header using the data in the provided struct
170 archive_entry structure. See archive_entry(3) for information on
171 creating and populating struct archive_entry objects.
172 archive_write_data()
174 Write data corresponding to the header just written. Returns
175 number of bytes written or -1 on error.
176 archive_write_data_block()
178 Write data corresponding to the header just written. This is
179 like archive_write_data() except that it performs a seek on the
180 file being written to the specified offset before writing the
181 data. This is useful when restoring sparse files from archive
182 formats that support sparse files. Returns number of bytes writ‐
183 ten or -1 on error. (Note: This is currently not supported for
184 archive_write handles, only for archive_write_disk handles.)
185 archive_write_finish_entry()
187 Close out the entry just written. Ordinarily, clients never need
188 to call this, as it is called automatically by
189 archive_write_next_header() and archive_write_close() as needed.
190 However, some file attributes are written to disk only after the
191 file is closed, so this can be necessary if you need to work with
192 the file on disk right away.
193 archive_write_close()
195 Set any attributes that could not be set during the initial
196 restore. For example, directory timestamps are not restored ini‐
197 tially because restoring a subsequent file would alter that time‐
198 stamp. Similarly, non-writable directories are initially created
199 with write permissions (so that their contents can be restored).
200 The archive_write_disk_new library maintains a list of all such
201 deferred attributes and sets them when this function is invoked.
202 archive_write_finish()
204 This is a deprecated synonym for archive_write_free().
205 archive_write_free()
207 Invokes archive_write_close() if it was not invoked manually,
208 then releases all resources.
209 More information about the struct archive object and the overall design
210 of the library can be found in the libarchive(3) overview. Many of these
211 functions are also documented under archive_write(3).
212
214 Most functions return ARCHIVE_OK (zero) on success, or one of several
215 non-zero error codes for errors. Specific error codes include:
216 ARCHIVE_RETRY for operations that might succeed if retried, ARCHIVE_WARN
217 for unusual conditions that do not prevent further operations, and
218 ARCHIVE_FATAL for serious errors that make remaining operations impossi‐
219 ble.
220 archive_write_disk_new() returns a pointer to a newly-allocated struct
222 archive object.
223 archive_write_data() returns a count of the number of bytes actually
225 written, or -1 on error.
226
228 Detailed error codes and textual descriptions are available from the
229 archive_errno() and archive_error_string() functions.
230
232 archive_read(3), archive_write(3), tar(1), libarchive(3)
233
235 The libarchive library first appeared in FreeBSD 5.3. The
236 archive_write_disk interface was added to libarchive 2.0 and first
237 appeared in FreeBSD 6.3.
238
240 The libarchive library was written by Tim Kientzle <kientzle@acm.org>.
241
243 Directories are actually extracted in two distinct phases. Directories
244 are created during archive_write_header(), but final permissions are not
245 set until archive_write_close(). This separation is necessary to cor‐
246 rectly handle borderline cases such as a non-writable directory contain‐
247 ing files, but can cause unexpected results. In particular, directory
248 permissions are not fully restored until the archive is closed. If you
249 use chdir(2) to change the current directory between calls to
250 archive_read_extract() or before calling archive_read_close(), you may
251 confuse the permission-setting logic with the result that directory per‐
252 missions are restored incorrectly.
253 The library attempts to create objects with filenames longer than
255 PATH_MAX by creating prefixes of the full path and changing the current
256 directory. Currently, this logic is limited in scope; the fixup pass
257 does not work correctly for such objects and the symlink security check
258 option disables the support for very long pathnames.
259 Restoring the path aa/../bb does create each intermediate directory. In
261 particular, the directory aa is created as well as the final object bb.
262 In theory, this can be exploited to create an entire directory hierarchy
263 with a single request. Of course, this does not work if the
264 ARCHIVE_EXTRACT_NODOTDOT option is specified.
265 Implicit directories are always created obeying the current umask.
267 Explicit objects are created obeying the current umask unless
268 ARCHIVE_EXTRACT_PERM is specified, in which case they current umask is
269 ignored.
270 SGID and SUID bits are restored only if the correct user and group could
272 be set. If ARCHIVE_EXTRACT_OWNER is not specified, then no attempt is
273 made to set the ownership. In this case, SGID and SUID bits are restored
274 only if the user and group of the final object happen to match those
275 specified in the entry.
276 The “standard” user-id and group-id lookup functions are not the defaults
278 because getgrnam(3) and getpwnam(3) are sometimes too large for particu‐
279 lar applications. The current design allows the application author to
280 use a more compact implementation when appropriate.
281 There should be a corresponding archive_read_disk interface that walks a
283 directory hierarchy and returns archive entry objects.
284BSD February 2, 2012 BSD