ZCHUNK(3) CZMQ Manual ZCHUNK(3) NAME zchunk - Class for work with memory chunks SYNOPSIS // This is a stable class, and may not change except for emergencies. It // is provided in stable builds. // This class has draft methods, which may change over time. They are not // in stable releases, by default. Use --enable-drafts to enable. // Create a new chunk of the specified size. If you specify the data, it // is copied into the chunk. If you do not specify the data, the chunk is // allocated and left empty, and you can then add data using zchunk_append. CZMQ_EXPORT zchunk_t * zchunk_new (const void *data, size_t size); // Destroy a chunk CZMQ_EXPORT void zchunk_destroy (zchunk_t **self_p); // Resizes chunk max_size as requested; chunk_cur size is set to zero CZMQ_EXPORT void zchunk_resize (zchunk_t *self, size_t size); // Return chunk cur size CZMQ_EXPORT size_t zchunk_size (zchunk_t *self); // Return chunk max size CZMQ_EXPORT size_t zchunk_max_size (zchunk_t *self); // Return chunk data CZMQ_EXPORT byte * zchunk_data (zchunk_t *self); // Set chunk data from user-supplied data; truncate if too large. Data may // be null. Returns actual size of chunk CZMQ_EXPORT size_t zchunk_set (zchunk_t *self, const void *data, size_t size); // Fill chunk data from user-supplied octet CZMQ_EXPORT size_t zchunk_fill (zchunk_t *self, byte filler, size_t size); // Append user-supplied data to chunk, return resulting chunk size. If the // data would exceeded the available space, it is truncated. If you want to // grow the chunk to accommodate new data, use the zchunk_extend method. CZMQ_EXPORT size_t zchunk_append (zchunk_t *self, const void *data, size_t size); // Append user-supplied data to chunk, return resulting chunk size. If the // data would exceeded the available space, the chunk grows in size. CZMQ_EXPORT size_t zchunk_extend (zchunk_t *self, const void *data, size_t size); // Copy as much data from 'source' into the chunk as possible; returns the // new size of chunk. If all data from 'source' is used, returns exhausted // on the source chunk. Source can be consumed as many times as needed until // it is exhausted. If source was already exhausted, does not change chunk. CZMQ_EXPORT size_t zchunk_consume (zchunk_t *self, zchunk_t *source); // Returns true if the chunk was exhausted by consume methods, or if the // chunk has a size of zero. CZMQ_EXPORT bool zchunk_exhausted (zchunk_t *self); // Read chunk from an open file descriptor // Caller owns return value and must destroy it when done. CZMQ_EXPORT zchunk_t * zchunk_read (FILE *handle, size_t bytes); // Write chunk to an open file descriptor CZMQ_EXPORT int zchunk_write (zchunk_t *self, FILE *handle); // Try to slurp an entire file into a chunk. Will read up to maxsize of // the file. If maxsize is 0, will attempt to read the entire file and // fail with an assertion if that cannot fit into memory. Returns a new // chunk containing the file data, or NULL if the file could not be read. // Caller owns return value and must destroy it when done. CZMQ_EXPORT zchunk_t * zchunk_slurp (const char *filename, size_t maxsize); // Create copy of chunk, as new chunk object. Returns a fresh zchunk_t // object, or null if there was not enough heap memory. If chunk is null, // returns null. // Caller owns return value and must destroy it when done. CZMQ_EXPORT zchunk_t * zchunk_dup (zchunk_t *self); // Return chunk data encoded as printable hex string. Caller must free // string when finished with it. // Caller owns return value and must destroy it when done. CZMQ_EXPORT char * zchunk_strhex (zchunk_t *self); // Return chunk data copied into freshly allocated string // Caller must free string when finished with it. // Caller owns return value and must destroy it when done. CZMQ_EXPORT char * zchunk_strdup (zchunk_t *self); // Return TRUE if chunk body is equal to string, excluding terminator CZMQ_EXPORT bool zchunk_streq (zchunk_t *self, const char *string); // Transform zchunk into a zframe that can be sent in a message. // Caller owns return value and must destroy it when done. CZMQ_EXPORT zframe_t * zchunk_pack (zchunk_t *self); // Transform a zframe into a zchunk. // Caller owns return value and must destroy it when done. CZMQ_EXPORT zchunk_t * zchunk_unpack (zframe_t *frame); // Calculate SHA1 digest for chunk, using zdigest class. CZMQ_EXPORT const char * zchunk_digest (zchunk_t *self); // Dump chunk to FILE stream, for debugging and tracing. CZMQ_EXPORT void zchunk_fprint (zchunk_t *self, FILE *file); // Dump message to stderr, for debugging and tracing. // See zchunk_fprint for details CZMQ_EXPORT void zchunk_print (zchunk_t *self); // Probe the supplied object, and report if it looks like a zchunk_t. CZMQ_EXPORT bool zchunk_is (void *self); // Self test of this class. CZMQ_EXPORT void zchunk_test (bool verbose); #ifdef CZMQ_BUILD_DRAFT_API // Destroy an item typedef void (zchunk_destructor_fn) ( void **hint); // *** Draft method, for development use, may change without warning *** // Create a new chunk from memory. Take ownership of the memory and calling the destructor // on destroy. CZMQ_EXPORT zchunk_t * zchunk_frommem (void *data, size_t size, zchunk_destructor_fn destructor, void *hint); // *** Draft method, for development use, may change without warning *** // Transform zchunk into a zframe that can be sent in a message. // Take ownership of the chunk. // Caller owns return value and must destroy it when done. CZMQ_EXPORT zframe_t * zchunk_packx (zchunk_t **self_p); #endif // CZMQ_BUILD_DRAFT_API Please add '@interface' section in './../src/zchunk.c'. DESCRIPTION The zchunk class works with variable sized blobs. Not as efficient as Ze- roMQ's messages but they do less weirdness and so are easier to understand. The chunk class has methods to read and write chunks from disk. Please add @discuss section in ./../src/zchunk.c. EXAMPLE From zchunk_test method. zchunk_t *chunk = zchunk_new ("1234567890", 10); assert (chunk); assert (zchunk_size (chunk) == 10); assert (memcmp (zchunk_data (chunk), "1234567890", 10) == 0); zchunk_destroy (&chunk); chunk = zchunk_new (NULL, 10); assert (chunk); zchunk_append (chunk, "12345678", 8); zchunk_append (chunk, "90ABCDEF", 8); zchunk_append (chunk, "GHIJKLMN", 8); assert (memcmp (zchunk_data (chunk), "1234567890", 10) == 0); assert (zchunk_size (chunk) == 10); assert (zchunk_streq (chunk, "1234567890")); assert (streq (zchunk_digest (chunk), "01B307ACBA4F54F55AAFC33BB06BBBF6CA803E9A")); char *string = zchunk_strdup (chunk); assert (streq (string, "1234567890")); freen (string); string = zchunk_strhex (chunk); assert (streq (string, "31323334353637383930")); freen (string); zframe_t *frame = zchunk_pack (chunk); assert (frame); zchunk_t *chunk2 = zchunk_unpack (frame); assert (chunk2); assert (memcmp (zchunk_data (chunk2), "1234567890", 10) == 0); zframe_destroy (&frame); zchunk_destroy (&chunk2); zchunk_t *copy = zchunk_dup (chunk); assert (copy); assert (memcmp (zchunk_data (copy), "1234567890", 10) == 0); assert (zchunk_size (copy) == 10); zchunk_destroy (©); zchunk_destroy (&chunk); chunk = zchunk_new (NULL, 0); zchunk_extend (chunk, "12345678", 8); zchunk_extend (chunk, "90ABCDEF", 8); zchunk_extend (chunk, "GHIJKLMN", 8); assert (zchunk_size (chunk) == 24); assert (zchunk_streq (chunk, "1234567890ABCDEFGHIJKLMN")); zchunk_destroy (&chunk); copy = zchunk_new ("1234567890abcdefghij", 20); assert (copy); chunk = zchunk_new (NULL, 8); assert (chunk); zchunk_consume (chunk, copy); assert (!zchunk_exhausted (copy)); assert (memcmp (zchunk_data (chunk), "12345678", 8) == 0); zchunk_set (chunk, NULL, 0); zchunk_consume (chunk, copy); assert (!zchunk_exhausted (copy)); assert (memcmp (zchunk_data (chunk), "90abcdef", 8) == 0); zchunk_set (chunk, NULL, 0); zchunk_consume (chunk, copy); assert (zchunk_exhausted (copy)); assert (zchunk_size (chunk) == 4); assert (memcmp (zchunk_data (chunk), "ghij", 4) == 0); zchunk_destroy (©); zchunk_destroy (&chunk); char str[] = "hello"; chunk = zchunk_frommem (str, 5, mem_destructor, str); assert (chunk); zchunk_destroy (&chunk); // The destructor doesn't free the memory, only changing the strid, // so we can check if the destructor was invoked assert (streq (str, "world")); chunk = zchunk_new ("1234567890", 10); frame = zchunk_packx (&chunk); assert (frame); assert (chunk == NULL); chunk = zchunk_unpack (frame); assert (chunk); assert (memcmp (zchunk_data (chunk), "1234567890", 10) == 0); zframe_destroy (&frame); zchunk_destroy (&chunk); #if defined (__WINDOWS__) zsys_shutdown(); #endif AUTHORS The czmq manual was written by the authors in the AUTHORS file. RESOURCES Main web site: Report bugs to the email <zeromq-dev@lists.zeromq.org[1]> COPYRIGHT Copyright (c) the Contributors as noted in the AUTHORS file. This file is part of CZMQ, the high-level C binding for 0MQ: http://czmq.zeromq.org. This Source Code Form is subject to the terms of the Mozilla Public Li- cense, v. 2.0. If a copy of the MPL was not distributed with this file, You can obtain one at http://mozilla.org/MPL/2.0/. LICENSE included with the czmq distribution. NOTES 1. zeromq-dev@lists.zeromq.org mailto:zeromq-dev@lists.zeromq.org CZMQ 4.2.1 08/27/2026 ZCHUNK(3)
NAME | SYNOPSIS | DESCRIPTION | EXAMPLE | AUTHORS | RESOURCES | COPYRIGHT | NOTES
Want to link to this manual page? Use this URL:
<https://man.freebsd.org/cgi/man.cgi?query=zchunk&sektion=3&manpath=FreeBSD+Ports+15.1.quarterly>