diff options
| -rw-r--r-- | man/man3/zmq_msg_close.3 | 20 | ||||
| -rw-r--r-- | man/man3/zmq_msg_copy.3 | 31 | ||||
| -rw-r--r-- | man/man3/zmq_msg_data.3 | 15 | ||||
| -rw-r--r-- | man/man3/zmq_msg_init.3 | 21 | ||||
| -rw-r--r-- | man/man3/zmq_msg_init_data.3 | 33 | ||||
| -rw-r--r-- | man/man3/zmq_msg_init_size.3 | 32 | ||||
| -rw-r--r-- | man/man3/zmq_msg_move.3 | 26 | ||||
| -rw-r--r-- | man/man3/zmq_msg_size.3 | 18 | ||||
| -rw-r--r-- | man/man3/zmq_poll.3 | 53 |
9 files changed, 249 insertions, 0 deletions
diff --git a/man/man3/zmq_msg_close.3 b/man/man3/zmq_msg_close.3 index ee9d009..6613360 100644 --- a/man/man3/zmq_msg_close.3 +++ b/man/man3/zmq_msg_close.3 @@ -4,9 +4,29 @@ zmq_msg_close \- destroys 0MQ message .SH SYNOPSIS .B int zmq_msg_close (zmq_msg_t *msg); .SH DESCRIPTION +Deallocates message +.IR msg +including any associated buffers (unless the buffer is +shared with another message). Not calling this function can result in +memory leaks. .SH RETURN VALUE +In case of success the function returns zero. Otherwise it returns -1 and +sets +.IR errno +to the appropriate value. .SH ERRORS +No errors are defined. .SH EXAMPLE +.nf +zmq_msg_t msg; +rc = zmq_msg_init_size (&msg, 1000000); +assert (rc = 0); +rc = zmq_msg_close (&msg); +assert (rc = 0); +.fi .SH SEE ALSO +.BR zmq_msg_init (3) +.BR zmq_msg_init_size (3) +.BR zmq_msg_init_data (3) .SH AUTHOR Martin Sustrik <sustrik at 250bpm dot com> diff --git a/man/man3/zmq_msg_copy.3 b/man/man3/zmq_msg_copy.3 index 239203b..2f70400 100644 --- a/man/man3/zmq_msg_copy.3 +++ b/man/man3/zmq_msg_copy.3 @@ -4,9 +4,40 @@ zmq_msg_copy \- copies content of a message to another message .SH SYNOPSIS .B int zmq_msg_copy (zmq_msg_t *dest, zmq_msg_t *src); .SH DESCRIPTION +Copy the +.IR src +message to +.IR dest . +The original content of +.IR dest +is orderly deallocated. +Caution: The implementation may choose not to physically copy the data, rather +to share the buffer between two messages. Thus avoid modifying message data +after the message was copied. Doing so can modify multiple message instances. +If what you need is actual hard copy, allocate new message using +.IR zmq_msg_size +and copy the data using +.IR memcpy . .SH RETURN VALUE +In case of success the function returns zero. Otherwise it returns -1 and +sets +.IR errno +to the appropriate value. .SH ERRORS +No errors are defined. .SH EXAMPLE +.nf +zmq_msg_t dest; +rc = zmq_msg_init (&dest); +assert (rc == 0); +rc = zmq_msg_copy (&dest, &src); +assert (rc == 0); +.fi .SH SEE ALSO +.BR zmq_msg_move (3) +.BR zmq_msg_init (3) +.BR zmq_msg_init_size (3) +.BR zmq_msg_init_data (3) +.BR zmq_msg_close (3) .SH AUTHOR Martin Sustrik <sustrik at 250bpm dot com> diff --git a/man/man3/zmq_msg_data.3 b/man/man3/zmq_msg_data.3 index 647e9e9..9876378 100644 --- a/man/man3/zmq_msg_data.3 +++ b/man/man3/zmq_msg_data.3 @@ -4,9 +4,24 @@ zmq_msg_data \- retrieves pointer to the message content .SH SYNOPSIS .B void *zmq_msg_data (zmq_msg_t *msg); .SH DESCRIPTION +Returns pointer to message data. Always use this function to access the data, +never use +.IR zmq_msg_t +members directly. .SH RETURN VALUE +Pointer to the message data. .SH ERRORS +No errors are defined. .SH EXAMPLE +.nf +zmq_msg_t msg; +rc = zmq_msg_init_size (&msg, 100); +memset (zmq_msg_data (&msg), 0, 100); +.fi .SH SEE ALSO +.BR zmq_msg_init (3) +.BR zmq_msg_init_size (3) +.BR zmq_msg_init_data (3) +.BR zmq_msg_close (3) .SH AUTHOR Martin Sustrik <sustrik at 250bpm dot com> diff --git a/man/man3/zmq_msg_init.3 b/man/man3/zmq_msg_init.3 index 8b18207..a531fc1 100644 --- a/man/man3/zmq_msg_init.3 +++ b/man/man3/zmq_msg_init.3 @@ -4,9 +4,30 @@ zmq_msg_init \- initialises empty 0MQ message .SH SYNOPSIS .B int zmq_msg_init (zmq_msg_t *msg); .SH DESCRIPTION +Initialises 0MQ message zero bytes long. The function is most useful +to initialise a +.IR zmq_msg_t +structure before receiving a message. .SH RETURN VALUE +In case of success the function returns zero. Otherwise it returns -1 and +sets +.IR errno +to the appropriate value. .SH ERRORS +No errors are defined. .SH EXAMPLE +.nf +zmq_msg_t msg; +rc = zmq_msg_init (&msg); +assert (rc == 0); +rc = zmq_recv (s, &msg, 0); +assert (rc == 0); +.fi .SH SEE ALSO +.BR zmq_msg_close (3) +.BR zmq_msg_init_size (3) +.BR zmq_msg_init_data (3) +.BR zmq_msg_data (3) +.BR zmq_msg_size (3) .SH AUTHOR Martin Sustrik <sustrik at 250bpm dot com> diff --git a/man/man3/zmq_msg_init_data.3 b/man/man3/zmq_msg_init_data.3 index d00ed9c..a0b14c8 100644 --- a/man/man3/zmq_msg_init_data.3 +++ b/man/man3/zmq_msg_init_data.3 @@ -7,9 +7,42 @@ zmq_msg_init \- initialises 0MQ message from the given data .B int zmq_msg_init_data (zmq_msg_t *msg, void *data, size_t size, zmq_free_fn *ffn); .fi .SH DESCRIPTION +Initialise a message from a supplied buffer. Message isn't copied, +instead 0MQ infrastructure takes ownership of the buffer located at address +.IR data , +.IR size +bytes long. +Deallocation function ( +.IR ffn +) will be called once the data are not needed anymore. Note that deallocation +function prototype is designed so that it complies with standard C +.IR free +function. When using a static constant buffer, +.IR ffn +may be NULL to prevent subsequent deallocation. .SH RETURN VALUE +In case of success the function returns zero. Otherwise it returns -1 and +sets +.IR errno +to the appropriate value. .SH ERRORS +No errors are defined. .SH EXAMPLE +.nf +void *data = malloc (6); +assert (data); +memcpy (data, "ABCDEF", 6); +zmq_msg_t msg; +rc = zmq_msg_init_data (&msg, data, 6, free); +assert (rc == 0); +rc = zmq_send (s, &msg, 0); +assert (rc == 0); +.fi .SH SEE ALSO +.BR zmq_msg_close (3) +.BR zmq_msg_init (3) +.BR zmq_msg_init_size (3) +.BR zmq_msg_data (3) +.BR zmq_msg_size (3) .SH AUTHOR Martin Sustrik <sustrik at 250bpm dot com> diff --git a/man/man3/zmq_msg_init_size.3 b/man/man3/zmq_msg_init_size.3 index b1baa75..ce1ec94 100644 --- a/man/man3/zmq_msg_init_size.3 +++ b/man/man3/zmq_msg_init_size.3 @@ -4,9 +4,41 @@ zmq_msg_init \- initialises 0MQ message of a specified size .SH SYNOPSIS .B int zmq_msg_init_size (zmq_msg_t *msg, size_t size); .SH DESCRIPTION +Initialises 0MQ message +.IR size +bytes long. The implementation chooses whether it is more efficient to store +message content on the stack (small messages) or on the heap (large messages). +Therefore, never access message data directly via +.IR zmq_msg_t +members, rather use +.IR zmq_msg_data +and +.IR zmq_msg_size +functions to get message data and size. Note that the message data are not +nullified to avoid the associated performance impact. Thus you +should expect your message to contain bogus data after this call. .SH RETURN VALUE +In case of success the function returns zero. Otherwise it returns -1 and +sets +.IR errno +to the appropriate value. .SH ERRORS +.IP "\fBENOMEM\fP" +memory to hold the message cannot be allocated. .SH EXAMPLE +.nf +zmq_msg_t msg; +rc = zmq_msg_init_size (&msg, 6); +assert (rc == 0); +memcpy (zmq_msg_data (&msg), "ABCDEF", 6); +rc = zmq_send (s, &msg, 0); +assert (rc == 0); +.fi .SH SEE ALSO +.BR zmq_msg_close (3) +.BR zmq_msg_init (3) +.BR zmq_msg_init_data (3) +.BR zmq_msg_data (3) +.BR zmq_msg_size (3) .SH AUTHOR Martin Sustrik <sustrik at 250bpm dot com> diff --git a/man/man3/zmq_msg_move.3 b/man/man3/zmq_msg_move.3 index 0daf2f7..810e105 100644 --- a/man/man3/zmq_msg_move.3 +++ b/man/man3/zmq_msg_move.3 @@ -4,9 +4,35 @@ zmq_msg_move \- moves content of a message to another message .SH SYNOPSIS .B int zmq_msg_move (zmq_msg_t *dest, zmq_msg_t *src); .SH DESCRIPTION +Move the content of the message from +.IR src +to +.IR dest . +The content isn't copied, just moved. +.IR src +becomes an empty message after the call. Original content of +.IR dest +message is deallocated. .SH RETURN VALUE +In case of success the function returns zero. Otherwise it returns -1 and +sets +.IR errno +to the appropriate value. .SH ERRORS +No errors are defined. .SH EXAMPLE +.nf +zmq_msg_t dest; +rc = zmq_msg_init (&dest); +assert (rc == 0); +rc = zmq_msg_move (&dest, &src); +assert (rc == 0); +.fi .SH SEE ALSO +.BR zmq_msg_copy (3) +.BR zmq_msg_init (3) +.BR zmq_msg_init_size (3) +.BR zmq_msg_init_data (3) +.BR zmq_msg_close (3) .SH AUTHOR Martin Sustrik <sustrik at 250bpm dot com> diff --git a/man/man3/zmq_msg_size.3 b/man/man3/zmq_msg_size.3 index d8bbc53..b51d582 100644 --- a/man/man3/zmq_msg_size.3 +++ b/man/man3/zmq_msg_size.3 @@ -4,9 +4,27 @@ zmq_msg_size \- retrieves size of the message content .SH SYNOPSIS .B size_t zmq_msg_size (zmq_msg_t *msg); .SH DESCRIPTION +Returns size of the message data. Always use this function to get the size, +never use +.IR zmq_msg_t +members directly. .SH RETURN VALUE +Size of the message data (bytes). .SH ERRORS +No errors are defined. .SH EXAMPLE +.nf +zmq_msg_t msg; +rc = zmq_msg_init (&msg); +assert (rc == 0); +rc = zmq_recv (s, &msg, 0); +assert (rc == 0); +size_t msg_size = zmq_msg_size (&msg); +.fi .SH SEE ALSO +.BR zmq_msg_init (3) +.BR zmq_msg_init_size (3) +.BR zmq_msg_init_data (3) +.BR zmq_msg_close (3) .SH AUTHOR Martin Sustrik <sustrik at 250bpm dot com> diff --git a/man/man3/zmq_poll.3 b/man/man3/zmq_poll.3 index d821e9f..5ce5055 100644 --- a/man/man3/zmq_poll.3 +++ b/man/man3/zmq_poll.3 @@ -4,9 +4,62 @@ zmq_poll \- polls for events on a set of 0MQ and POSIX sockets .SH SYNOPSIS .B int zmq_poll (zmq_pollitem_t *items, int nitems); .SH DESCRIPTION +Waits for the events specified by +.IR items +parameter. Number of items in the array is determined by +.IR nitems +argument. Each item in the array looks like this: + +.nf +typedef struct +{ + void *socket; + int fd; + short events; + short revents; +} zmq_pollitem_t; +.fi + +0MQ socket to poll on is specified by +.IR socket . +In case you want to poll on standard POSIX socket, set +.IR socket +to NULL and fill the POSIX file descriptor to +.IR fd . +.IR events +specifies which events to wait for. It's a combination of the values below. +Once the call exits, +.IR revent +will be filled with events that have actually occured on the socket. The field +will contain a combination of the following values. + +.IP "\fBZMQ_POLLIN\fP" +poll for incoming messages. +.IP "\fBZMQ_POLLOUT\fP" +wait while message can be set socket. Poll will return if a message of at least +one byte can be written to the socket. However, there is no guarantee that +arbitrarily large message can be sent. + .SH RETURN VALUE +Function returns number of items signaled or -1 in the case of error. .SH ERRORS +.IP "\fBEFAULT\fP" +there's a 0MQ socket in the pollset belonging to a different application thread. +.IP "\fBENOTSUP\fP" +0MQ context was initialised without ZMQ_POLL flag. I/O multiplexing is disabled. .SH EXAMPLE +.nf +zmq_pollitem_t items [2]; +items [0].socket = s; +items [0].events = POLLIN; +items [1].socket = NULL; +items [1].fd = my_fd; +items [1].events = POLLIN; + +int rc = zmq_poll (items, 2); +assert (rc != -1); +.fi .SH SEE ALSO +.BR zmq_socket (3) .SH AUTHOR Martin Sustrik <sustrik at 250bpm dot com> |