|
Packit Service |
1d0348 |
ARCHIVE_WRITE_OPEN(3) manual page
|
|
Packit Service |
1d0348 |
== NAME ==
|
|
Packit Service |
1d0348 |
'''archive_write_open''',
|
|
Packit Service |
1d0348 |
'''archive_write_open_fd''',
|
|
Packit Service |
1d0348 |
'''archive_write_open_FILE''',
|
|
Packit Service |
1d0348 |
'''archive_write_open_filename''',
|
|
Packit Service |
1d0348 |
'''archive_write_open_memory'''
|
|
Packit Service |
1d0348 |
- functions for creating 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_write_open'''(''struct archive *'', ''void *client_data'', ''archive_open_callback *'', ''archive_write_callback *'', ''archive_close_callback *'');
|
|
Packit Service |
1d0348 |
|
|
Packit Service |
1d0348 |
''int''
|
|
Packit Service |
1d0348 |
|
|
Packit Service |
1d0348 |
'''archive_write_open_fd'''(''struct archive *'', ''int fd'');
|
|
Packit Service |
1d0348 |
|
|
Packit Service |
1d0348 |
''int''
|
|
Packit Service |
1d0348 |
|
|
Packit Service |
1d0348 |
'''archive_write_open_FILE'''(''struct archive *'', ''FILE *file'');
|
|
Packit Service |
1d0348 |
|
|
Packit Service |
1d0348 |
''int''
|
|
Packit Service |
1d0348 |
|
|
Packit Service |
1d0348 |
'''archive_write_open_filename'''(''struct archive *'', ''const char *filename'');
|
|
Packit Service |
1d0348 |
|
|
Packit Service |
1d0348 |
''int''
|
|
Packit Service |
1d0348 |
|
|
Packit Service |
1d0348 |
'''archive_write_open_memory'''(''struct archive *'', ''void *buffer'', ''size_t bufferSize'', ''size_t *outUsed'');
|
|
Packit Service |
1d0348 |
== DESCRIPTION ==
|
|
Packit Service |
1d0348 |
|
|
Packit Service |
1d0348 |
'''archive_write_open'''()
|
|
Packit Service |
1d0348 |
Freeze the settings, open the archive, and prepare for writing entries.
|
|
Packit Service |
1d0348 |
This is the most generic form of this function, which accepts
|
|
Packit Service |
1d0348 |
pointers to three callback functions which will be invoked by
|
|
Packit Service |
1d0348 |
the compression layer to write the constructed archive.
|
|
Packit Service |
1d0348 |
This does not alter the default archive padding.
|
|
Packit Service |
1d0348 |
'''archive_write_open_fd'''()
|
|
Packit Service |
1d0348 |
A convenience form of
|
|
Packit Service |
1d0348 |
'''archive_write_open'''()
|
|
Packit Service |
1d0348 |
that accepts a file descriptor.
|
|
Packit Service |
1d0348 |
The
|
|
Packit Service |
1d0348 |
'''archive_write_open_fd'''()
|
|
Packit Service |
1d0348 |
function is safe for use with tape drives or other
|
|
Packit Service |
1d0348 |
block-oriented devices.
|
|
Packit Service |
1d0348 |
'''archive_write_open_FILE'''()
|
|
Packit Service |
1d0348 |
A convenience form of
|
|
Packit Service |
1d0348 |
'''archive_write_open'''()
|
|
Packit Service |
1d0348 |
that accepts a
|
|
Packit Service |
1d0348 |
''FILE *''
|
|
Packit Service |
1d0348 |
pointer.
|
|
Packit Service |
1d0348 |
Note that
|
|
Packit Service |
1d0348 |
'''archive_write_open_FILE'''()
|
|
Packit Service |
1d0348 |
is not safe for writing to tape drives or other devices
|
|
Packit Service |
1d0348 |
that require correct blocking.
|
|
Packit Service |
1d0348 |
'''archive_write_open_file'''()
|
|
Packit Service |
1d0348 |
A deprecated synonym for
|
|
Packit Service |
1d0348 |
'''archive_write_open_filename'''().
|
|
Packit Service |
1d0348 |
'''archive_write_open_filename'''()
|
|
Packit Service |
1d0348 |
A convenience form of
|
|
Packit Service |
1d0348 |
'''archive_write_open'''()
|
|
Packit Service |
1d0348 |
that accepts a filename.
|
|
Packit Service |
1d0348 |
A NULL argument indicates that the output should be written to standard output;
|
|
Packit Service |
1d0348 |
an argument of
|
|
Packit Service |
1d0348 |
"-"
|
|
Packit Service |
1d0348 |
will open a file with that name.
|
|
Packit Service |
1d0348 |
If you have not invoked
|
|
Packit Service |
1d0348 |
'''archive_write_set_bytes_in_last_block'''(),
|
|
Packit Service |
1d0348 |
then
|
|
Packit Service |
1d0348 |
'''archive_write_open_filename'''()
|
|
Packit Service |
1d0348 |
will adjust the last-block padding depending on the file:
|
|
Packit Service |
1d0348 |
it will enable padding when writing to standard output or
|
|
Packit Service |
1d0348 |
to a character or block device node, it will disable padding otherwise.
|
|
Packit Service |
1d0348 |
You can override this by manually invoking
|
|
Packit Service |
1d0348 |
'''archive_write_set_bytes_in_last_block'''()
|
|
Packit Service |
1d0348 |
before calling
|
|
Packit Service |
1d0348 |
'''archive_write_open'''().
|
|
Packit Service |
1d0348 |
The
|
|
Packit Service |
1d0348 |
'''archive_write_open_filename'''()
|
|
Packit Service |
1d0348 |
function is safe for use with tape drives or other
|
|
Packit Service |
1d0348 |
block-oriented devices.
|
|
Packit Service |
1d0348 |
'''archive_write_open_memory'''()
|
|
Packit Service |
1d0348 |
A convenience form of
|
|
Packit Service |
1d0348 |
'''archive_write_open'''()
|
|
Packit Service |
1d0348 |
that accepts a pointer to a block of memory that will receive
|
|
Packit Service |
1d0348 |
the archive.
|
|
Packit Service |
1d0348 |
The final
|
|
Packit Service |
1d0348 |
''size_t *''
|
|
Packit Service |
1d0348 |
argument points to a variable that will be updated
|
|
Packit Service |
1d0348 |
after each write to reflect how much of the buffer
|
|
Packit Service |
1d0348 |
is currently in use.
|
|
Packit Service |
1d0348 |
You should be careful to ensure that this variable
|
|
Packit Service |
1d0348 |
remains allocated until after the archive is
|
|
Packit Service |
1d0348 |
closed.
|
|
Packit Service |
1d0348 |
This function will disable padding unless you
|
|
Packit Service |
1d0348 |
have specifically set the block size.
|
|
Packit Service |
1d0348 |
|
|
Packit Service |
1d0348 |
More information about the
|
|
Packit Service |
1d0348 |
''struct'' archive
|
|
Packit Service |
1d0348 |
object and the overall design of the library can be found in the
|
|
Packit Service |
1d0348 |
[[ManPageibarchive3]]
|
|
Packit Service |
1d0348 |
overview.
|
|
Packit Service |
1d0348 |
|
|
Packit Service |
1d0348 |
Note that the convenience forms above vary in how
|
|
Packit Service |
1d0348 |
they block the output.
|
|
Packit Service |
1d0348 |
See
|
|
Packit Service |
1d0348 |
[[ManPagerchiveritelocksize3]]
|
|
Packit Service |
1d0348 |
if you need to control the block size used for writes
|
|
Packit Service |
1d0348 |
or the end-of-file padding behavior.
|
|
Packit Service |
1d0348 |
== CLIENT CALLBACKS ==
|
|
Packit Service |
1d0348 |
To use this library, you will need to define and register
|
|
Packit Service |
1d0348 |
callback functions that will be invoked to write data to the
|
|
Packit Service |
1d0348 |
resulting archive.
|
|
Packit Service |
1d0348 |
These functions are registered by calling
|
|
Packit Service |
1d0348 |
'''archive_write_open'''():
|
|
Packit Service |
1d0348 |
|
|
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 |
|
|
Packit Service |
1d0348 |
The open callback is invoked by
|
|
Packit Service |
1d0348 |
'''archive_write_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 |
|
|
Packit Service |
1d0348 |
''typedef la_ssize_t''
|
|
Packit Service |
1d0348 |
'''archive_write_callback'''(''struct archive *'', ''void *client_data'', ''const void *buffer'', ''size_t length'')
|
|
Packit Service |
1d0348 |
|
|
Packit Service |
1d0348 |
|
|
Packit Service |
1d0348 |
The write callback is invoked whenever the library
|
|
Packit Service |
1d0348 |
needs to write raw bytes to the archive.
|
|
Packit Service |
1d0348 |
For correct blocking, each call to the write callback function
|
|
Packit Service |
1d0348 |
should translate into a single
|
|
Packit Service |
1d0348 |
[[write(2)|http://www.freebsd.org/cgi/man.cgi?query=write&sektion=2]]
|
|
Packit Service |
1d0348 |
system call.
|
|
Packit Service |
1d0348 |
This is especially critical when writing archives to tape drives.
|
|
Packit Service |
1d0348 |
On success, the write callback should return the
|
|
Packit Service |
1d0348 |
number of bytes actually written.
|
|
Packit Service |
1d0348 |
On error, the callback should invoke
|
|
Packit Service |
1d0348 |
'''archive_set_error'''()
|
|
Packit Service |
1d0348 |
to register an error code and message and return -1.
|
|
Packit Service |
1d0348 |
|
|
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 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 |
|
|
Packit Service |
1d0348 |
Note that if the client-provided write callback function
|
|
Packit Service |
1d0348 |
returns a non-zero value, that error will be propagated back to the caller
|
|
Packit Service |
1d0348 |
through whatever API function resulted in that call, which
|
|
Packit Service |
1d0348 |
may include
|
|
Packit Service |
1d0348 |
'''archive_write_header'''(),
|
|
Packit Service |
1d0348 |
'''archive_write_data'''(),
|
|
Packit Service |
1d0348 |
'''archive_write_close'''(),
|
|
Packit Service |
1d0348 |
'''archive_write_finish'''(),
|
|
Packit Service |
1d0348 |
or
|
|
Packit Service |
1d0348 |
'''archive_write_free'''().
|
|
Packit Service |
1d0348 |
The client callback can call
|
|
Packit Service |
1d0348 |
'''archive_set_error'''()
|
|
Packit Service |
1d0348 |
to provide values that can then be retrieved by
|
|
Packit Service |
1d0348 |
'''archive_errno'''()
|
|
Packit Service |
1d0348 |
and
|
|
Packit Service |
1d0348 |
'''archive_error_string'''().
|
|
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 |
[[ManPagerchiverite3]],
|
|
Packit Service |
1d0348 |
[[ManPagerchiveritelocksize3]],
|
|
Packit Service |
1d0348 |
[[ManPagerchiveriteilter3]],
|
|
Packit Service |
1d0348 |
[[ManPagerchiveriteormat3]],
|
|
Packit Service |
1d0348 |
[[ManPagerchiveriteew3]],
|
|
Packit Service |
1d0348 |
[[ManPagerchiveriteetptions3]],
|
|
Packit Service |
1d0348 |
[[ManPageCpio5]],
|
|
Packit Service |
1d0348 |
[[ManPageMtree5]],
|
|
Packit Service |
1d0348 |
[[ManPageTar5]]
|