ZCHUNK(3)

📦
version 4.2.1 · 7 versions
, in fedora 44, ubuntu resolute, ubuntu stonking

💖 zchunk(3) — the cute little memory chunk class 💖

okay bestie, welcome to ZCHUNK(3), straight out of the CZMQ Manual. this is the page for zchunk, and by the end of it you're gonna be handling variable-sized blobs like it's nothing. slay. 🫶

✨ NAME ✨

zchunk — Class for work with memory chunks

like. it's a chunk. of memory. that's the whole vibe. 💅

🌸 SYNOPSIS 🌸

okay so first things first, the class itself has ✨rules✨:

//  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.
📌 bestie, read that again. the stable methods? they're stable, fr fr — they only change in emergencies. but the draft methods? they can change whenever. to get them you need --enable-drafts. no cap.

🧚 making and unmaking chunks

//  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);

so like, zchunk_new is the birth of a chunk. give it data and it copies that in. give it nothing and it hands you an empty chunk you can fill up later with zchunk_append. main character energy. ✨

//  Destroy a chunk
CZMQ_EXPORT void
    zchunk_destroy (zchunk_t **self_p);

zchunk_destroy — and it takes a pointer to a pointer (zchunk_t **self_p), so it can null out your variable for you. iconic behaviour, honestly. 🌈

🎀 sizing and peeking

//  Resizes chunk max_size as requested; chunk_cur size is set to zero
CZMQ_EXPORT void
    zchunk_resize (zchunk_t *self, size_t size);

zchunk_resize sets the chunk's max_size to whatever you asked for, and lowkey resets the current size to zero. noted. 📝

//  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);

three little peekers: zchunk_size (current size), zchunk_max_size (max size), and zchunk_data (the actual byte * data). 👑

🍓 setting and filling

//  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);

zchunk_set drops your data in, truncates if it's too large, and data is allowed to be null. it returns the actual size of the chunk. and zchunk_fill just fills it with one repeated octet — filler — size times. obsessed. 💖

🦋 appending vs extending (the plot twist)

//  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);

zchunk_append appends, returns the new size, and if your data would exceed the available space — it gets truncated. 😭

//  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);

zchunk_extend appends too, same return value, BUT if the data would exceed the available space the chunk grows instead. that's the difference bestie, don't mix them up!! 🚨

💀 consuming & being exhausted (the drama)

//  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);

zchunk_consume copies as much as it can from source into your chunk and returns the new size of the chunk. when source runs out of data it reports exhausted on the source. you can consume the source as many times as you need until it's exhausted — and if it was already exhausted, your chunk doesn't change. 🧊

zchunk_exhausted returns true if a consume method exhausted the chunk, or if the chunk's size is zero. vibe check: is it empty? is it drained? true. 💅

🎀 file I/O, the whole era

//  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);

zchunk_read pulls a chunk off an open file descriptor — you own the return value, so you must destroy it when you're done. 🫶 zchunk_write writes your chunk to an open file descriptor. returns an int.

//  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);

zchunk_slurp 😭 the name. it slurps a whole file into a chunk, reading up to maxsize. if maxsize is 0 it tries to read the entire file and fails with an assertion if that can't fit in memory. (yes bestie, an assertion. dramatic.) returns a fresh chunk with the file data, or NULL if the file couldn't be read. caller owns it → destroy it. 🌸

🌈 copying & stringifying

//  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);

zchunk_dup clones the chunk into a brand new zchunk_t. if heap memory ran out → null. if the chunk is null → also null. caller owns it, destroy it. ✨

//  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);

zchunk_strhex gives you the data as a printable hex string. zchunk_strdup gives you the data copied into a freshly allocated string. both: caller must free the string when finished, caller owns the return value and must destroy it when done. 🔥

//  Return TRUE if chunk body is equal to string, excluding terminator
CZMQ_EXPORT bool
    zchunk_streq (zchunk_t *self, const char *string);

zchunk_streq — TRUE if the chunk body equals string, excluding the terminator. 🍓

🧚 packing & unpacking

//  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);

zchunk_pack turns your chunk into a zframe you can send in a message. zchunk_unpack turns a zframe back into a chunk. both are caller-owns-it, destroy-when-done situations. 💜

👑 digest, dump, probe, test

//  Calculate SHA1 digest for chunk, using zdigest class.
CZMQ_EXPORT const char *
    zchunk_digest (zchunk_t *self);

zchunk_digest — SHA1 digest for the chunk, using the zdigest class. 🔐

//  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);

zchunk_fprint dumps the chunk to a FILE stream for debugging and tracing. zchunk_print dumps it to stderr for debugging and tracing — see zchunk_fprint for details. 🐛

//  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);

zchunk_is probes an object and reports whether it looks like a zchunk_t. zchunk_test runs the self test of this class (verbose is a bool). ⭐

💅 the draft section (handle with care)

#ifdef CZMQ_BUILD_DRAFT_API
// Destroy an item
typedef void (zchunk_destructor_fn) (
    void **hint);

a zchunk_destructor_fn — destroys an item, takes 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. zchunk_frommem creates a new chunk straight from memory, takes ownership of that memory, and calls the destructor when it's destroyed.
//  *** 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
🚨 also a DRAFT METHOD — development use only, may change without warning. zchunk_packx turns a chunk into a zframe, and takes ownership of the chunk. caller owns the return value and must destroy it when done.

and then, verbatim, from the source of truth:

Please add '@interface' section in './../src/zchunk.c'.

like. the docs are asking us to add a section. relatable. 🙈

💖 DESCRIPTION 💖

The zchunk class works with variable sized blobs. Not as efficient as ZeroMQ'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. 🦋

and also, once again, from the file itself:

Please add @discuss section in ./../src/zchunk.c.

the source code is begging for documentation and honestly? same. 😭

🌟 EXAMPLE 🌟

From zchunk_test method. this is the whole thing, character for character, because we do NOT play about the example:

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 (&copy);
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 (&copy);
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

see how zchunk_append on a 10-byte chunk eats all three appends and still only keeps "1234567890"? that's the truncation bestie. meanwhile zchunk_extend on a size-0 chunk goes all the way to 24. and zchunk_consume draining copy piece by piece until zchunk_exhausted (copy) is true?? cinema. 🎬

🫶 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 (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 License, 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

and that's the whole page bestie!! 💖 this was CZMQ 4.2.1, dated 01/16/2026 — go forth and chunk responsibly, you absolute icon. periodt. 🎀✨🦋

📦 where this page comes from