|
Packit Service |
1d0348 |
ARCHIVE_READ_OPEN(3) manual page
|
|
Packit Service |
1d0348 |
== NAME ==
|
|
Packit Service |
1d0348 |
'''archive_read_open''',
|
|
Packit Service |
1d0348 |
'''archive_read_open2''',
|
|
Packit Service |
1d0348 |
'''archive_read_open_fd''',
|
|
Packit Service |
1d0348 |
'''archive_read_open_FILE''',
|
|
Packit Service |
1d0348 |
'''archive_read_open_filename''',
|
|
Packit Service |
1d0348 |
'''archive_read_open_memory'''
|
|
Packit Service |
1d0348 |
- functions for reading streaming archives
|
|
Packit Service |
1d0348 |
== LIBRARY ==
|
|
Packit Service |
1d0348 |
Streaming Archive Library (libarchive, -larchive)
|
|
Packit Service |
1d0348 |
== SYNOPSIS ==
|
|
Packit Service |
1d0348 |
'''<nowiki>#include <archive.h></nowiki>'''
|
|
Packit Service |
1d0348 |
|
|
Packit Service |
1d0348 |
''int''
|
|
Packit Service |
1d0348 |
|
|
Packit Service |
1d0348 |
'''archive_read_open'''(''struct archive *'', ''void *client_data'', ''archive_open_callback *'', ''archive_read_callback *'', ''archive_close_callback *'');
|
|
Packit Service |
1d0348 |
|
|
Packit Service |
1d0348 |
''int''
|
|
Packit Service |
1d0348 |
|
|
Packit Service |
1d0348 |
'''archive_read_open2'''(''struct archive *'', ''void *client_data'', ''archive_open_callback *'', ''archive_read_callback *'', ''archive_skip_callback *'', ''archive_close_callback *'');
|
|
Packit Service |
1d0348 |
|
|
Packit Service |
1d0348 |
''int''
|
|
Packit Service |
1d0348 |
|
|
Packit Service |
1d0348 |
'''archive_read_open_FILE'''(''struct archive *'', ''FILE *file'');
|
|
Packit Service |
1d0348 |
|
|
Packit Service |
1d0348 |
''int''
|
|
Packit Service |
1d0348 |
|
|
Packit Service |
1d0348 |
'''archive_read_open_fd'''(''struct archive *'', ''int fd'', ''size_t block_size'');
|
|
Packit Service |
1d0348 |
|
|
Packit Service |
1d0348 |
''int''
|
|
Packit Service |
1d0348 |
|
|
Packit Service |
1d0348 |
'''archive_read_open_filename'''(''struct archive *'', ''const char *filename'', ''size_t block_size'');
|
|
Packit Service |
1d0348 |
|
|
Packit Service |
1d0348 |
''int''
|
|
Packit Service |
1d0348 |
|
|
Packit Service |
1d0348 |
'''archive_read_open_memory'''(''struct archive *'', ''const void *buff'', ''size_t size'');
|
|
Packit Service |
1d0348 |
== DESCRIPTION ==
|
|
Packit Service |
1d0348 |
|
|
Packit Service |
1d0348 |
'''archive_read_open'''()
|
|
Packit Service |
1d0348 |
The same as
|
|
Packit Service |
1d0348 |
'''archive_read_open2'''(),
|
|
Packit Service |
1d0348 |
except that the skip callback is assumed to be
|
|
Packit Service |
1d0348 |
NULL.
|
|
Packit Service |
1d0348 |
'''archive_read_open2'''()
|
|
Packit Service |
1d0348 |
Freeze the settings, open the archive, and prepare for reading entries.
|
|
Packit Service |
1d0348 |
This is the most generic version of this call, which accepts
|
|
Packit Service |
1d0348 |
four callback functions.
|
|
Packit Service |
1d0348 |
Most clients will want to use
|
|
Packit Service |
1d0348 |
'''archive_read_open_filename'''(),
|
|
Packit Service |
1d0348 |
'''archive_read_open_FILE'''(),
|
|
Packit Service |
1d0348 |
'''archive_read_open_fd'''(),
|
|
Packit Service |
1d0348 |
or
|
|
Packit Service |
1d0348 |
'''archive_read_open_memory'''()
|
|
Packit Service |
1d0348 |
instead.
|
|
Packit Service |
1d0348 |
The library invokes the client-provided functions to obtain
|
|
Packit Service |
1d0348 |
raw bytes from the archive.
|
|
Packit Service |
1d0348 |
'''archive_read_open_FILE'''()
|
|
Packit Service |
1d0348 |
Like
|
|
Packit Service |
1d0348 |
'''archive_read_open'''(),
|
|
Packit Service |
1d0348 |
except that it accepts a
|
|
Packit Service |
1d0348 |
''FILE *''
|
|
Packit Service |
1d0348 |
pointer.
|
|
Packit Service |
1d0348 |
This function should not be used with tape drives or other devices
|
|
Packit Service |
1d0348 |
that require strict I/O blocking.
|
|
Packit Service |
1d0348 |
'''archive_read_open_fd'''()
|
|
Packit Service |
1d0348 |
Like
|
|
Packit Service |
1d0348 |
'''archive_read_open'''(),
|
|
Packit Service |
1d0348 |
except that it accepts a file descriptor and block size rather than
|
|
Packit Service |
1d0348 |
a set of function pointers.
|
|
Packit Service |
1d0348 |
Note that the file descriptor will not be automatically closed at
|
|
Packit Service |
1d0348 |
end-of-archive.
|
|
Packit Service |
1d0348 |
This function is safe for use with tape drives or other blocked devices.
|
|
Packit Service |
1d0348 |
'''archive_read_open_file'''()
|
|
Packit Service |
1d0348 |
This is a deprecated synonym for
|
|
Packit Service |
1d0348 |
'''archive_read_open_filename'''().
|
|
Packit Service |
1d0348 |
'''archive_read_open_filename'''()
|
|
Packit Service |
1d0348 |
Like
|
|
Packit Service |
1d0348 |
'''archive_read_open'''(),
|
|
Packit Service |
1d0348 |
except that it accepts a simple filename and a block size.
|
|
Packit Service |
1d0348 |
A NULL filename represents standard input.
|
|
Packit Service |
1d0348 |
This function is safe for use with tape drives or other blocked devices.
|
|
Packit Service |
1d0348 |
'''archive_read_open_memory'''()
|
|
Packit Service |
1d0348 |
Like
|
|
Packit Service |
1d0348 |
'''archive_read_open'''(),
|
|
Packit Service |
1d0348 |
except that it accepts a pointer and size of a block of
|
|
Packit Service |
1d0348 |
memory containing the archive data.
|
|
Packit Service |
1d0348 |
|
|
Packit Service |
1d0348 |
|
|
Packit Service |
1d0348 |
A complete description of the
|
|
Packit Service |
1d0348 |
'''struct archive'''
|
|
Packit Service |
1d0348 |
and
|
|
Packit Service |
1d0348 |
'''struct archive_entry'''
|
|
Packit Service |
1d0348 |
objects can be found in the overview manual page for
|
|
Packit Service |
1d0348 |
[[ManPageibarchive3]].
|
|
Packit Service |
1d0348 |
== CLIENT CALLBACKS ==
|
|
Packit Service |
1d0348 |
The callback functions must match the following prototypes:
|
|
Packit Service |
1d0348 |
|
|
Packit Service |
1d0348 |
|
|
Packit Service |
1d0348 |
''typedef la_ssize_t''
|
|
Packit Service |
1d0348 |
'''archive_read_callback'''(''struct archive *'', ''void *client_data'', ''const void **buffer'')
|
|
Packit Service |
1d0348 |
|
|
Packit Service |
1d0348 |
''typedef la_int64_t''
|
|
Packit Service |
1d0348 |
'''archive_skip_callback'''(''struct archive *'', ''void *client_data'', ''off_t request'')
|
|
Packit Service |
1d0348 |
|
|
Packit Service |
1d0348 |
''typedef int''
|
|
Packit Service |
1d0348 |
'''archive_open_callback'''(''struct archive *'', ''void *client_data'')
|
|
Packit Service |
1d0348 |
|
|
Packit Service |
1d0348 |
''typedef int''
|
|
Packit Service |
1d0348 |
'''archive_close_callback'''(''struct archive *'', ''void *client_data'')
|
|
Packit Service |
1d0348 |
|
|
Packit Service |
1d0348 |
|
|
Packit Service |
1d0348 |
The open callback is invoked by
|
|
Packit Service |
1d0348 |
'''archive_open'''().
|
|
Packit Service |
1d0348 |
It should return
|
|
Packit Service |
1d0348 |
'''ARCHIVE_OK'''
|
|
Packit Service |
1d0348 |
if the underlying file or data source is successfully
|
|
Packit Service |
1d0348 |
opened.
|
|
Packit Service |
1d0348 |
If the open fails, it should call
|
|
Packit Service |
1d0348 |
'''archive_set_error'''()
|
|
Packit Service |
1d0348 |
to register an error code and message and return
|
|
Packit Service |
1d0348 |
'''ARCHIVE_FATAL'''.
|
|
Packit Service |
1d0348 |
|
|
Packit Service |
1d0348 |
The read callback is invoked whenever the library
|
|
Packit Service |
1d0348 |
requires raw bytes from the archive.
|
|
Packit Service |
1d0348 |
The read callback should read data into a buffer,
|
|
Packit Service |
1d0348 |
set the
|
|
Packit Service |
1d0348 |
```text
|
|
Packit Service |
1d0348 |
const void **buffer
|
|
Packit Service |
1d0348 |
```
|
|
Packit Service |
1d0348 |
argument to point to the available data, and
|
|
Packit Service |
1d0348 |
return a count of the number of bytes available.
|
|
Packit Service |
1d0348 |
The library will invoke the read callback again
|
|
Packit Service |
1d0348 |
only after it has consumed this data.
|
|
Packit Service |
1d0348 |
The library imposes no constraints on the size
|
|
Packit Service |
1d0348 |
of the data blocks returned.
|
|
Packit Service |
1d0348 |
On end-of-file, the read callback should
|
|
Packit Service |
1d0348 |
return zero.
|
|
Packit Service |
1d0348 |
On error, the read callback should invoke
|
|
Packit Service |
1d0348 |
'''archive_set_error'''()
|
|
Packit Service |
1d0348 |
to register an error code and message and
|
|
Packit Service |
1d0348 |
return -1.
|
|
Packit Service |
1d0348 |
|
|
Packit Service |
1d0348 |
The skip callback is invoked when the
|
|
Packit Service |
1d0348 |
library wants to ignore a block of data.
|
|
Packit Service |
1d0348 |
The return value is the number of bytes actually
|
|
Packit Service |
1d0348 |
skipped, which may differ from the request.
|
|
Packit Service |
1d0348 |
If the callback cannot skip data, it should return
|
|
Packit Service |
1d0348 |
zero.
|
|
Packit Service |
1d0348 |
If the skip callback is not provided (the
|
|
Packit Service |
1d0348 |
function pointer is
|
|
Packit Service |
1d0348 |
NULL ),
|
|
Packit Service |
1d0348 |
the library will invoke the read function
|
|
Packit Service |
1d0348 |
instead and simply discard the result.
|
|
Packit Service |
1d0348 |
A skip callback can provide significant
|
|
Packit Service |
1d0348 |
performance gains when reading uncompressed
|
|
Packit Service |
1d0348 |
archives from slow disk drives or other media
|
|
Packit Service |
1d0348 |
that can skip quickly.
|
|
Packit Service |
1d0348 |
|
|
Packit Service |
1d0348 |
The close callback is invoked by archive_close when
|
|
Packit Service |
1d0348 |
the archive processing is complete.
|
|
Packit Service |
1d0348 |
The callback should return
|
|
Packit Service |
1d0348 |
'''ARCHIVE_OK'''
|
|
Packit Service |
1d0348 |
on success.
|
|
Packit Service |
1d0348 |
On failure, the callback should invoke
|
|
Packit Service |
1d0348 |
'''archive_set_error'''()
|
|
Packit Service |
1d0348 |
to register an error code and message and
|
|
Packit Service |
1d0348 |
return
|
|
Packit Service |
1d0348 |
'''ARCHIVE_FATAL.'''
|
|
Packit Service |
1d0348 |
== RETURN VALUES ==
|
|
Packit Service |
1d0348 |
These functions return
|
|
Packit Service |
1d0348 |
'''ARCHIVE_OK'''
|
|
Packit Service |
1d0348 |
on success, or
|
|
Packit Service |
1d0348 |
'''ARCHIVE_FATAL'''.
|
|
Packit Service |
1d0348 |
== ERRORS ==
|
|
Packit Service |
1d0348 |
Detailed error codes and textual descriptions are available from the
|
|
Packit Service |
1d0348 |
'''archive_errno'''()
|
|
Packit Service |
1d0348 |
and
|
|
Packit Service |
1d0348 |
'''archive_error_string'''()
|
|
Packit Service |
1d0348 |
functions.
|
|
Packit Service |
1d0348 |
== SEE ALSO ==
|
|
Packit Service |
1d0348 |
[[ManPageBsdtar1]],
|
|
Packit Service |
1d0348 |
[[ManPageibarchive3]],
|
|
Packit Service |
1d0348 |
[[ManPagerchiveead3]],
|
|
Packit Service |
1d0348 |
[[ManPagerchiveeadata3]],
|
|
Packit Service |
1d0348 |
[[ManPagerchiveeadilter3]],
|
|
Packit Service |
1d0348 |
[[ManPagerchiveeadormat3]],
|
|
Packit Service |
1d0348 |
[[ManPagerchiveeadetptions3]],
|
|
Packit Service |
1d0348 |
[[ManPagerchivetil3]],
|
|
Packit Service |
1d0348 |
[[ManPageTar5]]
|