From 1aee86408d575d6572b071d7564da7f006d1757e Mon Sep 17 00:00:00 2001 From: Martin Lucina Date: Tue, 9 Mar 2010 18:47:31 +0100 Subject: Documentation rewrite --- doc/zmq_msg_init_data.txt | 51 ++++++++++++++++++++++++++++------------------- 1 file changed, 30 insertions(+), 21 deletions(-) (limited to 'doc/zmq_msg_init_data.txt') diff --git a/doc/zmq_msg_init_data.txt b/doc/zmq_msg_init_data.txt index 1ae6ce2..5adfeee 100644 --- a/doc/zmq_msg_init_data.txt +++ b/doc/zmq_msg_init_data.txt @@ -4,30 +4,35 @@ zmq_msg_init_data(3) NAME ---- -zmq_msg_init_data - initialises 0MQ message from the given data +zmq_msg_init_data - initialise 0MQ message from a supplied buffer SYNOPSIS -------- -'typedef void (zmq_free_fn) (void *data, void *hint);' -'int zmq_msg_init_data (zmq_msg_t *msg, void *data, size_t size, zmq_free_fn *ffn, void *hint);' +*typedef void (zmq_free_fn) (void '*data', void '*hint');* + +*int zmq_msg_init_data (zmq_msg_t '*msg', void '*data', size_t 'size', zmq_free_fn '*ffn', void '*hint');* DESCRIPTION ----------- -Initialise a message from a supplied buffer. Message isn't copied, -instead 0MQ infrastructure takes ownership of the buffer located at address -'data', 'size' bytes long. Deallocation function ('ffn') will be called once -the data are not needed anymore. When using a static constant buffer, 'ffn' may -be NULL to prevent subsequent deallocation. If needed, additional 'hint' can be -passed to the initialisation function. It's an opaque pointer that will be -later on passed to 'ffn' as a second argument. +The _zmq_msg_init_data()_ function shall initialise the message object +referenced by 'msg' to represent the content referenced by the buffer located +at address 'data', 'size' bytes long. No copy of 'data' shall be performed and +0MQ shall take ownership of the supplied buffer. + +If provided, the deallocation function 'ffn' shall be called once the data +buffer is no longer required by 0MQ, with the 'data' and 'hint' arguments +supplied to _zmq_msg_init_data()_. + +CAUTION: Never access 'zmq_msg_t' members directly, instead always use the +_zmq_msg_ family of functions. RETURN VALUE ------------ -In case of success the function returns zero. Otherwise it returns -1 and -sets 'errno' to the appropriate value. +The _zmq_msg_init_data()_ function shall return zero if successful. Otherwise +it shall return -1 and set 'errno' to one of the values defined below. ERRORS @@ -37,10 +42,14 @@ No errors are defined. EXAMPLE ------- +.Initialising a message from a supplied buffer ---- -void my_free (void *data, void *hint) {free (data);} +void my_free (void *data, void *hint) +{ + free (data); +} - ... + /* ... */ void *data = malloc (6); assert (data); @@ -48,20 +57,20 @@ memcpy (data, "ABCDEF", 6); zmq_msg_t msg; rc = zmq_msg_init_data (&msg, data, 6, my_free, NULL); assert (rc == 0); -rc = zmq_send (s, &msg, 0); -assert (rc == 0); ---- SEE ALSO -------- -linkzmq:zmq_msg_close[3] -linkzmq:zmq_msg_init[3] linkzmq:zmq_msg_init_size[3] +linkzmq:zmq_msg_init[3] +linkzmq:zmq_msg_close[3] linkzmq:zmq_msg_data[3] linkzmq:zmq_msg_size[3] +linkzmq:zmq[7] -AUTHOR ------- -Martin Sustrik +AUTHORS +------- +The 0MQ documentation was written by Martin Sustrik and +Martin Lucina . -- cgit v1.2.3