1ZCHUNK(3)                         CZMQ Manual                        ZCHUNK(3)
2
3
4

NAME

6       zchunk - Class for work with memory chunks
7

SYNOPSIS

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
19       //  Destroy a chunk
20       CZMQ_EXPORT void
21           zchunk_destroy (zchunk_t **self_p);
22
23       //  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
27       //  Return chunk cur size
28       CZMQ_EXPORT size_t
29           zchunk_size (zchunk_t *self);
30
31       //  Return chunk max size
32       CZMQ_EXPORT size_t
33           zchunk_max_size (zchunk_t *self);
34
35       //  Return chunk data
36       CZMQ_EXPORT byte *
37           zchunk_data (zchunk_t *self);
38
39       //  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
44       //  Fill chunk data from user-supplied octet
45       CZMQ_EXPORT size_t
46           zchunk_fill (zchunk_t *self, byte filler, size_t size);
47
48       //  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
54       //  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
59       //  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
66       //  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
71       //  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
76       //  Write chunk to an open file descriptor
77       CZMQ_EXPORT int
78           zchunk_write (zchunk_t *self, FILE *handle);
79
80       //  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
88       //  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
95       //  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
101       //  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
107       //  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
111       //  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
116       //  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
121       //  Calculate SHA1 digest for chunk, using zdigest class.
122       CZMQ_EXPORT const char *
123           zchunk_digest (zchunk_t *self);
124
125       //  Dump chunk to FILE stream, for debugging and tracing.
126       CZMQ_EXPORT void
127           zchunk_fprint (zchunk_t *self, FILE *file);
128
129       //  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
134       //  Probe the supplied object, and report if it looks like a zchunk_t.
135       CZMQ_EXPORT bool
136           zchunk_is (void *self);
137
138       //  Self test of this class.
139       CZMQ_EXPORT void
140           zchunk_test (bool verbose);
141
142       #ifdef CZMQ_BUILD_DRAFT_API
143       // Destroy an item
144       typedef void (zchunk_destructor_fn) (
145           void **hint);
146
147       //  *** 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
153       //  *** 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
160       #endif // CZMQ_BUILD_DRAFT_API
161       Please add '@interface' section in './../src/zchunk.c'.
162

DESCRIPTION

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
169       Please add @discuss section in ./../src/zchunk.c.
170

EXAMPLE

172       From zchunk_test method.
173
174           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
180           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
196           zframe_t *frame = zchunk_pack (chunk);
197           assert (frame);
198
199           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
205           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 (&copy);
210           zchunk_destroy (&chunk);
211
212           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
220           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 (&copy);
237           zchunk_destroy (&chunk);
238
239           char str[] = "hello";
240           chunk = zchunk_frommem (str, 5, mem_destructor, str);
241           assert (chunk);
242           zchunk_destroy (&chunk);
243
244           //  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
248           chunk = zchunk_new ("1234567890", 10);
249           frame = zchunk_packx (&chunk);
250           assert (frame);
251           assert (chunk == NULL);
252
253           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
259           #if defined (__WINDOWS__)
260           zsys_shutdown();
261           #endif
262
263

AUTHORS

265       The czmq manual was written by the authors in the AUTHORS file.
266

RESOURCES

268       Main web site:
269
270       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

NOTES

282        1. zeromq-dev@lists.zeromq.org
283           mailto:zeromq-dev@lists.zeromq.org
284
285
286
287CZMQ 4.2.1                        01/19/2023                         ZCHUNK(3)
Impressum