mirror of
https://github.com/cmclark00/retro-imager.git
synced 2025-05-19 08:25:21 +01:00
Bump bundled libarchive version to 3.5.2
- Update bunlded libarchive version used on Windows/Mac - Enable requested zstd support while we are at it. Closes #211
This commit is contained in:
Floris Bos
parent
03e083b4f3
commit
67618a2eac
1869 changed files with 166685 additions and 9489 deletions
271
dependencies/libarchive-3.5.2/libarchive/archive_write_open.3
vendored
Normal file
271
dependencies/libarchive-3.5.2/libarchive/archive_write_open.3
vendored
Normal file
|
|
@ -0,0 +1,271 @@
|
|||
.\" Copyright (c) 2003-2011 Tim Kientzle
|
||||
.\" All rights reserved.
|
||||
.\"
|
||||
.\" Redistribution and use in source and binary forms, with or without
|
||||
.\" modification, are permitted provided that the following conditions
|
||||
.\" are met:
|
||||
.\" 1. Redistributions of source code must retain the above copyright
|
||||
.\" notice, this list of conditions and the following disclaimer.
|
||||
.\" 2. Redistributions in binary form must reproduce the above copyright
|
||||
.\" notice, this list of conditions and the following disclaimer in the
|
||||
.\" documentation and/or other materials provided with the distribution.
|
||||
.\"
|
||||
.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
|
||||
.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
|
||||
.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
|
||||
.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
|
||||
.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
|
||||
.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
|
||||
.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
|
||||
.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
|
||||
.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
|
||||
.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
|
||||
.\" SUCH DAMAGE.
|
||||
.\"
|
||||
.\" $FreeBSD$
|
||||
.\"
|
||||
.Dd November 12, 2020
|
||||
.Dt ARCHIVE_WRITE_OPEN 3
|
||||
.Os
|
||||
.Sh NAME
|
||||
.Nm archive_write_open ,
|
||||
.Nm archive_write_open2 ,
|
||||
.Nm archive_write_open_fd ,
|
||||
.Nm archive_write_open_FILE ,
|
||||
.Nm archive_write_open_filename ,
|
||||
.Nm archive_write_open_memory
|
||||
.Nd functions for creating archives
|
||||
.Sh LIBRARY
|
||||
Streaming Archive Library (libarchive, -larchive)
|
||||
.Sh SYNOPSIS
|
||||
.In archive.h
|
||||
.Ft int
|
||||
.Fo archive_write_open
|
||||
.Fa "struct archive *"
|
||||
.Fa "void *client_data"
|
||||
.Fa "archive_open_callback *"
|
||||
.Fa "archive_write_callback *"
|
||||
.Fa "archive_close_callback *"
|
||||
.Fc
|
||||
.Ft int
|
||||
.Fo archive_write_open2
|
||||
.Fa "struct archive *"
|
||||
.Fa "void *client_data"
|
||||
.Fa "archive_open_callback *"
|
||||
.Fa "archive_write_callback *"
|
||||
.Fa "archive_close_callback *"
|
||||
.Fa "archive_free_callback *"
|
||||
.Fc
|
||||
.Ft int
|
||||
.Fn archive_write_open_fd "struct archive *" "int fd"
|
||||
.Ft int
|
||||
.Fn archive_write_open_FILE "struct archive *" "FILE *file"
|
||||
.Ft int
|
||||
.Fn archive_write_open_filename "struct archive *" "const char *filename"
|
||||
.Ft int
|
||||
.Fo archive_write_open_memory
|
||||
.Fa "struct archive *"
|
||||
.Fa "void *buffer"
|
||||
.Fa "size_t bufferSize"
|
||||
.Fa "size_t *outUsed"
|
||||
.Fc
|
||||
.Sh DESCRIPTION
|
||||
.Bl -tag -width indent
|
||||
.It Fn archive_write_open
|
||||
Freeze the settings, open the archive, and prepare for writing entries.
|
||||
This is the most generic form of this function, which accepts
|
||||
pointers to three callback functions which will be invoked by
|
||||
the compression layer to write the constructed archive.
|
||||
This does not alter the default archive padding.
|
||||
.It Fn archive_write_open2
|
||||
Same as
|
||||
.Fn archive_write_open
|
||||
with an additional fourth free callback. This function should be preferred to
|
||||
.Fn archive_write_open .
|
||||
.It Fn archive_write_open_fd
|
||||
A convenience form of
|
||||
.Fn archive_write_open
|
||||
that accepts a file descriptor.
|
||||
The
|
||||
.Fn archive_write_open_fd
|
||||
function is safe for use with tape drives or other
|
||||
block-oriented devices.
|
||||
.It Fn archive_write_open_FILE
|
||||
A convenience form of
|
||||
.Fn archive_write_open
|
||||
that accepts a
|
||||
.Ft "FILE *"
|
||||
pointer.
|
||||
Note that
|
||||
.Fn archive_write_open_FILE
|
||||
is not safe for writing to tape drives or other devices
|
||||
that require correct blocking.
|
||||
.It Fn archive_write_open_file
|
||||
A deprecated synonym for
|
||||
.Fn archive_write_open_filename .
|
||||
.It Fn archive_write_open_filename
|
||||
A convenience form of
|
||||
.Fn archive_write_open
|
||||
that accepts a filename.
|
||||
A NULL argument indicates that the output should be written to standard output;
|
||||
an argument of
|
||||
.Dq -
|
||||
will open a file with that name.
|
||||
If you have not invoked
|
||||
.Fn archive_write_set_bytes_in_last_block ,
|
||||
then
|
||||
.Fn archive_write_open_filename
|
||||
will adjust the last-block padding depending on the file:
|
||||
it will enable padding when writing to standard output or
|
||||
to a character or block device node, it will disable padding otherwise.
|
||||
You can override this by manually invoking
|
||||
.Fn archive_write_set_bytes_in_last_block
|
||||
before calling
|
||||
.Fn archive_write_open2 .
|
||||
The
|
||||
.Fn archive_write_open_filename
|
||||
function is safe for use with tape drives or other
|
||||
block-oriented devices.
|
||||
.It Fn archive_write_open_memory
|
||||
A convenience form of
|
||||
.Fn archive_write_open2
|
||||
that accepts a pointer to a block of memory that will receive
|
||||
the archive.
|
||||
The final
|
||||
.Ft "size_t *"
|
||||
argument points to a variable that will be updated
|
||||
after each write to reflect how much of the buffer
|
||||
is currently in use.
|
||||
You should be careful to ensure that this variable
|
||||
remains allocated until after the archive is
|
||||
closed.
|
||||
This function will disable padding unless you
|
||||
have specifically set the block size.
|
||||
.El
|
||||
More information about the
|
||||
.Va struct archive
|
||||
object and the overall design of the library can be found in the
|
||||
.Xr libarchive 3
|
||||
overview.
|
||||
.Pp
|
||||
Note that the convenience forms above vary in how
|
||||
they block the output.
|
||||
See
|
||||
.Xr archive_write_blocksize 3
|
||||
if you need to control the block size used for writes
|
||||
or the end-of-file padding behavior.
|
||||
.\"
|
||||
.Sh CLIENT CALLBACKS
|
||||
To use this library, you will need to define and register
|
||||
callback functions that will be invoked to write data to the
|
||||
resulting archive.
|
||||
These functions are registered by calling
|
||||
.Fn archive_write_open2 :
|
||||
.Bl -item -offset indent
|
||||
.It
|
||||
.Ft typedef int
|
||||
.Fn archive_open_callback "struct archive *" "void *client_data"
|
||||
.El
|
||||
.Pp
|
||||
The open callback is invoked by
|
||||
.Fn archive_write_open .
|
||||
It should return
|
||||
.Cm ARCHIVE_OK
|
||||
if the underlying file or data source is successfully
|
||||
opened.
|
||||
If the open fails, it should call
|
||||
.Fn archive_set_error
|
||||
to register an error code and message and return
|
||||
.Cm ARCHIVE_FATAL .
|
||||
Please note that if open fails, close is not called and resources must be
|
||||
freed inside the open callback or with the free callback.
|
||||
.Bl -item -offset indent
|
||||
.It
|
||||
.Ft typedef la_ssize_t
|
||||
.Fo archive_write_callback
|
||||
.Fa "struct archive *"
|
||||
.Fa "void *client_data"
|
||||
.Fa "const void *buffer"
|
||||
.Fa "size_t length"
|
||||
.Fc
|
||||
.El
|
||||
.Pp
|
||||
The write callback is invoked whenever the library
|
||||
needs to write raw bytes to the archive.
|
||||
For correct blocking, each call to the write callback function
|
||||
should translate into a single
|
||||
.Xr write 2
|
||||
system call.
|
||||
This is especially critical when writing archives to tape drives.
|
||||
On success, the write callback should return the
|
||||
number of bytes actually written.
|
||||
On error, the callback should invoke
|
||||
.Fn archive_set_error
|
||||
to register an error code and message and return -1.
|
||||
.Bl -item -offset indent
|
||||
.It
|
||||
.Ft typedef int
|
||||
.Fn archive_close_callback "struct archive *" "void *client_data"
|
||||
.El
|
||||
.Pp
|
||||
The close callback is invoked by archive_close when
|
||||
the archive processing is complete. If the open callback fails, the close
|
||||
callback is not invoked.
|
||||
The callback should return
|
||||
.Cm ARCHIVE_OK
|
||||
on success.
|
||||
On failure, the callback should invoke
|
||||
.Fn archive_set_error
|
||||
to register an error code and message and
|
||||
return
|
||||
.Bl -item -offset indent
|
||||
.It
|
||||
.Ft typedef int
|
||||
.Fn archive_free_callback "struct archive *" "void *client_data"
|
||||
.El
|
||||
.Pp
|
||||
The free callback is always invoked on archive_free.
|
||||
The return code of this callback is not processed.
|
||||
.Pp
|
||||
Note that if the client-provided write callback function
|
||||
returns a non-zero value, that error will be propagated back to the caller
|
||||
through whatever API function resulted in that call, which
|
||||
may include
|
||||
.Fn archive_write_header ,
|
||||
.Fn archive_write_data ,
|
||||
.Fn archive_write_close ,
|
||||
.Fn archive_write_finish ,
|
||||
or
|
||||
.Fn archive_write_free .
|
||||
The client callback can call
|
||||
.Fn archive_set_error
|
||||
to provide values that can then be retrieved by
|
||||
.Fn archive_errno
|
||||
and
|
||||
.Fn archive_error_string .
|
||||
.\" .Sh EXAMPLE
|
||||
.Sh RETURN VALUES
|
||||
These functions return
|
||||
.Cm ARCHIVE_OK
|
||||
on success, or
|
||||
.Cm ARCHIVE_FATAL .
|
||||
.\"
|
||||
.Sh ERRORS
|
||||
Detailed error codes and textual descriptions are available from the
|
||||
.Fn archive_errno
|
||||
and
|
||||
.Fn archive_error_string
|
||||
functions.
|
||||
.\"
|
||||
.Sh SEE ALSO
|
||||
.Xr tar 1 ,
|
||||
.Xr archive_write 3 ,
|
||||
.Xr archive_write_blocksize 3 ,
|
||||
.Xr archive_write_filter 3 ,
|
||||
.Xr archive_write_format 3 ,
|
||||
.Xr archive_write_new 3 ,
|
||||
.Xr archive_write_set_options 3 ,
|
||||
.Xr libarchive 3 ,
|
||||
.Xr cpio 5 ,
|
||||
.Xr mtree 5 ,
|
||||
.Xr tar 5
|
||||
Loading…
Add table
Add a link
Reference in a new issue