1ZIP_SOURCE_FUNCTION(3)   BSD Library Functions Manual   ZIP_SOURCE_FUNCTION(3)
2

NAME

4     zip_source_function, zip_source_function_create — create data source from
5     function
6

LIBRARY

8     libzip (-lzip)
9

SYNOPSIS

11     #include <zip.h>
12
13     zip_source_t *
14     zip_source_function(zip_t *archive, zip_source_callback fn,
15         void *userdata);
16
17     zip_source_t *
18     zip_source_function_create(zip_source_callback fn, void *userdata,
19         zip_error_t *error);
20

DESCRIPTION

22     The functions zip_source_function() and zip_source_function_create() cre‐
23     ates a zip source from the user-provided function fn, which must be of
24     the following type:
25
26     typedef zip_int64_t (*zip_source_callback)(void *userdata, void *data,
27     zip_uint64_t len, zip_source_cmd_t cmd)
28
29     archive or error are used for reporting errors and can be NULL.
30
31     When called by the library, the first argument is the userdata argument
32     supplied to the function.  The next two arguments are a buffer data of
33     size len when data is passed in or expected to be returned, or else NULL
34     and 0.  The last argument, cmd, specifies which action the function
35     should perform.
36
37     Depending on the uses, there are three useful sets of commands to be sup‐
38     ported by a zip_source_callback():
39
40     read source             Providing streamed data (for file data added to
41                             archives).  Must support ZIP_SOURCE_OPEN,
42                             ZIP_SOURCE_READ, ZIP_SOURCE_CLOSE,
43                             ZIP_SOURCE_STAT, and ZIP_SOURCE_ERROR.
44
45     seekable read source    Same as previous, but from a source allowing
46                             reading from arbitrary offsets (also for read-
47                             only zip archive).  Must additionally support
48                             ZIP_SOURCE_SEEK, ZIP_SOURCE_TELL, and
49                             ZIP_SOURCE_SUPPORTS.
50
51     read/write source       Same as previous, but additionally allowing writ‐
52                             ing (also for writable zip archives).  Must addi‐
53                             tionally support ZIP_SOURCE_BEGIN_WRITE,
54                             ZIP_SOURCE_COMMIT_WRITE,
55                             ZIP_SOURCE_ROLLBACK_WRITE, ZIP_SOURCE_SEEK_WRITE,
56                             ZIP_SOURCE_TELL_WRITE, and ZIP_SOURCE_REMOVE.
57
58   ZIP_SOURCE_ACCEPT_EMPTY
59     Return 1 if an empty source should be accepted as a valid zip archive.
60     This is the default if this command is not supported by a source.  File
61     system backed sources should return 0.
62
63   ZIP_SOURCE_BEGIN_WRITE
64     Prepare the source for writing.  Use this to create any temporary
65     file(s).
66
67   ZIP_SOURCE_BEGIN_WRITE_CLONING
68     Prepare the source for writing, keeping the first len bytes of the origi‐
69     nal file.  Only implement this command if it is more efficient than copy‐
70     ing the data, and if it does not destructively overwrite the original
71     file (you still have to be able to execute ZIP_SOURCE_ROLLBACK_WRITE).
72
73     The next write should happen at byte offset.
74
75   ZIP_SOURCE_CLOSE
76     Reading is done.
77
78   ZIP_SOURCE_COMMIT_WRITE
79     Finish writing to the source.  Replace the original data with the newly
80     written data.  Clean up temporary files or internal buffers.  Subse‐
81     quently opening and reading from the source should return the newly writ‐
82     ten data.
83
84   ZIP_SOURCE_ERROR
85     Get error information.  data points to an array of two ints, which should
86     be filled with the libzip error code and the corresponding system error
87     code for the error that occurred.  See zip_errors(3) for details on the
88     error codes.  If the source stores error information in a zip_error_t,
89     use zip_error_to_data(3) and return its return value.  Otherwise, return
90     2 * sizeof(int).
91
92   ZIP_SOURCE_FREE
93     Clean up and free all resources, including userdata.  The callback func‐
94     tion will not be called again.
95
96   ZIP_SOURCE_GET_FILE_ATTRIBUTES
97     Provide information about various data.  Then the data should be put in
98     the appropriate entry in the passed zip_file_attributes_t argument, and
99     the appropriate ZIP_FILE_ATTRIBUTES_* value must be or'ed into the valid
100     member to denote that the corresponding data has been provided.  A
101     zip_file_attributes_t structure can be initialized using
102     zip_file_attributes_init(3).
103
104     ASCII mode  If a file is a plaintext file in ASCII.  Can be used by
105                 extraction tools to automatically convert line endings (part
106                 of the interal file attributes).  Member ascii, flag
107                 ZIP_FILE_ATTRIBUTES_ASCII.
108
109     General Purpose Bit Flags (limited to Compression Flags)
110                 The general purpose bit flag in the zip in the local and cen‐
111                 tral directory headers contain information about the compres‐
112                 sion method.  Member general_purpose_bit_flags and
113                 general_purpose_bit_mask to denote which members have been
114                 set; flag ZIP_FILE_ATTRIBUTES_GENERAL_PURPOSE_BIT_FLAGS.
115
116     External File Attributes
117                 The external file attributes (usually operating system-spe‐
118                 cific).  Member external_file_attributes, flag
119                 ZIP_FILE_ATTRIBUTES_EXTERNAL_FILE_ATTRIBUTES.
120
121     Version Needed
122                 A minimum version needed required to unpack this entry (in
123                 the usual "major * 10 + minor" format).  Member
124                 version_needed, flag ZIP_FILE_ATTRIBUTES_VERSION_NEEDED.
125
126     Operating System
127                 One of the operating systems as defined by the ZIP_OPSYS_*
128                 variables (see zip.h).  This value affects the interpretation
129                 of the external file attributes.  Member host_system, flag
130                 ZIP_FILE_ATTRIBUTES_HOST_SYSTEM.
131
132   ZIP_SOURCE_OPEN
133     Prepare for reading.
134
135   ZIP_SOURCE_READ
136     Read data into the buffer data of size len.  Return the number of bytes
137     placed into data on success, and zero for end-of-file.
138
139   ZIP_SOURCE_REMOVE
140     Remove the underlying file.  This is called if a zip archive is empty
141     when closed.
142
143   ZIP_SOURCE_ROLLBACK_WRITE
144     Abort writing to the source.  Discard written data.  Clean up temporary
145     files or internal buffers.  Subsequently opening and reading from the
146     source should return the original data.
147
148   ZIP_SOURCE_SEEK
149     Specify position to read next byte from, like fseek(3).  Use
150     ZIP_SOURCE_GET_ARGS(3) to decode the arguments into the following struct:
151
152     struct zip_source_args_seek {
153         zip_int64_t offset;
154         int whence;
155     };
156
157     If the size of the source's data is known, use
158     zip_source_seek_compute_offset(3) to validate the arguments and compute
159     the new offset.
160
161   ZIP_SOURCE_SEEK_WRITE
162     Specify position to write next byte to, like fseek(3).  See
163     ZIP_SOURCE_SEEK for details.
164
165   ZIP_SOURCE_STAT
166     Get meta information for the input data.  data points to an allocated
167     struct zip_stat, which should be initialized using zip_stat_init(3) and
168     then filled in.
169
170     For uncompressed, unencrypted data, all information is optional.  How‐
171     ever, fill in as much information as is readily available.
172
173     If the data is compressed, ZIP_STAT_COMP_METHOD, ZIP_STAT_SIZE, and
174     ZIP_STAT_CRC must be filled in.
175
176     If the data is encrypted, ZIP_STAT_ENCRYPTION_METHOD,
177     ZIP_STAT_COMP_METHOD, ZIP_STAT_SIZE, and ZIP_STAT_CRC must be filled in.
178
179     Information only available after the source has been read (e.g., size)
180     can be omitted in an earlier call.  NOTE: zip_source_function() may be
181     called with this argument even after being called with ZIP_SOURCE_CLOSE.
182
183     Return sizeof(struct zip_stat) on success.
184
185   ZIP_SOURCE_SUPPORTS
186     Return bitmap specifying which commands are supported.  Use
187     zip_source_make_command_bitmap(3).  If this command is not implemented,
188     the source is assumed to be a read source without seek support.
189
190   ZIP_SOURCE_TELL
191     Return the current read offset in the source, like ftell(3).
192
193   ZIP_SOURCE_TELL_WRITE
194     Return the current write offset in the source, like ftell(3).
195
196   ZIP_SOURCE_WRITE
197     Write data to the source.  Return number of bytes written.
198
199   Return Values
200     Commands should return -1 on error.  ZIP_SOURCE_ERROR will be called to
201     retrieve the error code.  On success, commands return 0, unless specified
202     otherwise in the description above.
203
204   Calling Conventions
205     The library will always issue ZIP_SOURCE_OPEN before issuing
206     ZIP_SOURCE_READ, ZIP_SOURCE_SEEK, or ZIP_SOURCE_TELL.  When it no longer
207     wishes to read from this source, it will issue ZIP_SOURCE_CLOSE.  If the
208     library wishes to read the data again, it will issue ZIP_SOURCE_OPEN a
209     second time.  If the function is unable to provide the data again, it
210     should return -1.
211
212     ZIP_SOURCE_BEGIN_WRITE or ZIP_SOURCE_BEGIN_WRITE_CLONING will be called
213     before ZIP_SOURCE_WRITE, ZIP_SOURCE_SEEK_WRITE, or ZIP_SOURCE_TELL_WRITE.
214     When writing is complete, either ZIP_SOURCE_COMMIT_WRITE or
215     ZIP_SOURCE_ROLLBACK_WRITE will be called.
216
217     ZIP_SOURCE_ACCEPT_EMPTY, ZIP_SOURCE_GET_FILE_ATTRIBUTES, and
218     ZIP_SOURCE_STAT can be issued at any time.
219
220     ZIP_SOURCE_ERROR will only be issued in response to the function return‐
221     ing -1.
222
223     ZIP_SOURCE_FREE will be the last command issued; if ZIP_SOURCE_OPEN was
224     called and succeeded, ZIP_SOURCE_CLOSE will be called before
225     ZIP_SOURCE_FREE, and similarly for ZIP_SOURCE_BEGIN_WRITE or
226     ZIP_SOURCE_BEGIN_WRITE_CLONING and ZIP_SOURCE_COMMIT_WRITE or
227     ZIP_SOURCE_ROLLBACK_WRITE.
228

RETURN VALUES

230     Upon successful completion, the created source is returned.  Otherwise,
231     NULL is returned and the error code in archive or error is set to indi‐
232     cate the error (unless it is NULL).
233

ERRORS

235     zip_source_function() fails if:
236
237     [ZIP_ER_MEMORY]    Required memory could not be allocated.
238

SEE ALSO

240     libzip(3), zip_file_add(3), zip_file_attributes_init(3),
241     zip_file_replace(3), zip_source(3), zip_stat_init(3)
242

HISTORY

244     zip_source_function() and zip_source_function_create() were added in
245     libzip 1.0.
246

AUTHORS

248     Dieter Baron <dillo@nih.at> and Thomas Klausner <tk@giga.or.at>
249
250BSD                             April 17, 2020                             BSD
Impressum