diff options
Diffstat (limited to 'man/man3')
| -rw-r--r-- | man/man3/zmq_bind.3 | 36 | ||||
| -rw-r--r-- | man/man3/zmq_close.3 | 15 | ||||
| -rw-r--r-- | man/man3/zmq_connect.3 | 37 | ||||
| -rw-r--r-- | man/man3/zmq_flush.3 | 25 | ||||
| -rw-r--r-- | man/man3/zmq_init.3 | 3 | ||||
| -rw-r--r-- | man/man3/zmq_recv.3 | 40 | ||||
| -rw-r--r-- | man/man3/zmq_send.3 | 52 | ||||
| -rw-r--r-- | man/man3/zmq_setsockopt.3 | 103 | ||||
| -rw-r--r-- | man/man3/zmq_socket.3 | 56 | ||||
| -rw-r--r-- | man/man3/zmq_term.3 | 2 |
10 files changed, 367 insertions, 2 deletions
diff --git a/man/man3/zmq_bind.3 b/man/man3/zmq_bind.3 index 70f1df7..069b966 100644 --- a/man/man3/zmq_bind.3 +++ b/man/man3/zmq_bind.3 @@ -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> diff --git a/man/man3/zmq_close.3 b/man/man3/zmq_close.3 index c04f97a..cc49635 100644 --- a/man/man3/zmq_close.3 +++ b/man/man3/zmq_close.3 @@ -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> diff --git a/man/man3/zmq_connect.3 b/man/man3/zmq_connect.3 index c68101c..8f09e20 100644 --- a/man/man3/zmq_connect.3 +++ b/man/man3/zmq_connect.3 @@ -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> diff --git a/man/man3/zmq_flush.3 b/man/man3/zmq_flush.3 index f84c561..194cf6c 100644 --- a/man/man3/zmq_flush.3 +++ b/man/man3/zmq_flush.3 @@ -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> diff --git a/man/man3/zmq_init.3 b/man/man3/zmq_init.3 index 1e48fd7..317dbba 100644 --- a/man/man3/zmq_init.3 +++ b/man/man3/zmq_init.3 @@ -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> diff --git a/man/man3/zmq_recv.3 b/man/man3/zmq_recv.3 index 8308f79..d3cf2fd 100644 --- a/man/man3/zmq_recv.3 +++ b/man/man3/zmq_recv.3 @@ -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> diff --git a/man/man3/zmq_send.3 b/man/man3/zmq_send.3 index ff6e429..0ebbd0c 100644 --- a/man/man3/zmq_send.3 +++ b/man/man3/zmq_send.3 @@ -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> diff --git a/man/man3/zmq_setsockopt.3 b/man/man3/zmq_setsockopt.3 index da528cf..a79f879 100644 --- a/man/man3/zmq_setsockopt.3 +++ b/man/man3/zmq_setsockopt.3 @@ -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> diff --git a/man/man3/zmq_socket.3 b/man/man3/zmq_socket.3 index f404b6b..8b819b5 100644 --- a/man/man3/zmq_socket.3 +++ b/man/man3/zmq_socket.3 @@ -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> diff --git a/man/man3/zmq_term.3 b/man/man3/zmq_term.3 index 14d9da9..8d822b6 100644 --- a/man/man3/zmq_term.3 +++ b/man/man3/zmq_term.3 @@ -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> |