zchunk(3)

zchunk(3)

CZMQ Manual - CZMQ/2.2.1

Name

zchunk - work with memory chunks

Synopsis

//  Create new chunk
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
CZMQ_EXPORT size_t
    zchunk_append (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
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);

//  Create copy of chunk, as new chunk object. Returns a fresh zchunk_t
//  object, or NULL if there was not enough heap memory.
CZMQ_EXPORT zchunk_t *
    zchunk_dup (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);

//  Self test of this class
CZMQ_EXPORT int
    zchunk_test (bool verbose);

Description

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

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

 zchunk_t *copy = zchunk_dup (chunk);
 assert (memcmp (zchunk_data (copy), "1234567890", 10) == 0);
 assert (zchunk_size (copy) == 10);
 zchunk_destroy (&copy);
 zchunk_destroy (&chunk);

 copy = zchunk_new ("1234567890abcdefghij", 20);
 chunk = zchunk_new (NULL, 8);
 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);

See also

czmq(7)

Authors

The CZMQ manual was written by Pieter Hintjens<moc.xitami|hp#moc.xitami|hp>.

Resources

Main web site: http://czmq.zeromq.org/

Report bugs to the ØMQ development mailing list: <gro.qmorez.stsil|ved-qmorez#gro.qmorez.stsil|ved-qmorez>

Copyright

Copyright (c) 1991-2014 iMatix and Contributors. License LGPLv3+: GNU LGPL 3 or later <http://gnu.org/licenses/lgpl.html>. This is free software: you are free to change it and redistribute it. There is NO WARRANTY, to the extent permitted by law. For details see the files COPYING and COPYING.LESSER included with the CZMQ distribution.