summaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorMartin Lucina <mato@kotelna.sk>2010-12-01 10:57:37 +0100
committerMartin Sustrik <sustrik@250bpm.com>2010-12-01 10:57:37 +0100
commitb70d628fad5ab97d24473b83fd18997b4e87477d (patch)
tree71d2556da535ece2407db7f983a30cf7a04419dc
parent5bb0a339be31064900257e04e2ffd32e80911d63 (diff)
Documentation updates for 2.1
- Clarify ZMQ_LINGER, zmq_close (), zmq_term () relationship - New socket options - Clarify thread safety of sockets and migration between threads - Other minor and spelling fixes Signed-off-by: Martin Lucina <mato@kotelna.sk>
-rw-r--r--doc/zmq.txt12
-rw-r--r--doc/zmq_close.txt12
-rw-r--r--doc/zmq_errno.txt2
-rw-r--r--doc/zmq_getsockopt.txt116
-rw-r--r--doc/zmq_pgm.txt6
-rw-r--r--doc/zmq_poll.txt11
-rw-r--r--doc/zmq_setsockopt.txt67
-rw-r--r--doc/zmq_socket.txt24
-rw-r--r--doc/zmq_tcp.txt6
-rw-r--r--doc/zmq_term.txt27
-rw-r--r--doc/zmq_version.txt2
11 files changed, 186 insertions, 99 deletions
diff --git a/doc/zmq.txt b/doc/zmq.txt
index 06658c9..0c29a74 100644
--- a/doc/zmq.txt
+++ b/doc/zmq.txt
@@ -44,9 +44,15 @@ Terminate 0MQ context::
Thread safety
^^^^^^^^^^^^^
A 0MQ 'context' is thread safe and may be shared among as many application
-threads as necessary, without any additional locking required on the part of the
-caller. Each 0MQ socket belonging to a particular 'context' may only be used
-by *the thread that created it* using _zmq_socket()_.
+threads as necessary, without any additional locking required on the part of
+the caller.
+
+Individual 0MQ 'sockets' are _not_ thread safe except in the case where full
+memory barriers are issued when migrating a socket from one thread to another.
+In practice this means applications can create a socket in one thread with
+_zmq_socket()_ and then pass it to a _newly created_ thread as part of thread
+initialization, for example via a structure passed as an argument to
+_pthread_create()_.
Multiple contexts
diff --git a/doc/zmq_close.txt b/doc/zmq_close.txt
index 1200fb7..fe3bde5 100644
--- a/doc/zmq_close.txt
+++ b/doc/zmq_close.txt
@@ -16,10 +16,14 @@ DESCRIPTION
-----------
The _zmq_close()_ function shall destroy the socket referenced by the 'socket'
argument. Any outstanding messages physically received from the network but not
-yet received by the application with _zmq_recv()_ shall also be dropped. As for
-the messages sent with _zmq_send()_ but not yet passed to the network, 0MQ
-will try to send them in the background after _zmq_close()_ returns. Time spent
-attempting can be set using _ZMQ_LINGER_ socket option.
+yet received by the application with _zmq_recv()_ shall be discarded. The
+behaviour for discarding messages sent by the application with _zmq_send()_ but
+not yet physically transferred to the network depends on the value of the
+_ZMQ_LINGER_ socket option for the specified 'socket'.
+
+NOTE: The default setting of _ZMQ_LINGER_ does not discard unsent messages;
+this behaviour may cause the application to block when calling _zmq_term()_.
+For details refer to linkzmq:zmq_setsockopt[3] and linkzmq:zmq_term[3].
RETURN VALUE
diff --git a/doc/zmq_errno.txt b/doc/zmq_errno.txt
index 61939a5..6bee0f1 100644
--- a/doc/zmq_errno.txt
+++ b/doc/zmq_errno.txt
@@ -20,7 +20,7 @@ the calling thread.
The _zmq_errno()_ function is provided to assist users on non-POSIX systems who
are experiencing issues with retrieving the correct value of 'errno' directly.
Specifically, users on Win32 systems whose application is using a different C
-runtime library from the C runtime library in use by 0MQ will need to use
+run-time library from the C run-time library in use by 0MQ will need to use
_zmq_errno()_ for correct operation.
IMPORTANT: Users not experiencing issues with retrieving the correct value of
diff --git a/doc/zmq_getsockopt.txt b/doc/zmq_getsockopt.txt
index 40a99b1..7f73e1c 100644
--- a/doc/zmq_getsockopt.txt
+++ b/doc/zmq_getsockopt.txt
@@ -26,8 +26,8 @@ value stored in the buffer.
The following options can be retrieved with the _zmq_getsockopt()_ function:
-ZMQ_TYPE: Retrieve socket type.
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+ZMQ_TYPE: Retrieve socket type
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
The 'ZMQ_TYPE' option shall retrieve the socket type for the specified
'socket'. The socket type is specified at socket creation time and
cannot be modified afterwards.
@@ -167,13 +167,13 @@ Default value:: 10
Applicable socket types:: all, when using multicast transports
-ZMQ_MCAST_LOOP: Control multicast loopback
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+ZMQ_MCAST_LOOP: Control multicast loop-back
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
The 'ZMQ_MCAST_LOOP' option controls whether data sent via multicast
-transports can also be received by the sending host via loopback. A value of
-zero indicates that the loopback functionality is disabled, while the default
-value of 1 indicates that the loopback functionality is enabled. Leaving
-multicast loopback enabled when it is not required can have a negative impact
+transports can also be received by the sending host via loop-back. A value of
+zero indicates that the loop-back functionality is disabled, while the default
+value of 1 indicates that the loop-back functionality is enabled. Leaving
+multicast loop-back enabled when it is not required can have a negative impact
on performance. Where possible, disable 'ZMQ_MCAST_LOOP' in production
environments.
@@ -214,53 +214,80 @@ Applicable socket types:: all
ZMQ_LINGER: Retrieve linger period for socket shutdown
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-The 'ZMQ_LINGER' option shall retrieve the period for pending outbound
-messages to linger in memory after closing the socket. Value of -1 means
-infinite. Pending messages will be kept until they are fully transferred to
-the peer. Value of 0 means that all the pending messages are dropped immediately
-when socket is closed. Positive value means number of milliseconds to keep
-trying to send the pending messages before discarding them.
+The 'ZMQ_LINGER' option shall retrieve the linger period for the specified
+'socket'. The linger period determines how long pending messages which have
+yet to be sent to a peer shall linger in memory after a socket is closed with
+linkzmq:zmq_close[3], and further affects the termination of the socket's
+context with linkzmq:zmq_term[3]. The following outlines the different
+behaviours:
+
+* The default value of '-1' specifies an infinite linger period. Pending
+ messages shall not be discarded after a call to _zmq_close()_; attempting to
+ terminate the socket's context with _zmq_term()_ shall block until all
+ pending messages have been sent to a peer.
+
+* The value of '0' specifies no linger period. Pending messages shall be
+ discarded immediately when the socket is closed with _zmq_close()_.
+
+* Positive values specify an upper bound for the linger period in milliseconds.
+ Pending messages shall not be discarded after a call to _zmq_close()_;
+ attempting to terminate the socket's context with _zmq_term()_ shall block
+ until either all pending messages have been sent to a peer, or the linger
+ period expires, after which any pending messages shall be discarded.
[horizontal]
Option value type:: int
Option value unit:: milliseconds
-Default value:: -1
+Default value:: -1 (infinite)
Applicable socket types:: all
-ZMQ_RECONNECT_IVL: Retrieve reconnect period for connection-based transports
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-The 'ZMQ_RECONNECT_IVL' option shall retrieve the period indicating how long it
-takes for a disconnected underlying connection to attempt to reconnect.
+ZMQ_RECONNECT_IVL: Retrieve reconnection interval
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+The 'ZMQ_RECONNECT_IVL' option shall retrieve the reconnection interval for the
+specified 'socket'. The reconnection interval is the maximum period 0MQ shall
+wait between attempts to reconnect disconnected peers when using
+connection-oriented transports.
+
+NOTE: The reconnection interval may be randomized by 0MQ to prevent
+reconnection storms in topologies with a large number of peers per socket.
[horizontal]
Option value type:: int
Option value unit:: milliseconds
Default value:: 100
-Applicable socket types:: all
+Applicable socket types:: all, only for connection-oriented transports
-ZMQ_BACKLOG: Retrieve maximum length of the queue of pending connections
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-The 'ZMQ_BACKLOG' option shall retrieve maximum size of the
-pending connection backlog for connection-based transports. For details
-refer to your operating system documentation for the 'listen' function.
+ZMQ_BACKLOG: Retrieve maximum length of the queue of outstanding connections
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+The 'ZMQ_BACKLOG' option shall retrieve the maximum length of the queue of
+outstanding peer connections for the specified 'socket'; this only applies to
+connection-oriented transports. For details refer to your operating system
+documentation for the 'listen' function.
[horizontal]
Option value type:: int
Option value unit:: connections
Default value:: 100
-Applicable socket types:: all
+Applicable socket types:: all, only for connection-oriented transports
ZMQ_FD: Retrieve file descriptor associated with the socket
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-The 'ZMQ_FD' option shall retrieve file descriptor associated with the 0MQ
-socket. The descriptor can be used to integrate 0MQ socket into an existing
-event loop. It should never be used for anything else than polling -- such as
-reading or writing. The descriptor signals edge-triggered IN event when
-something has happened within the 0MQ socket. It does not necessarily mean that
-the messages can be read or written. Check ZMQ_EVENTS option to find out whether
-the 0MQ socket is readable or writeable.
+The 'ZMQ_FD' option shall retrieve the file descriptor associated with the
+specified 'socket'. The returned file descriptor can be used to integrate the
+socket into an existing event loop; the 0MQ library shall signal any pending
+events on the socket in an _edge-triggered_ fashion by making the file
+descriptor become ready for reading.
+
+NOTE: The ability to read from the returned file descriptor does not
+necessarily indicate that messages are available to be read from, or can be
+written to, the underlying socket; applications must retrieve the actual event
+state with a subsequent retrieval of the 'ZMQ_EVENTS' option.
+
+CAUTION: The returned file descriptor is intended for use with a 'poll' or
+similar system call only. Applications must never attempt to read or write data
+to it directly.
[horizontal]
Option value type:: int on POSIX systems, SOCKET on Windows
@@ -269,11 +296,24 @@ Default value:: N/A
Applicable socket types:: all
-ZMQ_EVENTS: Check whether socket is readable and/or writeable
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-The 'ZMQ_EVENTS' option shall retrieve event flags for the specified socket.
-If a message can be read from the socket ZMQ_POLLIN flag is set. If message can
-be written to the socket ZMQ_POLLOUT flag is set.
+ZMQ_EVENTS: Retrieve socket event state
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+The 'ZMQ_EVENTS' option shall retrieve the event state for the specified
+'socket'. The returned value is a bit mask constructed by OR'ing a combination
+of the following event flags:
+
+*ZMQ_POLLIN*::
+Indicates that at least one message may be received from the specified socket
+without blocking.
+
+*ZMQ_POLLOUT*::
+Indicates that at least one message may be sent to the specified socket without
+blocking.
+
+The combination of a file descriptor returned by the 'ZMQ_FD' option being
+ready for reading but no actual events returned by a subsequent retrieval of
+the 'ZMQ_EVENTS' option is valid; applications should simply ignore this case
+and restart their polling operation/event loop.
[horizontal]
Option value type:: uint32_t
diff --git a/doc/zmq_pgm.txt b/doc/zmq_pgm.txt
index 4017db2..d9bce5a 100644
--- a/doc/zmq_pgm.txt
+++ b/doc/zmq_pgm.txt
@@ -24,7 +24,7 @@ The 'pgm' and 'epgm' transports can only be used with the 'ZMQ_PUB' and
'ZMQ_SUB' socket types.
Further, PGM sockets are rate limited by default and incur a performance
-penalty when used over a loopback interface. For details, refer to the
+penalty when used over a loop-back interface. For details, refer to the
'ZMQ_RATE', 'ZMQ_RECOVERY_IVL' and 'ZMQ_MCAST_LOOP' options documented in
linkzmq:zmq_setsockopt[3].
@@ -69,7 +69,7 @@ representation.
WIRE FORMAT
-----------
-Consecutive PGM datagrams are interpreted by 0MQ as a single continous stream
+Consecutive PGM datagrams are interpreted by 0MQ as a single continuous stream
of data where 0MQ messages are not necessarily aligned with PGM datagram
boundaries and a single 0MQ message may span several PGM datagrams. This stream
of data consists of 0MQ messages encapsulated in 'frames' as described in
@@ -130,7 +130,7 @@ EXAMPLE
.Connecting a socket
----
/* Connecting to the multicast address 239.192.1.1, port 5555, */
-/* using the first ethernet network interface on Linux */
+/* using the first Ethernet network interface on Linux */
/* and the Encapsulated PGM protocol */
rc = zmq_connect(socket, "epgm://eth0;239.192.1.1:5555");
assert (rc == 0);
diff --git a/doc/zmq_poll.txt b/doc/zmq_poll.txt
index f709c07..e8e001c 100644
--- a/doc/zmq_poll.txt
+++ b/doc/zmq_poll.txt
@@ -40,17 +40,17 @@ NOTE: All 0MQ sockets passed to the _zmq_poll()_ function must share the
same 0MQ 'context' and must belong to the thread calling _zmq_poll()_.
For each *zmq_pollitem_t* item, _zmq_poll()_ shall first clear the 'revents'
-member, and then indicate any requested events that have occured by setting the
+member, and then indicate any requested events that have occurred by setting the
bit corresponding to the event condition in the 'revents' member.
-If none of the requested events have occured on any *zmq_pollitem_t* item,
+If none of the requested events have occurred on any *zmq_pollitem_t* item,
_zmq_poll()_ shall wait 'timeout' microseconds for an event to occur on
any of the requested items. If the value of 'timeout' is `0`, _zmq_poll()_
shall return immediately. If the value of 'timeout' is `-1`, _zmq_poll()_ shall
-block indefinitely until a requested event has occured on at least one
+block indefinitely until a requested event has occurred on at least one
*zmq_pollitem_t*.
-The 'events' and 'revents' members of *zmq_pollitem_t* are bitmasks constructed
+The 'events' and 'revents' members of *zmq_pollitem_t* are bit masks constructed
by OR'ing a combination of the following event flags:
*ZMQ_POLLIN*::
@@ -93,7 +93,8 @@ associated 0MQ 'context' was terminated.
*EFAULT*::
The provided 'items' was not valid (NULL).
*EINTR*::
-The poll was interrupted by delivery of a signal before any event was available.
+The operation was interrupted by delivery of a signal before any events were
+available.
EXAMPLE
diff --git a/doc/zmq_setsockopt.txt b/doc/zmq_setsockopt.txt
index af92929..86b01e4 100644
--- a/doc/zmq_setsockopt.txt
+++ b/doc/zmq_setsockopt.txt
@@ -171,13 +171,13 @@ Default value:: 10
Applicable socket types:: all, when using multicast transports
-ZMQ_MCAST_LOOP: Control multicast loopback
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+ZMQ_MCAST_LOOP: Control multicast loop-back
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
The 'ZMQ_MCAST_LOOP' option shall control whether data sent via multicast
transports using the specified 'socket' can also be received by the sending
-host via loopback. A value of zero disables the loopback functionality, while
-the default value of 1 enables the loopback functionality. Leaving multicast
-loopback enabled when it is not required can have a negative impact on
+host via loop-back. A value of zero disables the loop-back functionality, while
+the default value of 1 enables the loop-back functionality. Leaving multicast
+loop-back enabled when it is not required can have a negative impact on
performance. Where possible, disable 'ZMQ_MCAST_LOOP' in production
environments.
@@ -218,44 +218,63 @@ Applicable socket types:: all
ZMQ_LINGER: Set linger period for socket shutdown
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-The 'ZMQ_LINGER' option shall be set to specify period for pending outbound
-messages to linger in memory after closing the socket. Value of -1 means
-infinite. Pending messages will be kept until they are fully transferred to
-the peer. Value of 0 means that all the pending messages are dropped immediately
-when socket is closed. Positive value means number of milliseconds to keep
-trying to send the pending messages before discarding them.
+The 'ZMQ_LINGER' option shall set the linger period for the specified 'socket'.
+The linger period determines how long pending messages which have yet to be
+sent to a peer shall linger in memory after a socket is closed with
+linkzmq:zmq_close[3], and further affects the termination of the socket's
+context with linkzmq:zmq_term[3]. The following outlines the different
+behaviours:
+
+* The default value of '-1' specifies an infinite linger period. Pending
+ messages shall not be discarded after a call to _zmq_close()_; attempting to
+ terminate the socket's context with _zmq_term()_ shall block until all
+ pending messages have been sent to a peer.
+
+* The value of '0' specifies no linger period. Pending messages shall be
+ discarded immediately when the socket is closed with _zmq_close()_.
+
+* Positive values specify an upper bound for the linger period in milliseconds.
+ Pending messages shall not be discarded after a call to _zmq_close()_;
+ attempting to terminate the socket's context with _zmq_term()_ shall block
+ until either all pending messages have been sent to a peer, or the linger
+ period expires, after which any pending messages shall be discarded.
[horizontal]
Option value type:: int
Option value unit:: milliseconds
-Default value:: -1
+Default value:: -1 (infinite)
Applicable socket types:: all
-ZMQ_RECONNECT_IVL: Set reconnect period for connection-based transports
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-The 'ZMQ_RECONNECT_IVL' option shall be set to specify how long it takes for a
-disconnected underlying connection to attempt to reconnect. The interval
-can be randomized to some extent by 0MQ to prevent reconnection storms.
+ZMQ_RECONNECT_IVL: Set reconnection interval
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+The 'ZMQ_RECONNECT_IVL' option shall set the reconnection interval for the
+specified 'socket'. The reconnection interval is the maximum period 0MQ shall
+wait between attempts to reconnect disconnected peers when using
+connection-oriented transports.
+
+NOTE: The reconnection interval may be randomized by 0MQ to prevent
+reconnection storms in topologies with a large number of peers per socket.
[horizontal]
Option value type:: int
Option value unit:: milliseconds
Default value:: 100
-Applicable socket types:: all
+Applicable socket types:: all, only for connection-oriented transports
-ZMQ_BACKLOG: Set maximum length of the queue of pending connections
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-The 'ZMQ_BACKLOG' option shall be set to specify maximum size of the
-pending connection backlog for connection-based transports. For details
-refer to your operating system documentation for the 'listen' function.
+ZMQ_BACKLOG: Set maximum length of the queue of outstanding connections
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+The 'ZMQ_BACKLOG' option shall set the maximum length of the queue of
+outstanding peer connections for the specified 'socket'; this only applies to
+connection-oriented transports. For details refer to your operating system
+documentation for the 'listen' function.
[horizontal]
Option value type:: int
Option value unit:: connections
Default value:: 100
-Applicable socket types:: all
+Applicable socket types:: all, only for connection-oriented transports.
RETURN VALUE
diff --git a/doc/zmq_socket.txt b/doc/zmq_socket.txt
index 2156af2..6bcb133 100644
--- a/doc/zmq_socket.txt
+++ b/doc/zmq_socket.txt
@@ -35,7 +35,7 @@ sockets transfer streams of bytes or discrete datagrams, 0MQ sockets transfer
discrete _messages_.
0MQ sockets being _asynchronous_ means that the timings of the physical
-connection setup and teardown, reconnect and effective delivery are transparent
+connection setup and tear down, reconnect and effective delivery are transparent
to the user and organized by 0MQ itself. Further, messages may be _queued_ in
the event that a peer is unavailable to receive them.
@@ -46,6 +46,18 @@ relationships. With the exception of 'ZMQ_PAIR', 0MQ sockets may be connected
incoming connections *from multiple endpoints* bound to the socket using
_zmq_bind()_, thus allowing many-to-many relationships.
+.Thread safety
+A 0MQ 'context' is thread safe and may be shared among as many application
+threads as necessary, without any additional locking required on the part of
+the caller.
+
+Individual 0MQ 'sockets' are _not_ thread safe except in the case where full
+memory barriers are issued when migrating a socket from one thread to another.
+In practice this means applications can create a socket in one thread with
+_zmq_socket()_ and then pass it to a _newly created_ thread as part of thread
+initialization, for example via a structure passed as an argument to
+_pthread_create()_.
+
.Socket types
The following sections present the socket types defined by 0MQ, grouped by the
general _messaging pattern_ which is built from related socket types.
@@ -100,7 +112,7 @@ Compatible peer sockets:: 'ZMQ_REQ'
Direction:: Bidirectional
Send/receive pattern:: Receive, Send, Receive, Send, ...
Incoming routing strategy:: Fair-queued
-Outgoing routing stratagy:: Last peer
+Outgoing routing strategy:: Last peer
ZMQ_HWM option action:: Drop
@@ -166,13 +178,13 @@ ZMQ_HWM option action:: Drop
Publish-subscribe pattern
~~~~~~~~~~~~~~~~~~~~~~~~~
The publish-subscribe pattern is used for one-to-many distribution of data from
-a single _publisher_ to multiple _subscribers_ in a fanout fashion.
+a single _publisher_ to multiple _subscribers_ in a fan out fashion.
ZMQ_PUB
^^^^^^^
A socket of type 'ZMQ_PUB' is used by a _publisher_ to distribute data.
-Messages sent are distributed in a fanout fashion to all connected peers.
+Messages sent are distributed in a fan out fashion to all connected peers.
The linkzmq:zmq_recv[3] function is not implemented for this socket type.
When a 'ZMQ_PUB' socket enters an exceptional state due to having reached the
@@ -186,7 +198,7 @@ Compatible peer sockets:: 'ZMQ_SUB'
Direction:: Unidirectional
Send/receive pattern:: Send only
Incoming routing strategy:: N/A
-Outgoing routing strategy:: Fanout
+Outgoing routing strategy:: Fan out
ZMQ_HWM option action:: Drop
@@ -301,8 +313,6 @@ ERRORS
------
*EINVAL*::
The requested socket 'type' is invalid.
-*EMTHREAD*::
-The maximum number of sockets within this 'context' has been exceeded.
*EFAULT*::
The provided 'context' was not valid (NULL).
diff --git a/doc/zmq_tcp.txt b/doc/zmq_tcp.txt
index 29fa181..84ec6c8 100644
--- a/doc/zmq_tcp.txt
+++ b/doc/zmq_tcp.txt
@@ -30,7 +30,7 @@ colon and the TCP port number to use.
An 'interface' may be specified by either of the following:
-* The wildcard `*`, meaning all available interfaces.
+* The wild-card `*`, meaning all available interfaces.
* The primary IPv4 address assigned to the interface, in its numeric
representation.
* The interface name as defined by the operating system.
@@ -127,10 +127,10 @@ EXAMPLES
/* TCP port 5555 on all available interfaces */
rc = zmq_bind(socket, "tcp://*:5555");
assert (rc == 0);
-/* TCP port 5555 on the local loopback interface on all platforms */
+/* TCP port 5555 on the local loop-back interface on all platforms */
rc = zmq_bind(socket, "tcp://127.0.0.1:5555");
assert (rc == 0);
-/* TCP port 5555 on the first ethernet network interface on Linux */
+/* TCP port 5555 on the first Ethernet network interface on Linux */
rc = zmq_bind(socket, "tcp://eth0:5555");
assert (rc == 0);
----
diff --git a/doc/zmq_term.txt b/doc/zmq_term.txt
index 6c69b82..2edc765 100644
--- a/doc/zmq_term.txt
+++ b/doc/zmq_term.txt
@@ -14,20 +14,27 @@ SYNOPSIS
DESCRIPTION
-----------
-The _zmq_term()_ function terminates the 0MQ context 'context'.
+The _zmq_term()_ function shall terminate the 0MQ context 'context'.
-It does so in following steps:
+Context termination is performed in the following steps:
-* It causes any blocking operations currently in progress on sockets open within
- 'context' to exit immediately with an error code of ETERM.
+1. Any blocking operations currently in progress on sockets open within
+ 'context' shall return immediately with an error code of ETERM. With the
+ exception of _zmq_close()_, any further operations on sockets open within
+ 'context' shall fail with an error code of ETERM.
-* With the exception of _zmq_close()_, any further operations on sockets open
- within 'context' shall fail with an error code of ETERM.
+2. After interrupting all blocking calls, _zmq_term()_ shall _block_ until the
+ following conditions are satisfied:
++
+ * All sockets open within 'context' have been closed with _zmq_close()_.
-* After iterrupting all blocking calls, _zmq_term()_ blocks until all sockets
- open within the context are closed using _zmq_close()_ and either all the
- pending outbound messages are pushed to the network or ZMQ_LINGER period
- expires for individual sockets.
+ * For each socket within 'context', all messages sent by the application
+ with _zmq_send()_ have either been physically transferred to a network
+ peer, or the socket's linger period set with the _ZMQ_LINGER_ socket
+ option has expired.
+
+For further details regarding socket linger behaviour refer to the _ZMQ_LINGER_
+option in linkzmq:zmq_setsockopt[3].
RETURN VALUE
diff --git a/doc/zmq_version.txt b/doc/zmq_version.txt
index 0ad3a55..58b7977 100644
--- a/doc/zmq_version.txt
+++ b/doc/zmq_version.txt
@@ -15,7 +15,7 @@ SYNOPSIS
DESCRIPTION
-----------
The _zmq_version()_ function shall fill in the integer variables pointed to by
-the 'major', 'minor' and 'patch' arguments with the major, minor and patchlevel
+the 'major', 'minor' and 'patch' arguments with the major, minor and patch level
components of the 0MQ library version.
This functionality is intended for applications or language bindings