zmq_msg_init_data.txt 2.14 KB
Newer Older
1 2 3 4 5 6
zmq_msg_init_data(3)
====================


NAME
----
Martin Lucina's avatar
Martin Lucina committed
7
zmq_msg_init_data - initialise 0MQ message from a supplied buffer
8 9 10 11


SYNOPSIS
--------
Martin Lucina's avatar
Martin Lucina committed
12 13 14
*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');*
15 16 17 18


DESCRIPTION
-----------
Martin Lucina's avatar
Martin Lucina committed
19 20 21 22 23 24 25 26 27 28 29
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.
30

31 32 33
CAUTION: The deallocation function 'ffn' needs to be thread-safe, since it
will be called from an arbitrary thread.

34 35 36 37
CAUTION: If the deallocation function is not provided, the allocated memory
will not be freed, and this may cause a memory leak.


38
CAUTION: The functions _zmq_msg_init()_, _zmq_msg_init_data()_ and
39
_zmq_msg_init_size()_ are mutually exclusive. Never initialise the same
40 41
'zmq_msg_t' twice.

42 43 44

RETURN VALUE
------------
Martin Lucina's avatar
Martin Lucina committed
45
The _zmq_msg_init_data()_ function shall return zero if successful. Otherwise
Martin Lucina's avatar
Martin Lucina committed
46
it shall return `-1` and set 'errno' to one of the values defined below.
47 48 49 50


ERRORS
------
51 52 53
*ENOMEM*::
Insufficient storage space is available.

54 55 56 57


EXAMPLE
-------
Martin Lucina's avatar
Martin Lucina committed
58
.Initialising a message from a supplied buffer
59
----
Martin Lucina's avatar
Martin Lucina committed
60 61 62 63
void my_free (void *data, void *hint) 
{
    free (data);
}
64

Martin Lucina's avatar
Martin Lucina committed
65
    /*  ...  */
66 67 68 69 70 71 72 73 74 75 76 77 78

void *data = malloc (6);
assert (data);
memcpy (data, "ABCDEF", 6);
zmq_msg_t msg;
rc = zmq_msg_init_data (&msg, data, 6, my_free, NULL);
assert (rc == 0);
----


SEE ALSO
--------
linkzmq:zmq_msg_init_size[3]
Martin Lucina's avatar
Martin Lucina committed
79 80
linkzmq:zmq_msg_init[3]
linkzmq:zmq_msg_close[3]
81 82
linkzmq:zmq_msg_data[3]
linkzmq:zmq_msg_size[3]
Martin Lucina's avatar
Martin Lucina committed
83
linkzmq:zmq[7]
84 85


86 87
AUTHORS
-------
88 89
This page was written by the 0MQ community. To make a change please
read the 0MQ Contribution Policy at <http://www.zeromq.org/docs:contributing>.