267 lines
9.3 KiB
267 lines
9.3 KiB
6 years ago
|
'\" 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 (©);
|
||
|
|
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);
|
||
|
|
.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
|