man/zip_source_function.man

.\" Automatically generated from an mdoc input file.  Do not edit.
.\" zip_source_function.mdoc -- create data source from function
.\" Copyright (C) 2004-2021 Dieter Baron and Thomas Klausner
.\"
.\" This file is part of libzip, a library to manipulate ZIP archives.
.\" The authors can be contacted at <libzip@nih.at>
.\"
.\" 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.
.\" 3. The names of the authors may not be used to endorse or promote
.\"    products derived from this software without specific prior
.\"    written permission.
.\"
.\" THIS SOFTWARE IS PROVIDED BY THE AUTHORS ``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 AUTHORS 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.
.\"
.TH "ZIP_SOURCE_FUNCTION" "3" "April 17, 2020" "NiH" "Library Functions Manual"
.nh
.if n .ad l
.SH "NAME"
\fBzip_source_function\fR,
\fBzip_source_function_create\fR
\- create data source from function
.SH "LIBRARY"
libzip (-lzip)
.SH "SYNOPSIS"
\fB#include <zip.h>\fR
.sp
\fIzip_source_t *\fR
.br
.PD 0
.HP 4n
\fBzip_source_function\fR(\fIzip_t\ *archive\fR, \fIzip_source_callback\ fn\fR, \fIvoid\ *userdata\fR);
.PD
.PP
\fIzip_source_t *\fR
.br
.PD 0
.HP 4n
\fBzip_source_function_create\fR(\fIzip_source_callback\ fn\fR, \fIvoid\ *userdata\fR, \fIzip_error_t\ *error\fR);
.PD
.SH "DESCRIPTION"
The functions
\fBzip_source_function\fR()
and
\fBzip_source_function_create\fR()
creates a zip source from the user-provided function
\fIfn\fR,
which must be of the following type:
.PP
\fItypedef zip_int64_t\fR
\fB\fR(*\fPzip_source_callback\fR)\fP\fR(\fIvoid\ *userdata\fR, \fIvoid\ *data\fR, \fIzip_uint64_t\ len\fR, \fIzip_source_cmd_t\ cmd\fR)
.PP
\fIarchive\fR
or
\fIerror\fR
are used for reporting errors and can be
\fRNULL\fR.
.PP
When called by the library, the first argument is the
\fIuserdata\fR
argument supplied to the function.
The next two arguments are a buffer
\fIdata\fR
of size
\fIlen\fR
when data is passed in or expected to be returned, or else
\fRNULL\fR
and 0.
The last argument,
\fIcmd\fR,
specifies which action the function should perform.
.PP
Depending on the uses, there are three useful sets of commands to be supported by a
\fBzip_source_callback\fR():
.TP 24n
read source
Providing streamed data (for file data added to archives).
Must support
\fRZIP_SOURCE_OPEN\fR,
\fRZIP_SOURCE_READ\fR,
\fRZIP_SOURCE_CLOSE\fR,
\fRZIP_SOURCE_STAT\fR,
and
\fRZIP_SOURCE_ERROR\fR.
.TP 24n
seekable read source
Same as previous, but from a source allowing reading from arbitrary
offsets (also for read-only zip archive).
Must additionally support
\fRZIP_SOURCE_SEEK\fR,
\fRZIP_SOURCE_TELL\fR,
and
\fRZIP_SOURCE_SUPPORTS\fR.
.TP 24n
read/write source
Same as previous, but additionally allowing writing (also for writable
zip archives).
Must additionally support
\fRZIP_SOURCE_BEGIN_WRITE\fR,
\fRZIP_SOURCE_COMMIT_WRITE\fR,
\fRZIP_SOURCE_ROLLBACK_WRITE\fR,
\fRZIP_SOURCE_SEEK_WRITE\fR,
\fRZIP_SOURCE_TELL_WRITE\fR,
and
\fRZIP_SOURCE_REMOVE\fR.
.SS "\fRZIP_SOURCE_ACCEPT_EMPTY\fR"
Return 1 if an empty source should be accepted as a valid zip archive.
This is the default if this command is not supported by a source.
File system backed sources should return 0.
.SS "\fRZIP_SOURCE_BEGIN_WRITE\fR"
Prepare the source for writing.
Use this to create any temporary file(s).
.SS "\fRZIP_SOURCE_BEGIN_WRITE_CLONING\fR"
Prepare the source for writing, keeping the first
\fIlen\fR
bytes of the original file.
Only implement this command if it is more efficient than copying the
data, and if it does not destructively overwrite the original file
(you still have to be able to execute
\fRZIP_SOURCE_ROLLBACK_WRITE\fR).
.PP
The next write should happen at byte
\fIoffset\fR.
.SS "\fRZIP_SOURCE_CLOSE\fR"
Reading is done.
.SS "\fRZIP_SOURCE_COMMIT_WRITE\fR"
Finish writing to the source.
Replace the original data with the newly written data.
Clean up temporary files or internal buffers.
Subsequently opening and reading from the source should return the
newly written data.
.SS "\fRZIP_SOURCE_ERROR\fR"
Get error information.
\fIdata\fR
points to an array of two ints, which should be filled with the libzip
error code and the corresponding system error code for the error that
occurred.
See
zip_errors(3)
for details on the error codes.
If the source stores error information in a zip_error_t, use
zip_error_to_data(3)
and return its return value.
Otherwise, return 2 * sizeof(int).
.SS "\fRZIP_SOURCE_FREE\fR"
Clean up and free all resources, including
\fIuserdata\fR.
The callback function will not be called again.
.SS "\fRZIP_SOURCE_GET_FILE_ATTRIBUTES\fR"
Provide information about various data.
Then the data should be put in the appropriate entry in the passed
\fIzip_file_attributes_t\fR
argument, and the appropriate
\fRZIP_FILE_ATTRIBUTES_*\fR
value must be or'ed into the
\fIvalid\fR
member to denote that the corresponding data has been provided.
A
\fIzip_file_attributes_t\fR
structure can be initialized using
zip_file_attributes_init(3).
.TP 12n
ASCII mode
If a file is a plaintext file in ASCII.
Can be used by extraction tools to automatically convert line endings
(part of the interal file attributes).
Member
\fIascii\fR,
flag
\fRZIP_FILE_ATTRIBUTES_ASCII\fR.
.TP 12n
General Purpose Bit Flags (limited to Compression Flags)
The general purpose bit flag in the zip in the local and central
directory headers contain information about the compression method.
Member
\fIgeneral_purpose_bit_flags\fR
and
\fIgeneral_purpose_bit_mask\fR
to denote which members have been set;
flag
\fRZIP_FILE_ATTRIBUTES_GENERAL_PURPOSE_BIT_FLAGS\fR.
.TP 12n
External File Attributes
The external file attributes (usually operating system-specific).
Member
\fIexternal_file_attributes\fR,
flag
\fRZIP_FILE_ATTRIBUTES_EXTERNAL_FILE_ATTRIBUTES\fR.
.TP 12n
Version Needed
A minimum version needed required to unpack this entry (in the usual
"major * 10 + minor" format).
Member
\fIversion_needed\fR,
flag
\fRZIP_FILE_ATTRIBUTES_VERSION_NEEDED\fR.
.TP 12n
Operating System
One of the operating systems as defined by the
\fRZIP_OPSYS_*\fR
variables (see
\fIzip.h\fR).
This value affects the interpretation of the external file attributes.
Member
\fIhost_system\fR,
flag
\fRZIP_FILE_ATTRIBUTES_HOST_SYSTEM\fR.
.SS "\fRZIP_SOURCE_OPEN\fR"
Prepare for reading.
.SS "\fRZIP_SOURCE_READ\fR"
Read data into the buffer
\fIdata\fR
of size
\fIlen\fR.
Return the number of bytes placed into
\fIdata\fR
on success, and zero for end-of-file.
.SS "\fRZIP_SOURCE_REMOVE\fR"
Remove the underlying file.
This is called if a zip archive is empty when closed.
.SS "\fRZIP_SOURCE_ROLLBACK_WRITE\fR"
Abort writing to the source.
Discard written data.
Clean up temporary files or internal buffers.
Subsequently opening and reading from the source should return the
original data.
.SS "\fRZIP_SOURCE_SEEK\fR"
Specify position to read next byte from, like
fseek(3).
Use
ZIP_SOURCE_GET_ARGS(3)
to decode the arguments into the following struct:
.nf
.sp
.RS 0n
struct zip_source_args_seek {
    zip_int64_t offset;
    int whence;
};
.RE
.fi
.PP
If the size of the source's data is known, use
zip_source_seek_compute_offset(3)
to validate the arguments and compute the new offset.
.SS "\fRZIP_SOURCE_SEEK_WRITE\fR"
Specify position to write next byte to, like
fseek(3).
See
\fRZIP_SOURCE_SEEK\fR
for details.
.SS "\fRZIP_SOURCE_STAT\fR"
Get meta information for the input data.
\fIdata\fR
points to an allocated
\fIstruct zip_stat\fR,
which should be initialized using
zip_stat_init(3)
and then filled in.
.PP
For uncompressed, unencrypted data, all information is optional.
However, fill in as much information as is readily available.
.PP
If the data is compressed,
\fRZIP_STAT_COMP_METHOD\fR,
\fRZIP_STAT_SIZE\fR,
and
\fRZIP_STAT_CRC\fR
must be filled in.
.PP
If the data is encrypted,
\fRZIP_STAT_ENCRYPTION_METHOD\fR,
\fRZIP_STAT_COMP_METHOD\fR,
\fRZIP_STAT_SIZE\fR,
and
\fRZIP_STAT_CRC\fR
must be filled in.
.PP
Information only available after the source has been read (e.g., size)
can be omitted in an earlier call.
\fINOTE\fR:
\fBzip_source_function\fR()
may be called with this argument even after being called with
\fRZIP_SOURCE_CLOSE\fR.
.PP
Return sizeof(struct zip_stat) on success.
.SS "\fRZIP_SOURCE_SUPPORTS\fR"
Return bitmap specifying which commands are supported.
Use
zip_source_make_command_bitmap(3).
If this command is not implemented, the source is assumed to be a
read source without seek support.
.SS "\fRZIP_SOURCE_TELL\fR"
Return the current read offset in the source, like
ftell(3).
.SS "\fRZIP_SOURCE_TELL_WRITE\fR"
Return the current write offset in the source, like
ftell(3).
.SS "\fRZIP_SOURCE_WRITE\fR"
Write data to the source.
Return number of bytes written.
.SS "Return Values"
Commands should return \-1 on error.
\fRZIP_SOURCE_ERROR\fR
will be called to retrieve the error code.
On success, commands return 0, unless specified otherwise in the
description above.
.SS "Calling Conventions"
The library will always issue
\fRZIP_SOURCE_OPEN\fR
before issuing
\fRZIP_SOURCE_READ\fR,
\fRZIP_SOURCE_SEEK\fR,
or
\fRZIP_SOURCE_TELL\fR.
When it no longer wishes to read from this source, it will issue
\fRZIP_SOURCE_CLOSE\fR.
If the library wishes to read the data again, it will issue
\fRZIP_SOURCE_OPEN\fR
a second time.
If the function is unable to provide the data again, it should
return \-1.
.PP
\fRZIP_SOURCE_BEGIN_WRITE\fR
or
\fRZIP_SOURCE_BEGIN_WRITE_CLONING\fR
will be called before
\fRZIP_SOURCE_WRITE\fR,
\fRZIP_SOURCE_SEEK_WRITE\fR,
or
\fRZIP_SOURCE_TELL_WRITE\fR.
When writing is complete, either
\fRZIP_SOURCE_COMMIT_WRITE\fR
or
\fRZIP_SOURCE_ROLLBACK_WRITE\fR
will be called.
.PP
\fRZIP_SOURCE_ACCEPT_EMPTY\fR,
\fRZIP_SOURCE_GET_FILE_ATTRIBUTES\fR,
and
\fRZIP_SOURCE_STAT\fR
can be issued at any time.
.PP
\fRZIP_SOURCE_ERROR\fR
will only be issued in response to the function
returning \-1.
.PP
\fRZIP_SOURCE_FREE\fR
will be the last command issued;
if
\fRZIP_SOURCE_OPEN\fR
was called and succeeded,
\fRZIP_SOURCE_CLOSE\fR
will be called before
\fRZIP_SOURCE_FREE\fR,
and similarly for
\fRZIP_SOURCE_BEGIN_WRITE\fR
or
\fRZIP_SOURCE_BEGIN_WRITE_CLONING\fR
and
\fRZIP_SOURCE_COMMIT_WRITE\fR
or
\fRZIP_SOURCE_ROLLBACK_WRITE\fR.
.SH "RETURN VALUES"
Upon successful completion, the created source is returned.
Otherwise,
\fRNULL\fR
is returned and the error code in
\fIarchive\fR
or
\fIerror\fR
is set to indicate the error (unless
it is
\fRNULL\fR).
.SH "ERRORS"
\fBzip_source_function\fR()
fails if:
.TP 19n
[\fRZIP_ER_MEMORY\fR]
Required memory could not be allocated.
.SH "SEE ALSO"
libzip(3),
zip_file_add(3),
zip_file_attributes_init(3),
zip_file_replace(3),
zip_source(3),
zip_stat_init(3)
.SH "HISTORY"
\fBzip_source_function\fR()
and
\fBzip_source_function_create\fR()
were added in libzip 1.0.
.SH "AUTHORS"
Dieter Baron <\fIdillo@nih.at\fR>
and
Thomas Klausner <\fItk@giga.or.at\fR>