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 ates a zip source from the user-provided function fn, which must be of
24 the 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 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 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 ZIP_SOURCE_BEGIN_WRITE
59 Prepare the source for writing. Use this to create any temporary
60 file(s).
61 ZIP_SOURCE_BEGIN_WRITE_CLONING
63 Prepare the source for writing, keeping the first len bytes of the origi‐
64 nal file. Only implement this command if it is more efficient than copy‐
65 ing the data, and if it does not destructively overwrite the original
66 file (you still have to be able to execute ZIP_SOURCE_ROLLBACK_WRITE).
67 The next write should happen at byte offset.
69 ZIP_SOURCE_CLOSE
71 Reading is done.
72 ZIP_SOURCE_COMMIT_WRITE
74 Finish writing to the source. Replace the original data with the newly
75 written data. Clean up temporary files or internal buffers. Subse‐
76 quently opening and reading from the source should return the newly writ‐
77 ten data.
78 ZIP_SOURCE_ERROR
80 Get error information. data points to an array of two ints, which should
81 be filled with the libzip error code and the corresponding system error
82 code for the error that occurred. See zip_errors(3) for details on the
83 error codes. If the source stores error information in a zip_error_t,
84 use zip_error_to_data(3) and return its return value. Otherwise, return
85 2 * sizeof(int).
86 ZIP_SOURCE_FREE
88 Clean up and free all resources, including userdata. The callback func‐
89 tion will not be called again.
90 ZIP_SOURCE_OPEN
92 Prepare for reading.
93 ZIP_SOURCE_READ
95 Read data into the buffer data of size len. Return the number of bytes
96 placed into data on success, and zero for end-of-file.
97 ZIP_SOURCE_REMOVE
99 Remove the underlying file. This is called if a zip archive is empty
100 when closed.
101 ZIP_SOURCE_ROLLBACK_WRITE
103 Abort writing to the source. Discard written data. Clean up temporary
104 files or internal buffers. Subsequently opening and reading from the
105 source should return the original data.
106 ZIP_SOURCE_SEEK
108 Specify position to read next byte from, like fseek(3). Use
109 ZIP_SOURCE_GET_ARGS(3) to decode the arguments into the following struct:
110 struct zip_source_args_seek {
112 zip_int64_t offset;
113 int whence;
114 };
115 If the size of the source's data is known, use
117 zip_source_seek_compute_offset(3) to validate the arguments and compute
118 the new offset.
119 ZIP_SOURCE_SEEK_WRITE
121 Specify position to write next byte to, like fseek(3). See
122 ZIP_SOURCE_SEEK for details.
123 ZIP_SOURCE_STAT
125 Get meta information for the input data. data points to an allocated
126 struct zip_stat, which should be initialized using zip_stat_init(3) and
127 then filled in.
128 For uncompressed, unencrypted data, all information is optional. How‐
130 ever, fill in as much information as is readily available.
131 If the data is compressed, ZIP_STAT_COMP_METHOD, ZIP_STAT_SIZE, and
133 ZIP_STAT_CRC must be filled in.
134 If the data is encrypted, ZIP_STAT_ENCRYPTION_METHOD,
136 ZIP_STAT_COMP_METHOD, ZIP_STAT_SIZE, and ZIP_STAT_CRC must be filled in.
137 Information only available after the source has been read (e.g., size)
139 can be omitted in an earlier call. NOTE: zip_source_function() may be
140 called with this argument even after being called with ZIP_SOURCE_CLOSE.
141 Return sizeof(struct zip_stat) on success.
143 ZIP_SOURCE_SUPPORTS
145 Return bitmap specifying which commands are supported. Use
146 zip_source_make_command_bitmap(3). If this command is not implemented,
147 the source is assumed to be a read source without seek support.
148 ZIP_SOURCE_TELL
150 Return the current read offset in the source, like ftell(3).
151 ZIP_SOURCE_TELL_WRITE
153 Return the current write offset in the source, like ftell(3).
154 ZIP_SOURCE_WRITE
156 Write data to the source. Return number of bytes written.
157 Return Values
159 Commands should return -1 on error. ZIP_SOURCE_ERROR will be called to
160 retrieve the error code. On success, commands return 0, unless specified
161 otherwise in the description above.
162 Calling Conventions
164 The library will always issue ZIP_SOURCE_OPEN before issuing
165 ZIP_SOURCE_READ, ZIP_SOURCE_SEEK, or ZIP_SOURCE_TELL. When it no longer
166 wishes to read from this source, it will issue ZIP_SOURCE_CLOSE. If the
167 library wishes to read the data again, it will issue ZIP_SOURCE_OPEN a
168 second time. If the function is unable to provide the data again, it
169 should return -1.
170 ZIP_SOURCE_BEGIN_WRITE or ZIP_SOURCE_BEGIN_WRITE_CLONING will be called
172 before ZIP_SOURCE_WRITE, ZIP_SOURCE_SEEK_WRITE, or ZIP_SOURCE_TELL_WRITE.
173 When writing is complete, either ZIP_SOURCE_COMMIT_WRITE or
174 ZIP_SOURCE_ROLLBACK_WRITE will be called.
175 ZIP_SOURCE_STAT can be issued at any time.
177 ZIP_SOURCE_ERROR will only be issued in response to the function return‐
179 ing -1.
180 ZIP_SOURCE_FREE will be the last command issued; if ZIP_SOURCE_OPEN was
182 called and succeeded, ZIP_SOURCE_CLOSE will be called before
183 ZIP_SOURCE_FREE, and similarly for ZIP_SOURCE_BEGIN_WRITE or
184 ZIP_SOURCE_BEGIN_WRITE_CLONING and ZIP_SOURCE_COMMIT_WRITE or
185 ZIP_SOURCE_ROLLBACK_WRITE.
186
188 Upon successful completion, the created source is returned. Otherwise,
189 NULL is returned and the error code in archive or error is set to indi‐
190 cate the error (unless it is NULL).
191
193 zip_source_function() fails if:
194 [ZIP_ER_MEMORY] Required memory could not be allocated.
196
198 libzip(3), zip_file_add(3), zip_file_replace(3), zip_source(3),
199 zip_stat_init(3)
200
202 zip_source_function() and zip_source_function_create() were added in
203 libzip 1.0.
204
206 Dieter Baron <dillo@nih.at> and Thomas Klausner <tk@giga.or.at>
207BSD December 18, 2017 BSD