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 // Create a new chunk of the specified size. If you specify the data, it
12 // is copied into the chunk. If you do not specify the data, the chunk is
13 // allocated and left empty, and you can then add data using zchunk_append.
14 CZMQ_EXPORT zchunk_t *
15 zchunk_new (const void *data, size_t size);
16 // Destroy a chunk
18 CZMQ_EXPORT void
19 zchunk_destroy (zchunk_t **self_p);
20 // Resizes chunk max_size as requested; chunk_cur size is set to zero
22 CZMQ_EXPORT void
23 zchunk_resize (zchunk_t *self, size_t size);
24 // Return chunk cur size
26 CZMQ_EXPORT size_t
27 zchunk_size (zchunk_t *self);
28 // Return chunk max size
30 CZMQ_EXPORT size_t
31 zchunk_max_size (zchunk_t *self);
32 // Return chunk data
34 CZMQ_EXPORT byte *
35 zchunk_data (zchunk_t *self);
36 // Set chunk data from user-supplied data; truncate if too large. Data may
38 // be null. Returns actual size of chunk
39 CZMQ_EXPORT size_t
40 zchunk_set (zchunk_t *self, const void *data, size_t size);
41 // Fill chunk data from user-supplied octet
43 CZMQ_EXPORT size_t
44 zchunk_fill (zchunk_t *self, byte filler, size_t size);
45 // Append user-supplied data to chunk, return resulting chunk size. If the
47 // data would exceeded the available space, it is truncated. If you want to
48 // grow the chunk to accommodate new data, use the zchunk_extend method.
49 CZMQ_EXPORT size_t
50 zchunk_append (zchunk_t *self, const void *data, size_t size);
51 // Append user-supplied data to chunk, return resulting chunk size. If the
53 // data would exceeded the available space, the chunk grows in size.
54 CZMQ_EXPORT size_t
55 zchunk_extend (zchunk_t *self, const void *data, size_t size);
56 // Copy as much data from 'source' into the chunk as possible; returns the
58 // new size of chunk. If all data from 'source' is used, returns exhausted
59 // on the source chunk. Source can be consumed as many times as needed until
60 // it is exhausted. If source was already exhausted, does not change chunk.
61 CZMQ_EXPORT size_t
62 zchunk_consume (zchunk_t *self, zchunk_t *source);
63 // Returns true if the chunk was exhausted by consume methods, or if the
65 // chunk has a size of zero.
66 CZMQ_EXPORT bool
67 zchunk_exhausted (zchunk_t *self);
68 // Read chunk from an open file descriptor
70 // Caller owns return value and must destroy it when done.
71 CZMQ_EXPORT zchunk_t *
72 zchunk_read (FILE *handle, size_t bytes);
73 // Write chunk to an open file descriptor
75 CZMQ_EXPORT int
76 zchunk_write (zchunk_t *self, FILE *handle);
77 // Try to slurp an entire file into a chunk. Will read up to maxsize of
79 // the file. If maxsize is 0, will attempt to read the entire file and
80 // fail with an assertion if that cannot fit into memory. Returns a new
81 // chunk containing the file data, or NULL if the file could not be read.
82 // Caller owns return value and must destroy it when done.
83 CZMQ_EXPORT zchunk_t *
84 zchunk_slurp (const char *filename, size_t maxsize);
85 // Create copy of chunk, as new chunk object. Returns a fresh zchunk_t
87 // object, or null if there was not enough heap memory. If chunk is null,
88 // returns null.
89 // Caller owns return value and must destroy it when done.
90 CZMQ_EXPORT zchunk_t *
91 zchunk_dup (zchunk_t *self);
92 // Return chunk data encoded as printable hex string. Caller must free
94 // string when finished with it.
95 // Caller owns return value and must destroy it when done.
96 CZMQ_EXPORT char *
97 zchunk_strhex (zchunk_t *self);
98 // Return chunk data copied into freshly allocated string
100 // Caller must free string when finished with it.
101 // Caller owns return value and must destroy it when done.
102 CZMQ_EXPORT char *
103 zchunk_strdup (zchunk_t *self);
104 // Return TRUE if chunk body is equal to string, excluding terminator
106 CZMQ_EXPORT bool
107 zchunk_streq (zchunk_t *self, const char *string);
108 // Transform zchunk into a zframe that can be sent in a message.
110 // Caller owns return value and must destroy it when done.
111 CZMQ_EXPORT zframe_t *
112 zchunk_pack (zchunk_t *self);
113 // Transform a zframe into a zchunk.
115 // Caller owns return value and must destroy it when done.
116 CZMQ_EXPORT zchunk_t *
117 zchunk_unpack (zframe_t *frame);
118 // Calculate SHA1 digest for chunk, using zdigest class.
120 CZMQ_EXPORT const char *
121 zchunk_digest (zchunk_t *self);
122 // Dump chunk to FILE stream, for debugging and tracing.
124 CZMQ_EXPORT void
125 zchunk_fprint (zchunk_t *self, FILE *file);
126 // Dump message to stderr, for debugging and tracing.
128 // See zchunk_fprint for details
129 CZMQ_EXPORT void
130 zchunk_print (zchunk_t *self);
131 // Probe the supplied object, and report if it looks like a zchunk_t.
133 CZMQ_EXPORT bool
134 zchunk_is (void *self);
135 // Self test of this class.
137 CZMQ_EXPORT void
138 zchunk_test (bool verbose);
139 Please add '@interface' section in './../src/zchunk.c'.
141
143 The zchunk class works with variable sized blobs. Not as efficient as
144 ZeroMQ’s messages but they do less weirdness and so are easier to
145 understand. The chunk class has methods to read and write chunks from
146 disk.
147 Please add @discuss section in ./../src/zchunk.c.
149
151 From zchunk_test method.
152 zchunk_t *chunk = zchunk_new ("1234567890", 10);
154 assert (chunk);
155 assert (zchunk_size (chunk) == 10);
156 assert (memcmp (zchunk_data (chunk), "1234567890", 10) == 0);
157 zchunk_destroy (&chunk);
158 chunk = zchunk_new (NULL, 10);
160 assert (chunk);
161 zchunk_append (chunk, "12345678", 8);
162 zchunk_append (chunk, "90ABCDEF", 8);
163 zchunk_append (chunk, "GHIJKLMN", 8);
164 assert (memcmp (zchunk_data (chunk), "1234567890", 10) == 0);
165 assert (zchunk_size (chunk) == 10);
166 assert (zchunk_streq (chunk, "1234567890"));
167 assert (streq (zchunk_digest (chunk), "01B307ACBA4F54F55AAFC33BB06BBBF6CA803E9A"));
168 char *string = zchunk_strdup (chunk);
169 assert (streq (string, "1234567890"));
170 freen (string);
171 string = zchunk_strhex (chunk);
172 assert (streq (string, "31323334353637383930"));
173 freen (string);
174 zframe_t *frame = zchunk_pack (chunk);
176 assert (frame);
177 zchunk_t *chunk2 = zchunk_unpack (frame);
179 assert (chunk2);
180 assert (memcmp (zchunk_data (chunk2), "1234567890", 10) == 0);
181 zframe_destroy (&frame);
182 zchunk_destroy (&chunk2);
183 zchunk_t *copy = zchunk_dup (chunk);
185 assert (copy);
186 assert (memcmp (zchunk_data (copy), "1234567890", 10) == 0);
187 assert (zchunk_size (copy) == 10);
188 zchunk_destroy (©);
189 zchunk_destroy (&chunk);
190 chunk = zchunk_new (NULL, 0);
192 zchunk_extend (chunk, "12345678", 8);
193 zchunk_extend (chunk, "90ABCDEF", 8);
194 zchunk_extend (chunk, "GHIJKLMN", 8);
195 assert (zchunk_size (chunk) == 24);
196 assert (zchunk_streq (chunk, "1234567890ABCDEFGHIJKLMN"));
197 zchunk_destroy (&chunk);
198 copy = zchunk_new ("1234567890abcdefghij", 20);
200 assert (copy);
201 chunk = zchunk_new (NULL, 8);
202 assert (chunk);
203 zchunk_consume (chunk, copy);
204 assert (!zchunk_exhausted (copy));
205 assert (memcmp (zchunk_data (chunk), "12345678", 8) == 0);
206 zchunk_set (chunk, NULL, 0);
207 zchunk_consume (chunk, copy);
208 assert (!zchunk_exhausted (copy));
209 assert (memcmp (zchunk_data (chunk), "90abcdef", 8) == 0);
210 zchunk_set (chunk, NULL, 0);
211 zchunk_consume (chunk, copy);
212 assert (zchunk_exhausted (copy));
213 assert (zchunk_size (chunk) == 4);
214 assert (memcmp (zchunk_data (chunk), "ghij", 4) == 0);
215 zchunk_destroy (©);
216 zchunk_destroy (&chunk);
217 #if defined (__WINDOWS__)
219 zsys_shutdown();
220 #endif
221
224 The czmq manual was written by the authors in the AUTHORS file.
225
227 Main web site:
228 Report bugs to the email <zeromq-dev@lists.zeromq.org[1]>
230
232 Copyright (c) the Contributors as noted in the AUTHORS file. This file
233 is part of CZMQ, the high-level C binding for 0MQ:
234 http://czmq.zeromq.org. This Source Code Form is subject to the terms
235 of the Mozilla Public License, v. 2.0. If a copy of the MPL was not
236 distributed with this file, You can obtain one at
237 http://mozilla.org/MPL/2.0/. LICENSE included with the czmq
238 distribution.
239
241 1. zeromq-dev@lists.zeromq.org
242 mailto:zeromq-dev@lists.zeromq.org
243CZMQ 4.1.1 07/24/2019 ZCHUNK(3)