'\" t .\" Title: zchunk .\" Author: [see the "AUTHORS" section] .\" Generator: DocBook XSL Stylesheets vsnapshot .\" Date: 03/02/2024 .\" Manual: CZMQ Manual .\" Source: CZMQ 4.2.1 .\" Language: English .\" .TH "ZCHUNK" "3" "03/02/2024" "CZMQ 4\&.2\&.1" "CZMQ Manual" .\" ----------------------------------------------------------------- .\" * Define some portability stuff .\" ----------------------------------------------------------------- .\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .\" http://bugs.debian.org/507673 .\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html .\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .ie \n(.g .ds Aq \(aq .el .ds Aq ' .\" ----------------------------------------------------------------- .\" * set default formatting .\" ----------------------------------------------------------------- .\" disable hyphenation .nh .\" disable justification (adjust text to left margin only) .ad l .\" ----------------------------------------------------------------- .\" * MAIN CONTENT STARTS HERE * .\" ----------------------------------------------------------------- .SH "NAME" zchunk \- Class for work with memory chunks .SH "SYNOPSIS" .sp .nf // 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 \*(Aqsource\*(Aq into the chunk as possible; returns the // new size of chunk\&. If all data from \*(Aqsource\*(Aq 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 \*(Aq@interface\*(Aq section in \*(Aq\&./\&.\&./src/zchunk\&.c\*(Aq\&. .fi .SH "DESCRIPTION" .sp The zchunk class works with variable sized blobs\&. Not as efficient as ZeroMQ\(cqs messages but they do less weirdness and so are easier to understand\&. The chunk class has methods to read and write chunks from disk\&. .sp Please add \fI@discuss\fR section in \fI\&./\&.\&./src/zchunk\&.c\fR\&. .SH "EXAMPLE" .PP \fBFrom zchunk_test method\fR. .sp .if n \{\ .RS 4 .\} .nf 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\*(Aqt 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 .fi .if n \{\ .RE .\} .sp .SH "AUTHORS" .sp The czmq manual was written by the authors in the AUTHORS file\&. .SH "RESOURCES" .sp Main web site: \m[blue]\fB\%\fR\m[] .sp Report bugs to the email <\m[blue]\fBzeromq\-dev@lists\&.zeromq\&.org\fR\m[]\&\s-2\u[1]\d\s+2> .SH "COPYRIGHT" .sp 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\&. .SH "NOTES" .IP " 1." 4 zeromq-dev@lists.zeromq.org .RS 4 \%mailto:zeromq-dev@lists.zeromq.org .RE