1ZIP_SOURCE_FUNCTION(3) BSD Library Functions Manual ZIP_SOURCE_FUNCTION(3)
2
4 zip_source_function, zip_source_function_create — create data source from
5 function
6
8 libzip (-lzip)
9
11 #include <zip.h>
12 zip_source_t *
14 zip_source_function(zip_t *archive, zip_source_callback fn,
15 void *userdata);
16 zip_source_t *
18 zip_source_function_create(zip_source_callback fn, void *userdata,
19 zip_error_t *error);
20
22 The functions zip_source_function() and zip_source_function_create() cre‐
23 ate a zip source from the user-provided function fn, which must be of the
24 following type:
25 typedef zip_int64_t (*zip_source_callback)(void *userdata, void *data,
27 zip_uint64_t len, zip_source_cmd_t cmd)
28 archive or error are used for reporting errors and can be NULL.
30 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 Depending on the uses, there are three useful sets of commands to be sup‐
38 ported by a zip_source_callback():
39 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 If your source uses any allocated memory (includ‐
46 ing userdata) it should also implement
47 ZIP_SOURCE_FREE to avoid memory leaks.
48 seekable read source Same as previous, but from a source allowing
50 reading from arbitrary offsets (also for read-
51 only zip archive). Must additionally support
52 ZIP_SOURCE_SEEK, ZIP_SOURCE_TELL, and
53 ZIP_SOURCE_SUPPORTS.
54 read/write source Same as previous, but additionally allowing writ‐
56 ing (also for writable zip archives). Must addi‐
57 tionally support ZIP_SOURCE_BEGIN_WRITE,
58 ZIP_SOURCE_COMMIT_WRITE,
59 ZIP_SOURCE_ROLLBACK_WRITE, ZIP_SOURCE_SEEK_WRITE,
60 ZIP_SOURCE_TELL_WRITE, and ZIP_SOURCE_REMOVE.
61 On top of the above, supporting the pseudo-com‐
63 mand ZIP_SOURCE_SUPPORTS_REOPEN allows calling
64 zip_source_open() again after calling
65 zip_source_close().
66 ZIP_SOURCE_ACCEPT_EMPTY
68 Return 1 if an empty source should be accepted as a valid zip archive.
69 This is the default if this command is not supported by a source. File
70 system backed sources should return 0.
71 ZIP_SOURCE_BEGIN_WRITE
73 Prepare the source for writing. Use this to create any temporary
74 file(s).
75 ZIP_SOURCE_BEGIN_WRITE_CLONING
77 Prepare the source for writing, keeping the first len bytes of the origi‐
78 nal file. Only implement this command if it is more efficient than copy‐
79 ing the data, and if it does not destructively overwrite the original
80 file (you still have to be able to execute ZIP_SOURCE_ROLLBACK_WRITE).
81 The next write should happen at byte offset.
83 ZIP_SOURCE_CLOSE
85 Reading is done.
86 ZIP_SOURCE_COMMIT_WRITE
88 Finish writing to the source. Replace the original data with the newly
89 written data. Clean up temporary files or internal buffers. Subse‐
90 quently opening and reading from the source should return the newly writ‐
91 ten data.
92 ZIP_SOURCE_ERROR
94 Get error information. data points to an array of two ints, which should
95 be filled with the libzip error code and the corresponding system error
96 code for the error that occurred. See zip_errors(3) for details on the
97 error codes. If the source stores error information in a zip_error_t,
98 use zip_error_to_data(3) and return its return value. Otherwise, return
99 2 * sizeof(int).
100 ZIP_SOURCE_FREE
102 Clean up and free all resources, including userdata. The callback func‐
103 tion will not be called again.
104 ZIP_SOURCE_GET_FILE_ATTRIBUTES
106 Provide information about various data. Then the data should be put in
107 the appropriate entry in the passed zip_file_attributes_t argument, and
108 the appropriate ZIP_FILE_ATTRIBUTES_* value must be or'ed into the valid
109 member to denote that the corresponding data has been provided. A
110 zip_file_attributes_t structure can be initialized using
111 zip_file_attributes_init(3).
112 ASCII mode If a file is a plaintext file in ASCII. Can be used by ex‐
114 traction tools to automatically convert line endings (part of
115 the internal file attributes). Member ascii, flag
116 ZIP_FILE_ATTRIBUTES_ASCII.
117 General Purpose Bit Flags (limited to Compression Flags)
119 The general purpose bit flag in the zip in the local and cen‐
120 tral directory headers contain information about the compres‐
121 sion method. Member general_purpose_bit_flags and
122 general_purpose_bit_mask to denote which members have been
123 set; flag ZIP_FILE_ATTRIBUTES_GENERAL_PURPOSE_BIT_FLAGS.
124 External File Attributes
126 The external file attributes (usually operating system-spe‐
127 cific). Member external_file_attributes, flag
128 ZIP_FILE_ATTRIBUTES_EXTERNAL_FILE_ATTRIBUTES.
129 Version Needed
131 A minimum version needed required to unpack this entry (in
132 the usual "major * 10 + minor" format). Member
133 version_needed, flag ZIP_FILE_ATTRIBUTES_VERSION_NEEDED.
134 Operating System
136 One of the operating systems as defined by the ZIP_OPSYS_*
137 variables (see zip.h). This value affects the interpretation
138 of the external file attributes. Member host_system, flag
139 ZIP_FILE_ATTRIBUTES_HOST_SYSTEM.
140 ZIP_SOURCE_OPEN
142 Prepare for reading.
143 ZIP_SOURCE_READ
145 Read data into the buffer data of size len. Return the number of bytes
146 placed into data on success, and zero for end-of-file.
147 ZIP_SOURCE_REMOVE
149 Remove the underlying file. This is called if a zip archive is empty
150 when closed.
151 ZIP_SOURCE_ROLLBACK_WRITE
153 Abort writing to the source. Discard written data. Clean up temporary
154 files or internal buffers. Subsequently opening and reading from the
155 source should return the original data.
156 ZIP_SOURCE_SEEK
158 Specify position to read next byte from, like fseek(3). Use
159 ZIP_SOURCE_GET_ARGS(3) to decode the arguments into the following struct:
160 struct zip_source_args_seek {
162 zip_int64_t offset;
163 int whence;
164 };
165 If the size of the source's data is known, use
167 zip_source_seek_compute_offset(3) to validate the arguments and compute
168 the new offset.
169 ZIP_SOURCE_SEEK_WRITE
171 Specify position to write next byte to, like fseek(3). See
172 ZIP_SOURCE_SEEK for details.
173 ZIP_SOURCE_STAT
175 Get meta information for the input data. data points to an allocated
176 struct zip_stat, which should be initialized using zip_stat_init(3) and
177 then filled in.
178 For uncompressed, unencrypted data, all information is optional. How‐
180 ever, fill in as much information as is readily available.
181 If the data is compressed, ZIP_STAT_COMP_METHOD, ZIP_STAT_SIZE, and
183 ZIP_STAT_CRC must be filled in.
184 If the data is encrypted, ZIP_STAT_ENCRYPTION_METHOD,
186 ZIP_STAT_COMP_METHOD, ZIP_STAT_SIZE, and ZIP_STAT_CRC must be filled in.
187 Information only available after the source has been read (e.g., size)
189 can be omitted in an earlier call. NOTE: zip_source_function() may be
190 called with this argument even after being called with ZIP_SOURCE_CLOSE.
191 Return sizeof(struct zip_stat) on success.
193 ZIP_SOURCE_SUPPORTS
195 Return bitmap specifying which commands are supported. Use
196 zip_source_make_command_bitmap(3). If this command is not implemented,
197 the source is assumed to be a read source without seek support.
198 ZIP_SOURCE_TELL
200 Return the current read offset in the source, like ftell(3).
201 ZIP_SOURCE_TELL_WRITE
203 Return the current write offset in the source, like ftell(3).
204 ZIP_SOURCE_WRITE
206 Write data to the source. Return number of bytes written.
207 ZIP_SOURCE_SUPPORTS_REOPEN
209 This command is never actually invoked, support for it signals the abil‐
210 ity to handle multiple open/read/close cycles.
211 Return Values
213 Commands should return -1 on error. ZIP_SOURCE_ERROR will be called to
214 retrieve the error code. On success, commands return 0, unless specified
215 otherwise in the description above.
216 Calling Conventions
218 The library will always issue ZIP_SOURCE_OPEN before issuing
219 ZIP_SOURCE_READ, ZIP_SOURCE_SEEK, or ZIP_SOURCE_TELL. When it no longer
220 wishes to read from this source, it will issue ZIP_SOURCE_CLOSE. If the
221 library wishes to read the data again, it will issue ZIP_SOURCE_OPEN a
222 second time. If the function is unable to provide the data again, it
223 should return -1.
224 ZIP_SOURCE_BEGIN_WRITE or ZIP_SOURCE_BEGIN_WRITE_CLONING will be called
226 before ZIP_SOURCE_WRITE, ZIP_SOURCE_SEEK_WRITE, or ZIP_SOURCE_TELL_WRITE.
227 When writing is complete, either ZIP_SOURCE_COMMIT_WRITE or
228 ZIP_SOURCE_ROLLBACK_WRITE will be called.
229 ZIP_SOURCE_ACCEPT_EMPTY, ZIP_SOURCE_GET_FILE_ATTRIBUTES, and
231 ZIP_SOURCE_STAT can be issued at any time.
232 ZIP_SOURCE_ERROR will only be issued in response to the function return‐
234 ing -1.
235 ZIP_SOURCE_FREE will be the last command issued; if ZIP_SOURCE_OPEN was
237 called and succeeded, ZIP_SOURCE_CLOSE will be called before
238 ZIP_SOURCE_FREE, and similarly for ZIP_SOURCE_BEGIN_WRITE or
239 ZIP_SOURCE_BEGIN_WRITE_CLONING and ZIP_SOURCE_COMMIT_WRITE or
240 ZIP_SOURCE_ROLLBACK_WRITE.
241
243 Upon successful completion, the created source is returned. Otherwise,
244 NULL is returned and the error code in archive or error is set to indi‐
245 cate the error (unless it is NULL).
246
248 zip_source_function() fails if:
249 [ZIP_ER_MEMORY] Required memory could not be allocated.
251
253 libzip(3), zip_file_add(3), zip_file_attributes_init(3),
254 zip_file_replace(3), zip_source(3), zip_stat_init(3)
255
257 zip_source_function() and zip_source_function_create() were added in
258 libzip 1.0.
259
261 Dieter Baron <dillo@nih.at> and Thomas Klausner <tk@giga.or.at>
262BSD January 5, 2023 BSD