~stewart/percona-xtrabackup/bug1213036

« back to all changes in this revision

Viewing changes to src/libarchive/libarchive/archive_read_disk.3

  • Committer: Alexey Kopytov
  • Date: 2012-02-10 20:05:56 UTC
  • mto: (391.1.5 staging)
  • mto: This revision was merged to the branch mainline in revision 390.
  • Revision ID: akopytov@gmail.com-20120210200556-6kx41z8wwrqfucro
Rebase of the parallel compression patch on new trunk + post-review
fixes.

Implementation of parallel compression and streaming for XtraBackup.

This revision implements the following changes:

* InnoDB files are now streamed by the xtrabackup binary rather than
innobackupex. As a result, integrity is now verified by xtrabackup and
thus tar4ibd is no longer needed, so it was removed.

* xtrabackup binary now accepts the new '--stream' option which has
exactly the same semantics as the '--stream' option in
innobackupex: it tells xtrabackup to stream all files to the standard
output in the specified format rather than storing them locally.

* The xtrabackup binary can now do parallel compression using the
quicklz library. Two new options were added to xtrabackup to support
this feature:

- '--compress' tells xtrabackup to compress all output data, including
the transaction log file and meta data files, using the specified
compression algorithm. The only currently supported algorithm is
'quicklz'. The resulting files have the qpress archive format,
i.e. every *.qp file produced by xtrabackup is essentially a one-file
qpress archive and can be extracted and uncompressed by the qpress
file archiver (http://www.quicklz.com/).

- '--compress-threads' specifies the number of worker threads used by
xtrabackup for parallel data compression. This option defaults to 1.

Parallel compression ('--compress-threads') can be used together with
parallel file copying ('--parallel'). For example, '--parallel=4
--compress --compress-threads=2' will create 4 IO threads that will
read the data and pipe it to 2 compression threads.

* To support simultaneous compression and streaming, a new custom
streaming format called 'xbstream' was introduced to XtraBackup in
addition to the 'tar' format. That was required to overcome some
limitations of traditional archive formats such as 'tar', 'cpio' and
others that do not allow streaming dynamically generated files, for
example dynamically compressed files.  Other advantages of xbstream over
traditional streaming/archive formats include ability to stream multiple
files concurrently (so it is possible to use streaming in the xbstream
format together with the --parallel option) and more compact data
storage.

* To allow streaming and extracting files to/from the xbstream format
produced by xtrabackup, a new utility aptly called 'xbstream' was
added to the XtraBackup distribution. This utility has a tar-like
interface:

- with the '-x' option it extracts files from the stream read from its
standard input to the current directory unless specified otherwise
with the '-C' option.

- with the '-c' option it streams files specified on the command line
to its standard output.

The utility also tries to minimize its impact on the OS page cache by
using the appropriate posix_fadvise() calls when available.

Show diffs side-by-side

added added

removed removed

Lines of Context:
 
1
.\" Copyright (c) 2003-2009 Tim Kientzle
 
2
.\" All rights reserved.
 
3
.\"
 
4
.\" Redistribution and use in source and binary forms, with or without
 
5
.\" modification, are permitted provided that the following conditions
 
6
.\" are met:
 
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.
 
12
.\"
 
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
 
23
.\" SUCH DAMAGE.
 
24
.\"
 
25
.\" $FreeBSD: head/lib/libarchive/archive_read_disk.3 190957 2009-04-12 05:04:02Z kientzle $
 
26
.\"
 
27
.Dd March 10, 2009
 
28
.Dt archive_read_disk 3
 
29
.Os
 
30
.Sh NAME
 
31
.Nm archive_read_disk_new ,
 
32
.Nm archive_read_disk_set_symlink_logical ,
 
33
.Nm archive_read_disk_set_symlink_physical ,
 
34
.Nm archive_read_disk_set_symlink_hybrid ,
 
35
.Nm archive_read_disk_entry_from_file ,
 
36
.Nm archive_read_disk_gname ,
 
37
.Nm archive_read_disk_uname ,
 
38
.Nm archive_read_disk_set_uname_lookup ,
 
39
.Nm archive_read_disk_set_gname_lookup ,
 
40
.Nm archive_read_disk_set_standard_lookup ,
 
41
.Nm archive_read_close ,
 
42
.Nm archive_read_finish
 
43
.Nd functions for reading objects from disk
 
44
.Sh SYNOPSIS
 
45
.In archive.h
 
46
.Ft struct archive *
 
47
.Fn archive_read_disk_new "void"
 
48
.Ft int
 
49
.Fn archive_read_disk_set_symlink_logical "struct archive *"
 
50
.Ft int
 
51
.Fn archive_read_disk_set_symlink_physical "struct archive *"
 
52
.Ft int
 
53
.Fn archive_read_disk_set_symlink_hybrid "struct archive *"
 
54
.Ft int
 
55
.Fn archive_read_disk_gname "struct archive *" "gid_t"
 
56
.Ft int
 
57
.Fn archive_read_disk_uname "struct archive *" "uid_t"
 
58
.Ft int
 
59
.Fo archive_read_disk_set_gname_lookup
 
60
.Fa "struct archive *"
 
61
.Fa "void *"
 
62
.Fa "const char *(*lookup)(void *, gid_t)"
 
63
.Fa "void (*cleanup)(void *)"
 
64
.Fc
 
65
.Ft int
 
66
.Fo archive_read_disk_set_uname_lookup
 
67
.Fa "struct archive *"
 
68
.Fa "void *"
 
69
.Fa "const char *(*lookup)(void *, uid_t)"
 
70
.Fa "void (*cleanup)(void *)"
 
71
.Fc
 
72
.Ft int
 
73
.Fn archive_read_disk_set_standard_lookup "struct archive *"
 
74
.Ft int
 
75
.Fo archive_read_disk_entry_from_file
 
76
.Fa "struct archive *"
 
77
.Fa "struct archive_entry *"
 
78
.Fa "int fd"
 
79
.Fa "const struct stat *"
 
80
.Fc
 
81
.Ft int
 
82
.Fn archive_read_close "struct archive *"
 
83
.Ft int
 
84
.Fn archive_read_finish "struct archive *"
 
85
.Sh DESCRIPTION
 
86
These functions provide an API for reading information about
 
87
objects on disk.
 
88
In particular, they provide an interface for populating
 
89
.Tn struct archive_entry
 
90
objects.
 
91
.Bl -tag -width indent
 
92
.It Fn archive_read_disk_new
 
93
Allocates and initializes a
 
94
.Tn struct archive
 
95
object suitable for reading object information from disk.
 
96
.It Xo
 
97
.Fn archive_read_disk_set_symlink_logical ,
 
98
.Fn archive_read_disk_set_symlink_physical ,
 
99
.Fn archive_read_disk_set_symlink_hybrid
 
100
.Xc
 
101
This sets the mode used for handling symbolic links.
 
102
The
 
103
.Dq logical
 
104
mode follows all symbolic links.
 
105
The
 
106
.Dq physical
 
107
mode does not follow any symbolic links.
 
108
The
 
109
.Dq hybrid
 
110
mode currently behaves identically to the
 
111
.Dq logical
 
112
mode.
 
113
.It Xo
 
114
.Fn archive_read_disk_gname ,
 
115
.Fn archive_read_disk_uname
 
116
.Xc
 
117
Returns a user or group name given a gid or uid value.
 
118
By default, these always return a NULL string.
 
119
.It Xo
 
120
.Fn archive_read_disk_set_gname_lookup ,
 
121
.Fn archive_read_disk_set_uname_lookup
 
122
.Xc
 
123
These allow you to override the functions used for
 
124
user and group name lookups.
 
125
You may also provide a
 
126
.Tn void *
 
127
pointer to a private data structure and a cleanup function for
 
128
that data.
 
129
The cleanup function will be invoked when the
 
130
.Tn struct archive
 
131
object is destroyed or when new lookup functions are registered.
 
132
.It Fn archive_read_disk_set_standard_lookup
 
133
This convenience function installs a standard set of user
 
134
and group name lookup functions.
 
135
These functions use
 
136
.Xr getpwid 3
 
137
and
 
138
.Xr getgrid 3
 
139
to convert ids to names, defaulting to NULL if the names cannot
 
140
be looked up.
 
141
These functions also implement a simple memory cache to reduce
 
142
the number of calls to
 
143
.Xr getpwid 3
 
144
and
 
145
.Xr getgrid 3 .
 
146
.It Fn archive_read_disk_entry_from_file
 
147
Populates a
 
148
.Tn struct archive_entry
 
149
object with information about a particular file.
 
150
The
 
151
.Tn archive_entry
 
152
object must have already been created with
 
153
.Xr archive_entry_new 3
 
154
and at least one of the source path or path fields must already be set.
 
155
(If both are set, the source path will be used.)
 
156
.Pp
 
157
Information is read from disk using the path name from the
 
158
.Tn struct archive_entry
 
159
object.
 
160
If a file descriptor is provided, some information will be obtained using
 
161
that file descriptor, on platforms that support the appropriate
 
162
system calls.
 
163
.Pp
 
164
If a pointer to a
 
165
.Tn struct stat
 
166
is provided, information from that structure will be used instead
 
167
of reading from the disk where appropriate.
 
168
This can provide performance benefits in scenarios where
 
169
.Tn struct stat
 
170
information has already been read from the disk as a side effect
 
171
of some other operation.
 
172
(For example, directory traversal libraries often provide this information.)
 
173
.Pp
 
174
Where necessary, user and group ids are converted to user and group names
 
175
using the currently registered lookup functions above.
 
176
This affects the file ownership fields and ACL values in the
 
177
.Tn struct archive_entry
 
178
object.
 
179
.It Fn archive_read_close
 
180
This currently does nothing.
 
181
.It Fn archive_write_finish
 
182
Invokes
 
183
.Fn archive_write_close
 
184
if it was not invoked manually, then releases all resources.
 
185
.El
 
186
More information about the
 
187
.Va struct archive
 
188
object and the overall design of the library can be found in the
 
189
.Xr libarchive 3
 
190
overview.
 
191
.Sh EXAMPLE
 
192
The following illustrates basic usage of the library by
 
193
showing how to use it to copy an item on disk into an archive.
 
194
.Bd -literal -offset indent
 
195
void
 
196
file_to_archive(struct archive *a, const char *name)
 
197
{
 
198
  char buff[8192];
 
199
  size_t bytes_read;
 
200
  struct archive *ard;
 
201
  struct archive_entry *entry;
 
202
  int fd;
 
203
 
 
204
  ard = archive_read_disk_new();
 
205
  archive_read_disk_set_standard_lookup(ard);
 
206
  entry = archive_entry_new();
 
207
  fd = open(name, O_RDONLY);
 
208
  if (fd < 0)
 
209
     return;
 
210
  archive_entry_copy_sourcepath(entry, name);
 
211
  archive_read_disk_entry_from_file(ard, entry, fd, NULL);
 
212
  archive_write_header(a, entry);
 
213
  while ((bytes_read = read(fd, buff, sizeof(buff))) > 0)
 
214
    archive_write_data(a, buff, bytes_read);
 
215
  archive_write_finish_entry(a);
 
216
  archive_read_finish(ard);
 
217
  archive_entry_free(entry);
 
218
}
 
219
.Ed
 
220
.Sh RETURN VALUES
 
221
Most functions return
 
222
.Cm ARCHIVE_OK
 
223
(zero) on success, or one of several negative
 
224
error codes for errors.
 
225
Specific error codes include:
 
226
.Cm ARCHIVE_RETRY
 
227
for operations that might succeed if retried,
 
228
.Cm ARCHIVE_WARN
 
229
for unusual conditions that do not prevent further operations, and
 
230
.Cm ARCHIVE_FATAL
 
231
for serious errors that make remaining operations impossible.
 
232
The
 
233
.Xr archive_errno 3
 
234
and
 
235
.Xr archive_error_string 3
 
236
functions can be used to retrieve an appropriate error code and a
 
237
textual error message.
 
238
(See
 
239
.Xr archive_util 3
 
240
for details.)
 
241
.Pp
 
242
.Fn archive_read_disk_new
 
243
returns a pointer to a newly-allocated
 
244
.Tn struct archive
 
245
object or NULL if the allocation failed for any reason.
 
246
.Pp
 
247
.Fn archive_read_disk_gname
 
248
and
 
249
.Fn archive_read_disk_uname
 
250
return
 
251
.Tn const char *
 
252
pointers to the textual name or NULL if the lookup failed for any reason.
 
253
The returned pointer points to internal storage that
 
254
may be reused on the next call to either of these functions;
 
255
callers should copy the string if they need to continue accessing it.
 
256
.Pp
 
257
.Sh SEE ALSO
 
258
.Xr archive_read 3 ,
 
259
.Xr archive_write 3 ,
 
260
.Xr archive_write_disk 3 ,
 
261
.Xr tar 1 ,
 
262
.Xr libarchive 3
 
263
.Sh HISTORY
 
264
The
 
265
.Nm libarchive
 
266
library first appeared in
 
267
.Fx 5.3 .
 
268
The
 
269
.Nm archive_read_disk
 
270
interface was added to
 
271
.Nm libarchive 2.6
 
272
and first appeared in
 
273
.Fx 8.0 .
 
274
.Sh AUTHORS
 
275
.An -nosplit
 
276
The
 
277
.Nm libarchive
 
278
library was written by
 
279
.An Tim Kientzle Aq kientzle@freebsd.org .
 
280
.Sh BUGS
 
281
The
 
282
.Dq standard
 
283
user name and group name lookup functions are not the defaults because
 
284
.Xr getgrid 3
 
285
and
 
286
.Xr getpwid 3
 
287
are sometimes too large for particular applications.
 
288
The current design allows the application author to use a more
 
289
compact implementation when appropriate.
 
290
.Pp
 
291
The full list of metadata read from disk by
 
292
.Fn archive_read_disk_entry_from_file
 
293
is necessarily system-dependent.
 
294
.Pp
 
295
The
 
296
.Fn archive_read_disk_entry_from_file
 
297
function reads as much information as it can from disk.
 
298
Some method should be provided to limit this so that clients who
 
299
do not need ACLs, for instance, can avoid the extra work needed
 
300
to look up such information.
 
301
.Pp
 
302
This API should provide a set of methods for walking a directory tree.
 
303
That would make it a direct parallel of the
 
304
.Xr archive_read 3
 
305
API.
 
306
When such methods are implemented, the
 
307
.Dq hybrid
 
308
symbolic link mode will make sense.