mirror of
https://github.com/zeromq/libzmq.git
synced 2024-12-28 07:58:14 +08:00
the rest of man3 man pages filled in
This commit is contained in:
Martin Sustrik
parent
e90ada0d04
commit
5cd98bc575
@ -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>
|
||||
|
||||
@ -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>
|
||||
|
||||
@ -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>
|
||||
|
||||
@ -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>
|
||||
|
||||
@ -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>
|
||||
|
||||
@ -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>
|
||||
|
||||
@ -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>
|
||||
|
||||
@ -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>
|
||||
|
||||
@ -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>
|
||||
|
||||
Loading…
x
Reference in New Issue
Block a user