1ZCHUNK(3) CZMQ Manual ZCHUNK(3)
2
6 zchunk - Class for work with memory chunks
7
9 // This is a stable class, and may not change except for emergencies. It
10 // is provided in stable builds.
11 // This class has draft methods, which may change over time. They are not
12 // in stable releases, by default. Use --enable-drafts to enable.
13 // Create a new chunk of the specified size. If you specify the data, it
14 // is copied into the chunk. If you do not specify the data, the chunk is
15 // allocated and left empty, and you can then add data using zchunk_append.
16 CZMQ_EXPORT zchunk_t *
17 zchunk_new (const void *data, size_t size);
18 // Destroy a chunk
20 CZMQ_EXPORT void
21 zchunk_destroy (zchunk_t **self_p);
22 // Resizes chunk max_size as requested; chunk_cur size is set to zero
24 CZMQ_EXPORT void
25 zchunk_resize (zchunk_t *self, size_t size);
26 // Return chunk cur size
28 CZMQ_EXPORT size_t
29 zchunk_size (zchunk_t *self);
30 // Return chunk max size
32 CZMQ_EXPORT size_t
33 zchunk_max_size (zchunk_t *self);
34 // Return chunk data
36 CZMQ_EXPORT byte *
37 zchunk_data (zchunk_t *self);
38 // Set chunk data from user-supplied data; truncate if too large. Data may
40 // be null. Returns actual size of chunk
41 CZMQ_EXPORT size_t
42 zchunk_set (zchunk_t *self, const void *data, size_t size);
43 // Fill chunk data from user-supplied octet
45 CZMQ_EXPORT size_t
46 zchunk_fill (zchunk_t *self, byte filler, size_t size);
47 // Append user-supplied data to chunk, return resulting chunk size. If the
49 // data would exceeded the available space, it is truncated. If you want to
50 // grow the chunk to accommodate new data, use the zchunk_extend method.
51 CZMQ_EXPORT size_t
52 zchunk_append (zchunk_t *self, const void *data, size_t size);
53 // Append user-supplied data to chunk, return resulting chunk size. If the
55 // data would exceeded the available space, the chunk grows in size.
56 CZMQ_EXPORT size_t
57 zchunk_extend (zchunk_t *self, const void *data, size_t size);
58 // Copy as much data from 'source' into the chunk as possible; returns the
60 // new size of chunk. If all data from 'source' is used, returns exhausted
61 // on the source chunk. Source can be consumed as many times as needed until
62 // it is exhausted. If source was already exhausted, does not change chunk.
63 CZMQ_EXPORT size_t
64 zchunk_consume (zchunk_t *self, zchunk_t *source);
65 // Returns true if the chunk was exhausted by consume methods, or if the
67 // chunk has a size of zero.
68 CZMQ_EXPORT bool
69 zchunk_exhausted (zchunk_t *self);
70 // Read chunk from an open file descriptor
72 // Caller owns return value and must destroy it when done.
73 CZMQ_EXPORT zchunk_t *
74 zchunk_read (FILE *handle, size_t bytes);
75 // Write chunk to an open file descriptor
77 CZMQ_EXPORT int
78 zchunk_write (zchunk_t *self, FILE *handle);
79 // Try to slurp an entire file into a chunk. Will read up to maxsize of
81 // the file. If maxsize is 0, will attempt to read the entire file and
82 // fail with an assertion if that cannot fit into memory. Returns a new
83 // chunk containing the file data, or NULL if the file could not be read.
84 // Caller owns return value and must destroy it when done.
85 CZMQ_EXPORT zchunk_t *
86 zchunk_slurp (const char *filename, size_t maxsize);
87 // Create copy of chunk, as new chunk object. Returns a fresh zchunk_t
89 // object, or null if there was not enough heap memory. If chunk is null,
90 // returns null.
91 // Caller owns return value and must destroy it when done.
92 CZMQ_EXPORT zchunk_t *
93 zchunk_dup (zchunk_t *self);
94 // Return chunk data encoded as printable hex string. Caller must free
96 // string when finished with it.
97 // Caller owns return value and must destroy it when done.
98 CZMQ_EXPORT char *
99 zchunk_strhex (zchunk_t *self);
100 // Return chunk data copied into freshly allocated string
102 // Caller must free string when finished with it.
103 // Caller owns return value and must destroy it when done.
104 CZMQ_EXPORT char *
105 zchunk_strdup (zchunk_t *self);
106 // Return TRUE if chunk body is equal to string, excluding terminator
108 CZMQ_EXPORT bool
109 zchunk_streq (zchunk_t *self, const char *string);
110 // Transform zchunk into a zframe that can be sent in a message.
112 // Caller owns return value and must destroy it when done.
113 CZMQ_EXPORT zframe_t *
114 zchunk_pack (zchunk_t *self);
115 // Transform a zframe into a zchunk.
117 // Caller owns return value and must destroy it when done.
118 CZMQ_EXPORT zchunk_t *
119 zchunk_unpack (zframe_t *frame);
120 // Calculate SHA1 digest for chunk, using zdigest class.
122 CZMQ_EXPORT const char *
123 zchunk_digest (zchunk_t *self);
124 // Dump chunk to FILE stream, for debugging and tracing.
126 CZMQ_EXPORT void
127 zchunk_fprint (zchunk_t *self, FILE *file);
128 // Dump message to stderr, for debugging and tracing.
130 // See zchunk_fprint for details
131 CZMQ_EXPORT void
132 zchunk_print (zchunk_t *self);
133 // Probe the supplied object, and report if it looks like a zchunk_t.
135 CZMQ_EXPORT bool
136 zchunk_is (void *self);
137 // Self test of this class.
139 CZMQ_EXPORT void
140 zchunk_test (bool verbose);
141 #ifdef CZMQ_BUILD_DRAFT_API
143 // Destroy an item
144 typedef void (zchunk_destructor_fn) (
145 void **hint);
146 // *** Draft method, for development use, may change without warning ***
148 // Create a new chunk from memory. Take ownership of the memory and calling the destructor
149 // on destroy.
150 CZMQ_EXPORT zchunk_t *
151 zchunk_frommem (void *data, size_t size, zchunk_destructor_fn destructor, void *hint);
152 // *** Draft method, for development use, may change without warning ***
154 // Transform zchunk into a zframe that can be sent in a message.
155 // Take ownership of the chunk.
156 // Caller owns return value and must destroy it when done.
157 CZMQ_EXPORT zframe_t *
158 zchunk_packx (zchunk_t **self_p);
159 #endif // CZMQ_BUILD_DRAFT_API
161 Please add '@interface' section in './../src/zchunk.c'.
162
164 The zchunk class works with variable sized blobs. Not as efficient as
165 ZeroMQ’s messages but they do less weirdness and so are easier to
166 understand. The chunk class has methods to read and write chunks from
167 disk.
168 Please add @discuss section in ./../src/zchunk.c.
170
172 From zchunk_test method.
173 zchunk_t *chunk = zchunk_new ("1234567890", 10);
175 assert (chunk);
176 assert (zchunk_size (chunk) == 10);
177 assert (memcmp (zchunk_data (chunk), "1234567890", 10) == 0);
178 zchunk_destroy (&chunk);
179 chunk = zchunk_new (NULL, 10);
181 assert (chunk);
182 zchunk_append (chunk, "12345678", 8);
183 zchunk_append (chunk, "90ABCDEF", 8);
184 zchunk_append (chunk, "GHIJKLMN", 8);
185 assert (memcmp (zchunk_data (chunk), "1234567890", 10) == 0);
186 assert (zchunk_size (chunk) == 10);
187 assert (zchunk_streq (chunk, "1234567890"));
188 assert (streq (zchunk_digest (chunk), "01B307ACBA4F54F55AAFC33BB06BBBF6CA803E9A"));
189 char *string = zchunk_strdup (chunk);
190 assert (streq (string, "1234567890"));
191 freen (string);
192 string = zchunk_strhex (chunk);
193 assert (streq (string, "31323334353637383930"));
194 freen (string);
195 zframe_t *frame = zchunk_pack (chunk);
197 assert (frame);
198 zchunk_t *chunk2 = zchunk_unpack (frame);
200 assert (chunk2);
201 assert (memcmp (zchunk_data (chunk2), "1234567890", 10) == 0);
202 zframe_destroy (&frame);
203 zchunk_destroy (&chunk2);
204 zchunk_t *copy = zchunk_dup (chunk);
206 assert (copy);
207 assert (memcmp (zchunk_data (copy), "1234567890", 10) == 0);
208 assert (zchunk_size (copy) == 10);
209 zchunk_destroy (©);
210 zchunk_destroy (&chunk);
211 chunk = zchunk_new (NULL, 0);
213 zchunk_extend (chunk, "12345678", 8);
214 zchunk_extend (chunk, "90ABCDEF", 8);
215 zchunk_extend (chunk, "GHIJKLMN", 8);
216 assert (zchunk_size (chunk) == 24);
217 assert (zchunk_streq (chunk, "1234567890ABCDEFGHIJKLMN"));
218 zchunk_destroy (&chunk);
219 copy = zchunk_new ("1234567890abcdefghij", 20);
221 assert (copy);
222 chunk = zchunk_new (NULL, 8);
223 assert (chunk);
224 zchunk_consume (chunk, copy);
225 assert (!zchunk_exhausted (copy));
226 assert (memcmp (zchunk_data (chunk), "12345678", 8) == 0);
227 zchunk_set (chunk, NULL, 0);
228 zchunk_consume (chunk, copy);
229 assert (!zchunk_exhausted (copy));
230 assert (memcmp (zchunk_data (chunk), "90abcdef", 8) == 0);
231 zchunk_set (chunk, NULL, 0);
232 zchunk_consume (chunk, copy);
233 assert (zchunk_exhausted (copy));
234 assert (zchunk_size (chunk) == 4);
235 assert (memcmp (zchunk_data (chunk), "ghij", 4) == 0);
236 zchunk_destroy (©);
237 zchunk_destroy (&chunk);
238 char str[] = "hello";
240 chunk = zchunk_frommem (str, 5, mem_destructor, str);
241 assert (chunk);
242 zchunk_destroy (&chunk);
243 // The destructor doesn't free the memory, only changing the strid,
245 // so we can check if the destructor was invoked
246 assert (streq (str, "world"));
247 chunk = zchunk_new ("1234567890", 10);
249 frame = zchunk_packx (&chunk);
250 assert (frame);
251 assert (chunk == NULL);
252 chunk = zchunk_unpack (frame);
254 assert (chunk);
255 assert (memcmp (zchunk_data (chunk), "1234567890", 10) == 0);
256 zframe_destroy (&frame);
257 zchunk_destroy (&chunk);
258 #if defined (__WINDOWS__)
260 zsys_shutdown();
261 #endif
262
265 The czmq manual was written by the authors in the AUTHORS file.
266
268 Main web site:
269 Report bugs to the email <zeromq-dev@lists.zeromq.org[1]>
271
273 Copyright (c) the Contributors as noted in the AUTHORS file. This file
274 is part of CZMQ, the high-level C binding for 0MQ:
275 http://czmq.zeromq.org. This Source Code Form is subject to the terms
276 of the Mozilla Public License, v. 2.0. If a copy of the MPL was not
277 distributed with this file, You can obtain one at
278 http://mozilla.org/MPL/2.0/. LICENSE included with the czmq
279 distribution.
280
282 1. zeromq-dev@lists.zeromq.org
283 mailto:zeromq-dev@lists.zeromq.org
284CZMQ 4.2.1 01/19/2023 ZCHUNK(3)