openpilot_comma/external/zmq/share/man/man3/zchunk.3

'\" t
.\"     Title: zchunk
.\"    Author: [see the "AUTHORS" section]
.\" Generator: DocBook XSL Stylesheets v1.76.1 <http://docbook.sf.net/>
.\"      Date: 12/31/2016
.\"    Manual: CZMQ Manual
.\"    Source: CZMQ 4.0.2
.\"  Language: English
.\"
.TH "ZCHUNK" "3" "12/31/2016" "CZMQ 4\&.0\&.2" "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 \- 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\&.
//  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);

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"));
free (string);
string = zchunk_strhex (chunk);
assert (streq (string, "31323334353637383930"));
free (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);
.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