mirror of
https://github.com/zeromq/libzmq.git
synced 2024-12-12 10:33:52 +01:00
more man pages filled in
This commit is contained in:
Martin Sustrik
parent
6602cce9af
commit
e90ada0d04
@ -180,7 +180,7 @@ ZMQ_EXPORT int zmq_term (void *context);
|
||||
|
||||
// Socket to send requests and receive replies. Requests are
|
||||
// load-balanced among all the peers. This socket type allows
|
||||
// only an alternated sequence of send's and recv's
|
||||
// only an alternated sequence of send's and recv's.
|
||||
#define ZMQ_REQ 3
|
||||
|
||||
// Socket to receive requests and send replies. This socket type allows
|
||||
|
||||
@ -4,9 +4,45 @@ zmq_bind \- binds the socket to the specified address
|
||||
.SH SYNOPSIS
|
||||
.B int zmq_bind (void *s, const char *addr);
|
||||
.SH DESCRIPTION
|
||||
The function binds socket
|
||||
.IR s to a particular transport. Actual semantics of the
|
||||
command depend on the underlying transport mechanism, however, in cases where
|
||||
peers connect in an asymetric manner,
|
||||
.IR zmq_bind
|
||||
should be called first,
|
||||
.IR zmq_connect
|
||||
afterwards. For actual formats of
|
||||
.IR addr
|
||||
parameter for different types of transport have a look at
|
||||
.IR zmq(7) .
|
||||
Note that single socket can be bound (and connected) to
|
||||
arbitrary number of peers using different transport mechanisms.
|
||||
.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 "\fBEPROTONOSUPPORT\fP"
|
||||
unsupported protocol.
|
||||
.IP "\fBENOCOMPATPROTO\fP"
|
||||
protocol is not compatible with the socket type.
|
||||
.IP "\fBEADDRINUSE\fP"
|
||||
the given address is already in use.
|
||||
.IP "\fBEADDRNOTAVAIL\fP"
|
||||
a nonexistent interface was requested or the requested address was not local.
|
||||
.SH EXAMPLE
|
||||
.nf
|
||||
void *s = zmq_socket (context, ZMQ_PUB);
|
||||
assert (s);
|
||||
int rc = zmq_bind (s, "inproc://my_publisher");
|
||||
assert (rc == 0);
|
||||
rc = zmq_bind (s, "tcp://eth0:5555");
|
||||
assert (rc == 0);
|
||||
.fi
|
||||
.SH SEE ALSO
|
||||
.BR zmq_connect (3)
|
||||
.BR zmq_socket (3)
|
||||
.BR zmq (7)
|
||||
.SH AUTHOR
|
||||
Martin Sustrik <sustrik at 250bpm dot com>
|
||||
|
||||
@ -4,9 +4,24 @@ zmq_close \- destroys 0MQ socket
|
||||
.SH SYNOPSIS
|
||||
.B int zmq_close (void *s);
|
||||
.SH DESCRIPTION
|
||||
Destroys 0MQ socket (one created using
|
||||
.IR zmq_socket
|
||||
function). All sockets have to be properly closed before the application
|
||||
terminates, otherwise memory leaks will occur.
|
||||
.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
|
||||
int rc = zmq_close (s);
|
||||
assert (rc == 0);
|
||||
.fi
|
||||
.SH SEE ALSO
|
||||
.BR zmq_socket (3)
|
||||
.BR zmq_term (3)
|
||||
.SH AUTHOR
|
||||
Martin Sustrik <sustrik at 250bpm dot com>
|
||||
|
||||
@ -1,12 +1,47 @@
|
||||
.TH zmq_connect 3 "" "(c)2007-2009 FastMQ Inc." "0MQ User Manuals"
|
||||
.SH NAME
|
||||
zmq_connect \- connects the socket to the specified address
|
||||
zmq_connect \- connect the socket to the specified peer
|
||||
.SH SYNOPSIS
|
||||
.B int zmq_connect (void *s, const char *addr);
|
||||
.SH DESCRIPTION
|
||||
The function connect socket
|
||||
.IR s to the peer identified by
|
||||
.IR addr .
|
||||
Actual semantics of the command depend on the underlying transport mechanism,
|
||||
however, in cases where peers connect in an asymetric manner,
|
||||
.IR zmq_bind
|
||||
should be called first,
|
||||
.IR zmq_connect
|
||||
afterwards. For actual formats of
|
||||
.IR addr
|
||||
parameter for different types of transport have a look at
|
||||
.IR zmq(7) .
|
||||
Note that single socket can be connected (and bound) to
|
||||
arbitrary number of peers using different transport mechanisms.
|
||||
.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 "\fBEPROTONOSUPPORT\fP"
|
||||
unsupported protocol.
|
||||
.IP "\fBENOCOMPATPROTO\fP"
|
||||
protocol is not compatible with the socket type.
|
||||
.IP "\fBECONNREFUSED\fP"
|
||||
no-one listening on the remote address.
|
||||
.SH EXAMPLE
|
||||
.nf
|
||||
void *s = zmq_socket (context, ZMQ_SUB);
|
||||
assert (s);
|
||||
int rc = zmq_connect (s, "inproc://my_publisher");
|
||||
assert (rc == 0);
|
||||
rc = zmq_connect (s, "tcp://server001:5555");
|
||||
assert (rc == 0);
|
||||
.fi
|
||||
.SH SEE ALSO
|
||||
.BR zmq_bind (3)
|
||||
.BR zmq_socket (3)
|
||||
.BR zmq (7)
|
||||
.SH AUTHOR
|
||||
Martin Sustrik <sustrik at 250bpm dot com>
|
||||
|
||||
@ -4,9 +4,34 @@ zmq_flush \- flushes pre-sent messages to the socket
|
||||
.SH SYNOPSIS
|
||||
.B int zmq_flush (void *s);
|
||||
.SH DESCRIPTION
|
||||
Flushes all the pre-sent messages - i.e. those that have been sent with
|
||||
ZMQ_NOFLUSH flag - to the socket. This functionality improves performance in
|
||||
cases where several messages are sent during a single business operation.
|
||||
It should not be used as a transaction - ACID properties are not guaranteed.
|
||||
Note that calling
|
||||
.IR zmq_send
|
||||
without ZMQ_NOFLUSH flag automatically flushes all previously pre-sent messages.
|
||||
.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 "\fBENOTSUP\fP"
|
||||
function isn't supported by particular socket type.
|
||||
.IP "\fBEFSM\fP"
|
||||
function cannot be called at the moment, because socket is not in the
|
||||
approprite state.
|
||||
.SH EXAMPLE
|
||||
.nf
|
||||
rc = zmq_send (s, &msg1, ZMQ_NOFLUSH);
|
||||
assert (rc == 0);
|
||||
rc = zmq_send (s, &msg2, ZMQ_NOFLUSH);
|
||||
assert (rc == 0);
|
||||
rc = zmq_flush (s);
|
||||
assert (rc == 0);
|
||||
.fi
|
||||
.SH SEE ALSO
|
||||
.BR zmq_send (3)
|
||||
.SH AUTHOR
|
||||
Martin Sustrik <sustrik at 250bpm dot com>
|
||||
|
||||
@ -25,7 +25,7 @@ Function returns context handle is successful. Otherwise it returns NULL and
|
||||
sets errno to one of the values below.
|
||||
.SH ERRORS
|
||||
.IP "\fBEINVAL\fP"
|
||||
- there's less than one application thread allocated, or number of I/O threads
|
||||
there's less than one application thread allocated, or number of I/O threads
|
||||
is negative.
|
||||
.SH EXAMPLE
|
||||
.nf
|
||||
@ -34,5 +34,6 @@ assert (ctx);
|
||||
.fi
|
||||
.SH SEE ALSO
|
||||
.BR zmq_term (3)
|
||||
.BR zmq_socket (3)
|
||||
.SH AUTHOR
|
||||
Martin Sustrik <sustrik at 250bpm dot com>
|
||||
|
||||
@ -4,9 +4,49 @@ zmq_recv \- retrieves a message from the socket
|
||||
.SH SYNOPSIS
|
||||
.B int zmq_recv (void *s, zmq_msg_t *msg, int flags);
|
||||
.SH DESCRIPTION
|
||||
Receive a message from the socket
|
||||
.IR s ,
|
||||
store it in
|
||||
.IR msg .
|
||||
Any content previously in
|
||||
.IR msg
|
||||
will be properly deallocated.
|
||||
.IR flags
|
||||
argument can be combination of the flags described below.
|
||||
|
||||
.IP "\fBZMQ_NOBLOCK\fP"
|
||||
The flag specifies that the operation should be performed in
|
||||
non-blocking mode. I.e. if it cannot be processed immediately,
|
||||
error should be returned with
|
||||
.IR errno
|
||||
set to EAGAIN.
|
||||
|
||||
.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 "\fBEAGAIN\fP"
|
||||
it's a non-blocking receive and there's no message available at the moment.
|
||||
.IP "\fBENOTSUP\fP"
|
||||
function isn't supported by particular socket type.
|
||||
.IP "\fBEFSM\fP"
|
||||
function cannot be called at the moment, because socket is not in the
|
||||
approprite state. This error may occur with sockets that switch between
|
||||
several states (e.g. ZMQ_REQ).
|
||||
.SH EXAMPLE
|
||||
.nf
|
||||
zmq_msg_t msg;
|
||||
int rc = zmq_msg_init (&msg);
|
||||
assert (rc == 0);
|
||||
rc = zmq_recv (s, &msg, 0);
|
||||
assert (rc == 0);
|
||||
.fi
|
||||
.SH SEE ALSO
|
||||
.BR zmq_send (3)
|
||||
.BR zmq_msg_init (3)
|
||||
.BR zmq_msg_data (3)
|
||||
.BR zmq_msg_size (3)
|
||||
.SH AUTHOR
|
||||
Martin Sustrik <sustrik at 250bpm dot com>
|
||||
|
||||
@ -4,9 +4,61 @@ zmq_send \- sends a message
|
||||
.SH SYNOPSIS
|
||||
.B int zmq_send (void *s, zmq_msg_t *msg, int flags);
|
||||
.SH DESCRIPTION
|
||||
Send the message
|
||||
.IR msg
|
||||
to the socket
|
||||
.IR s .
|
||||
.IR flags
|
||||
argument can be combination the flags described below.
|
||||
|
||||
.IP "\fBZMQ_NOBLOCK\fP"
|
||||
The flag specifies that the operation should be performed in
|
||||
non-blocking mode. I.e. if it cannot be processed immediately,
|
||||
error should be returned with
|
||||
.IR errno
|
||||
set to EAGAIN.
|
||||
|
||||
.IP "\fBZMQ_NOFLUSH\fP"
|
||||
The flag specifies that
|
||||
.IR zmq_send
|
||||
should not flush the message downstream immediately. Instead, it should batch
|
||||
ZMQ_NOFLUSH messages and send them downstream only once
|
||||
.IR zmq_flush
|
||||
is invoked. This is an optimisation for cases where several messages are sent
|
||||
in a single business transaction. However, the effect is measurable only in
|
||||
extremely high-perf scenarios (million messages a second or so).
|
||||
If that's not your case, use standard flushing send instead.
|
||||
|
||||
.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 "\fBEAGAIN\fP"
|
||||
it's a non-blocking send and message cannot be sent at the moment.
|
||||
.IP "\fBENOTSUP\fP"
|
||||
function isn't supported by particular socket type.
|
||||
.IP "\fBEFSM\fP"
|
||||
function cannot be called at the moment, because socket is not in the
|
||||
approprite state. This error may occur with sockets that switch between
|
||||
several states (e.g. ZMQ_REQ).
|
||||
.SH EXAMPLE
|
||||
.nf
|
||||
zmq_msg_t msg;
|
||||
int rc = zmq_msg_init_size (&msg, 6);
|
||||
assert (rc == 0);
|
||||
memset (zmq_msg_data (&msg), 'A', 6);
|
||||
rc = zmq_send (s, &msg, 0);
|
||||
assert (rc == 0);
|
||||
.fi
|
||||
.SH SEE ALSO
|
||||
.BR zmq_flush (3)
|
||||
.BR zmq_recv (3)
|
||||
.BR zmq_msg_init (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>
|
||||
|
||||
@ -4,9 +4,112 @@ zmq_setsockopt \- sets a specified option on a 0MQ socket
|
||||
.SH SYNOPSIS
|
||||
.B int zmq_setsockopt (void *s, int option, const void *optval, size_t optvallen);
|
||||
.SH DESCRIPTION
|
||||
Sets an option on the socket.
|
||||
.IR option
|
||||
argument specifies the option from the list below.
|
||||
.IR optval
|
||||
is a pointer to the value to set,
|
||||
.IR optvallen
|
||||
is the size of the value in bytes.
|
||||
|
||||
.IP "\fBZMQ_HWM\fP"
|
||||
High watermark for the message pipes associated with the socket. The water
|
||||
mark cannot be exceeded. If the messages don't fit into the pipe emergency
|
||||
mechanisms of the particular socket type are used (block, drop etc.) If HWM
|
||||
is set to zero, there are no limits for the content of the pipe.
|
||||
Type: int64_t Unit: bytes Default: 0
|
||||
|
||||
.IP "\fBZMQ_LWM\fP"
|
||||
Low watermark makes sense only if high watermark is defined (i.e. is non-zero).
|
||||
When the emergency state is reached when messages overflow the pipe, the
|
||||
emergency lasts till the size of the pipe decreases to low watermark.
|
||||
At that point normal state is resumed.
|
||||
Type: int64_t Unit: bytes Default: 0
|
||||
|
||||
.IP "\fBZMQ_SWAP\fP"
|
||||
Swap allows the pipe to exceed high watermark. However, the data are written
|
||||
to the disk rather than held in the memory. Until high watermark is
|
||||
exceeded there is no disk activity involved though. The value of the option
|
||||
defines maximal size of the swap file.
|
||||
Type: int64_t Unit: bytes Default: 0
|
||||
|
||||
.IP "\fBZMQ_AFFINITY\fP"
|
||||
Affinity defines which threads in the thread pool will be used to handle
|
||||
newly created sockets. This way you can dedicate some of the threads (CPUs)
|
||||
to a specific work. Value of 0 means no affinity. Work is distributed
|
||||
fairly among the threads in the thread pool. For non-zero values, the lowest
|
||||
bit corresponds to the thread 1, second lowest bit to the thread 2 etc.
|
||||
Thus, value of 3 means that from now on newly created sockets will handle
|
||||
I/O activity exclusively using threads no. 1 and 2.
|
||||
Type: int64_t Unit: N/A (bitmap) Default: 0
|
||||
|
||||
.IP "\fBZMQ_IDENTITY\fP"
|
||||
Identity of the socket. Identity is important when restarting applications.
|
||||
If the socket has no identity, each run of the application is completely
|
||||
separated from other runs. However, with identity application reconnects to
|
||||
existing infrastructure left by the previous run. Thus it may receive
|
||||
messages that were sent in the meantime, it shares pipe limits with the
|
||||
previous run etc.
|
||||
Type: string Unit: N/A Default: NULL
|
||||
|
||||
.IP "\fBZMQ_SUBSCRIBE\fP"
|
||||
Applicable only to ZMQ_SUB socket type. It establishes new message filter.
|
||||
When ZMQ_SUB socket is created all the incoming messages are filtered out.
|
||||
This option allows you to subscribe for all messages ("*"), messages with
|
||||
specific topic ("x.y.z") and/or messages with specific topic prefix
|
||||
("x.y.*"). Topic is one-byte-size-prefixed string located at
|
||||
the very beginning of the message. Multiple filters can be attached to
|
||||
a single 'sub' socket. In that case message passes if it matches at least
|
||||
one of the filters.
|
||||
Type: string Unit: N/A Default: N/A
|
||||
|
||||
.IP "\fBZMQ_UNSUBSCRIBE\fP"
|
||||
Applicable only to ZMQ_SUB socket type. Removes existing message filter.
|
||||
The filter specified must match the string passed to ZMQ_SUBSCRIBE options
|
||||
exactly. If there were several instances of the same filter created,
|
||||
this options removes only one of them, leaving the rest in place
|
||||
and functional.
|
||||
Type: string Unit: N/A Default: N/A
|
||||
|
||||
.IP "\fBZMQ_RATE\fP"
|
||||
This option applies only to sending side of multicast transports (pgm & udp).
|
||||
It specifies maximal outgoing data rate that an individual sender socket
|
||||
can send.
|
||||
Type: uint64_t Unit: kilobits/second Default: 100
|
||||
|
||||
.IP "\fBZMQ_RECOVERY_IVL\fP"
|
||||
This option applies only to multicast transports (pgm & udp). It specifies
|
||||
how long can the receiver socket survive when the sender is inaccessible.
|
||||
Keep in mind that large recovery intervals at high data rates result in
|
||||
very large recovery buffers, meaning that you can easily overload your box
|
||||
by setting say 1 minute recovery interval at 1Gb/s rate (requires
|
||||
7GB in-memory buffer).
|
||||
Type: uint64_t Unit: seconds Default: 10
|
||||
|
||||
.IP "\fBZMQ_MCAST_LOOP\fP"
|
||||
This option applies only to multicast transports (pgm & udp). Value of 1
|
||||
means that the mutlicast packets can be received on the box they were sent
|
||||
from. Setting the value to 0 disables the loopback functionality which
|
||||
can have negative impact on the performance. If possible, disable
|
||||
the loopback in production environments.
|
||||
Type: uint64_t Unit: N/A (boolean value) Default: 1
|
||||
|
||||
.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 "\fBEINVAL\fP"
|
||||
unknown option, a value with incorrect length or invalid value.
|
||||
.SH EXAMPLE
|
||||
.nf
|
||||
int rc = zmq_setsockopt (s, ZMQ_SUBSCRIBE, "*", 1);
|
||||
assert (rc == 0);
|
||||
.fi
|
||||
.SH SEE ALSO
|
||||
.BR zmq_socket (3)
|
||||
.BR zmq (7)
|
||||
|
||||
.SH AUTHOR
|
||||
Martin Sustrik <sustrik at 250bpm dot com>
|
||||
|
||||
@ -4,9 +4,65 @@ zmq_socket \- creates 0MQ socket
|
||||
.SH SYNOPSIS
|
||||
.B void *zmq_socket (void *context, int type);
|
||||
.SH DESCRIPTION
|
||||
Open a socket within the specified
|
||||
.IR context .
|
||||
To create a context, use
|
||||
.IR zmq_init
|
||||
function.
|
||||
.IR type
|
||||
argument can be one of the values defined below. Note that each socket is owned
|
||||
by exactly one thread (the one that it was created from) and should not be used
|
||||
from any other thread.
|
||||
|
||||
.IP "\fBZMQ_P2P\fP"
|
||||
Socket to communicate with a single peer. Allows for only a single connect or a
|
||||
single bind. There's no message routing or message filtering involved.
|
||||
|
||||
.IP "\fBZMQ_PUB\fP"
|
||||
Socket to distribute data. Recv fuction is not implemented for this socket
|
||||
type. Messages are distributed in fanout fashion to all the peers.
|
||||
|
||||
.IP "\fBZMQ_SUB\fP"
|
||||
Socket to subscribe for data. Send function is not implemented for this
|
||||
socket type. Initially, socket is subscribed for no messages. Use ZMQ_SUBSCRIBE
|
||||
option to specify which messages to subscribe for.
|
||||
|
||||
.IP "\fBZMQ_REQ\fP"
|
||||
Socket to send requests and receive replies. Requests are load-balanced among
|
||||
all the peers. This socket type allows only an alternated sequence of
|
||||
send's and recv's.
|
||||
|
||||
.IP "\fBZMQ_REP\fP"
|
||||
Socket to receive requests and send replies. This socket type allows
|
||||
only an alternated sequence of recv's and send's. Each send is routed to
|
||||
the peer that issued the last received request.
|
||||
|
||||
.SH RETURN VALUE
|
||||
Function returns socket handle is successful. Otherwise it returns NULL and
|
||||
sets errno to one of the values below.
|
||||
.SH ERRORS
|
||||
.IP "\fBEINVAL\fP"
|
||||
invalid socket type.
|
||||
.IP "\fBEMTHREAD\fP"
|
||||
the number of application threads allowed to own 0MQ sockets was exceeded. See
|
||||
.IR app_threads
|
||||
parameter to
|
||||
.IR zmq_init
|
||||
function.
|
||||
.SH EXAMPLE
|
||||
.nf
|
||||
void *s = zmq_socket (context, ZMQ_PUB);
|
||||
assert (s);
|
||||
int rc = zmq_bind (s, "tcp://192.168.0.1:5555");
|
||||
assert (rc == 0);
|
||||
.fi
|
||||
.SH SEE ALSO
|
||||
.BR zmq_init (3)
|
||||
.BR zmq_setsockopt (3)
|
||||
.BR zmq_bind (3)
|
||||
.BR zmq_connect (3)
|
||||
.BR zmq_send (3)
|
||||
.BR zmq_flush (3)
|
||||
.BR zmq_recv (3)
|
||||
.SH AUTHOR
|
||||
Martin Sustrik <sustrik at 250bpm dot com>
|
||||
|
||||
@ -19,5 +19,7 @@ int rc = zmq_term (context);
|
||||
assert (rc == 0);
|
||||
.fi
|
||||
.SH SEE ALSO
|
||||
.BR zmq_init (3)
|
||||
.BR zmq_close (3)
|
||||
.SH AUTHOR
|
||||
Martin Sustrik <sustrik at 250bpm dot com>
|
||||
|
||||
Loading…
Reference in New Issue
Block a user