laag-libzmq 4.2.3.0

data/vendor/github.com/zeromq/libzmq/doc/zmq_socket_monitor.txt

@@ -0,0 +1,294 @@
+zmq_socket_monitor(3)
+=====================
+
+
+NAME
+----
+
+zmq_socket_monitor - monitor socket events
+
+
+SYNOPSIS
+--------
+*int zmq_socket_monitor (void '*socket', char '*endpoint', int 'events');*
+
+
+DESCRIPTION
+-----------
+The _zmq_socket_monitor()_ method lets an application thread track
+socket events (like connects) on a ZeroMQ socket. Each call to this
+method creates a 'ZMQ_PAIR' socket and binds that to the specified
+inproc:// 'endpoint'. To collect the socket events, you must create
+your own 'ZMQ_PAIR' socket, and connect that to the endpoint.
+
+The 'events' argument is a bitmask of the socket events you wish to
+monitor, see 'Supported events' below. To monitor all events, use the
+event value ZMQ_EVENT_ALL. NOTE: as new events are added, the catch-all
+value will start returning them. An application that relies on a strict
+and fixed sequence of events must not use ZMQ_EVENT_ALL in order to
+guarantee compatibility with future versions.
+
+Each event is sent as two frames. The first frame contains an event
+number (16 bits), and an event value (32 bits) that provides additional
+data according to the event number. The second frame contains a string
+that specifies the affected TCP or IPC endpoint.
+
+----
+The _zmq_socket_monitor()_ method supports only connection-oriented
+transports, that is, TCP, IPC, and TIPC.
+----
+
+Supported events
+----------------
+
+ZMQ_EVENT_CONNECTED
+~~~~~~~~~~~~~~~~~~~
+The socket has successfully connected to a remote peer. The event value
+is the file descriptor (FD) of the underlying network socket. Warning:
+there is no guarantee that the FD is still valid by the time your code
+receives this event.
+
+ZMQ_EVENT_CONNECT_DELAYED
+~~~~~~~~~~~~~~~~~~~~~~~~~
+A connect request on the socket is pending. The event value is unspecified.
+
+ZMQ_EVENT_CONNECT_RETRIED
+~~~~~~~~~~~~~~~~~~~~~~~~~
+A connect request failed, and is now being retried. The event value is the
+reconnect interval in milliseconds. Note that the reconnect interval is
+recalculated at each retry.
+
+ZMQ_EVENT_LISTENING
+~~~~~~~~~~~~~~~~~~~
+The socket was successfully bound to a network interface. The event value
+is the FD of the underlying network socket. Warning: there is no guarantee
+that the FD is still valid by the time your code receives this event.
+
+ZMQ_EVENT_BIND_FAILED
+~~~~~~~~~~~~~~~~~~~~~
+The socket could not bind to a given interface. The event value is the
+errno generated by the system bind call.
+
+ZMQ_EVENT_ACCEPTED
+~~~~~~~~~~~~~~~~~~
+The socket has accepted a connection from a remote peer. The event value is
+the FD of the underlying network socket. Warning: there is no guarantee that
+the FD is still valid by the time your code receives this event.
+
+ZMQ_EVENT_ACCEPT_FAILED
+~~~~~~~~~~~~~~~~~~~~~~~
+The socket has rejected a connection from a remote peer. The event value is
+the errno generated by the accept call.
+
+ZMQ_EVENT_CLOSED
+~~~~~~~~~~~~~~~~
+The socket was closed. The event value is the FD of the (now closed) network
+socket.
+
+ZMQ_EVENT_CLOSE_FAILED
+~~~~~~~~~~~~~~~~~~~~~~
+The socket close failed. The event value is the errno returned by the system
+call. Note that this event occurs only on IPC transports.
+
+ZMQ_EVENT_DISCONNECTED
+~~~~~~~~~~~~~~~~~~~~~~
+The socket was disconnected unexpectedly. The event value is the FD of the
+underlying network socket. Warning: this socket will be closed.
+
+ZMQ_EVENT_MONITOR_STOPPED
+~~~~~~~~~~~~~~~~~~~~~~~~~
+Monitoring on this socket ended.
+
+DRAFT events - subject to change without notice
+-----------------------------------------------
+
+ZMQ_EVENT_HANDSHAKE_FAILED_NO_DETAIL
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+Unspecified error during handshake.
+The event value is an errno.
+NOTE: in DRAFT state, not yet available in stable releases.
+
+ZMQ_EVENT_HANDSHAKE_SUCCEEDED
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+The ZMTP security mechanism handshake succeeded.
+The event value is unspecified.
+NOTE: in DRAFT state, not yet available in stable releases.
+
+ZMQ_EVENT_HANDSHAKE_FAILED_PROTOCOL
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+The ZMTP security mechanism handshake failed due to some mechanism protocol 
+error, either between the ZMTP mechanism peers, or between the mechanism 
+server and the ZAP handler. This indicates a configuration or implementation 
+error in either peer resp. the ZAP handler.
+The event value is one of the ZMQ_PROTOCOL_ERROR_* values:
+ZMQ_PROTOCOL_ERROR_ZMTP_UNSPECIFIED
+ZMQ_PROTOCOL_ERROR_ZMTP_UNEXPECTED_COMMAND
+ZMQ_PROTOCOL_ERROR_ZMTP_INVALID_SEQUENCE
+ZMQ_PROTOCOL_ERROR_ZMTP_KEY_EXCHANGE
+ZMQ_PROTOCOL_ERROR_ZMTP_MALFORMED_COMMAND_UNSPECIFIED
+ZMQ_PROTOCOL_ERROR_ZMTP_MALFORMED_COMMAND_MESSAGE
+ZMQ_PROTOCOL_ERROR_ZMTP_MALFORMED_COMMAND_HELLO
+ZMQ_PROTOCOL_ERROR_ZMTP_MALFORMED_COMMAND_INITIATE
+ZMQ_PROTOCOL_ERROR_ZMTP_MALFORMED_COMMAND_ERROR
+ZMQ_PROTOCOL_ERROR_ZMTP_MALFORMED_COMMAND_READY
+ZMQ_PROTOCOL_ERROR_ZMTP_MALFORMED_COMMAND_WELCOME
+ZMQ_PROTOCOL_ERROR_ZMTP_INVALID_METADATA
+ZMQ_PROTOCOL_ERROR_ZMTP_CRYPTOGRAPHIC
+ZMQ_PROTOCOL_ERROR_ZMTP_MECHANISM_MISMATCH
+ZMQ_PROTOCOL_ERROR_ZAP_UNSPECIFIED
+ZMQ_PROTOCOL_ERROR_ZAP_MALFORMED_REPLY
+ZMQ_PROTOCOL_ERROR_ZAP_BAD_REQUEST_ID
+ZMQ_PROTOCOL_ERROR_ZAP_BAD_VERSION
+ZMQ_PROTOCOL_ERROR_ZAP_INVALID_STATUS_CODE
+ZMQ_PROTOCOL_ERROR_ZAP_INVALID_METADATA
+NOTE: in DRAFT state, not yet available in stable releases.
+
+ZMQ_EVENT_HANDSHAKE_FAILED_AUTH
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+The ZMTP security mechanism handshake failed due to an authentication failure.
+The event value is the status code returned by the ZAP handler (i.e. 300, 
+400 or 500).
+NOTE: in DRAFT state, not yet available in stable releases.
+
+
+
+RETURN VALUE
+------------
+The _zmq_socket_monitor()_ function returns a value of 0 or greater if
+successful. Otherwise it returns `-1` and sets 'errno' to one of the values
+defined below.
+
+
+ERRORS
+------
+*ETERM*::
+The 0MQ 'context' associated with the specified 'socket' was terminated.
+
+*EPROTONOSUPPORT*::
+The requested 'transport' protocol is not supported. Monitor sockets are
+required to use the inproc:// transport.
+
+*EINVAL*::
+The endpoint supplied is invalid.
+
+EXAMPLE
+-------
+.Monitoring client and server sockets
+----
+//  Read one event off the monitor socket; return value and address
+//  by reference, if not null, and event number by value. Returns -1
+//  in case of error.
+
+static int
+get_monitor_event (void *monitor, int *value, char **address)
+{
+    //  First frame in message contains event number and value
+    zmq_msg_t msg;
+    zmq_msg_init (&msg);
+    if (zmq_msg_recv (&msg, monitor, 0) == -1)
+        return -1;              //  Interrupted, presumably
+    assert (zmq_msg_more (&msg));
+
+    uint8_t *data = (uint8_t *) zmq_msg_data (&msg);
+    uint16_t event = *(uint16_t *) (data);
+    if (value)
+        *value = *(uint32_t *) (data + 2);
+
+    //  Second frame in message contains event address
+    zmq_msg_init (&msg);
+    if (zmq_msg_recv (&msg, monitor, 0) == -1)
+        return -1;              //  Interrupted, presumably
+    assert (!zmq_msg_more (&msg));
+
+    if (address) {
+        uint8_t *data = (uint8_t *) zmq_msg_data (&msg);
+        size_t size = zmq_msg_size (&msg);
+        *address = (char *) malloc (size + 1);
+        memcpy (*address, data, size);
+        (*address)[size] = 0;
+    }
+    return event;
+}
+
+int main (void)
+{
+    void *ctx = zmq_ctx_new ();
+    assert (ctx);
+
+    //  We'll monitor these two sockets
+    void *client = zmq_socket (ctx, ZMQ_DEALER);
+    assert (client);
+    void *server = zmq_socket (ctx, ZMQ_DEALER);
+    assert (server);
+
+    //  Socket monitoring only works over inproc://
+    int rc = zmq_socket_monitor (client, "tcp://127.0.0.1:9999", 0);
+    assert (rc == -1);
+    assert (zmq_errno () == EPROTONOSUPPORT);
+
+    //  Monitor all events on client and server sockets
+    rc = zmq_socket_monitor (client, "inproc://monitor-client", ZMQ_EVENT_ALL);
+    assert (rc == 0);
+    rc = zmq_socket_monitor (server, "inproc://monitor-server", ZMQ_EVENT_ALL);
+    assert (rc == 0);
+
+    //  Create two sockets for collecting monitor events
+    void *client_mon = zmq_socket (ctx, ZMQ_PAIR);
+    assert (client_mon);
+    void *server_mon = zmq_socket (ctx, ZMQ_PAIR);
+    assert (server_mon);
+
+    //  Connect these to the inproc endpoints so they'll get events
+    rc = zmq_connect (client_mon, "inproc://monitor-client");
+    assert (rc == 0);
+    rc = zmq_connect (server_mon, "inproc://monitor-server");
+    assert (rc == 0);
+
+    //  Now do a basic ping test
+    rc = zmq_bind (server, "tcp://127.0.0.1:9998");
+    assert (rc == 0);
+    rc = zmq_connect (client, "tcp://127.0.0.1:9998");
+    assert (rc == 0);
+    bounce (client, server);
+
+    //  Close client and server
+    close_zero_linger (client);
+    close_zero_linger (server);
+
+    //  Now collect and check events from both sockets
+    int event = get_monitor_event (client_mon, NULL, NULL);
+    if (event == ZMQ_EVENT_CONNECT_DELAYED)
+        event = get_monitor_event (client_mon, NULL, NULL);
+    assert (event == ZMQ_EVENT_CONNECTED);
+    event = get_monitor_event (client_mon, NULL, NULL);
+    assert (event == ZMQ_EVENT_MONITOR_STOPPED);
+
+    //  This is the flow of server events
+    event = get_monitor_event (server_mon, NULL, NULL);
+    assert (event == ZMQ_EVENT_LISTENING);
+    event = get_monitor_event (server_mon, NULL, NULL);
+    assert (event == ZMQ_EVENT_ACCEPTED);
+    event = get_monitor_event (server_mon, NULL, NULL);
+    assert (event == ZMQ_EVENT_CLOSED);
+    event = get_monitor_event (server_mon, NULL, NULL);
+    assert (event == ZMQ_EVENT_MONITOR_STOPPED);
+
+    //  Close down the sockets
+    close_zero_linger (client_mon);
+    close_zero_linger (server_mon);
+    zmq_ctx_term (ctx);
+
+    return 0 ;
+}
+----
+
+
+SEE ALSO
+--------
+linkzmq:zmq[7]
+
+
+AUTHORS
+-------
+This page was written by the 0MQ community. To make a change please
+read the 0MQ Contribution Policy at <http://www.zeromq.org/docs:contributing>.

data/vendor/github.com/zeromq/libzmq/doc/zmq_strerror.txt

@@ -0,0 +1,56 @@
+zmq_strerror(3)
+===============
+
+
+NAME
+----
+zmq_strerror - get 0MQ error message string
+
+
+SYNOPSIS
+--------
+*const char *zmq_strerror (int 'errnum');*
+
+
+DESCRIPTION
+-----------
+The _zmq_strerror()_ function shall return a pointer to an error message string
+corresponding to the error number specified by the 'errnum' argument. As 0MQ
+defines additional error numbers over and above those defined by the operating
+system, applications should use _zmq_strerror()_ in preference to the standard
+_strerror()_ function.
+
+
+RETURN VALUE
+------------
+The _zmq_strerror()_ function shall return a pointer to an error message
+string.
+
+
+ERRORS
+------
+No errors are defined.
+
+
+EXAMPLE
+-------
+.Displaying an error message when a 0MQ context cannot be initialised
+----
+void *ctx = zmq_init (1, 1, 0);
+if (!ctx) {
+    printf ("Error occurred during zmq_init(): %s\n", zmq_strerror (errno));
+    abort ();
+}
+----
+
+
+SEE ALSO
+--------
+linkzmq:zmq[7]
+
+
+AUTHORS
+-------
+This page was written by the 0MQ community. To make a change please
+read the 0MQ Contribution Policy at <http://www.zeromq.org/docs:contributing>.
+

data/vendor/github.com/zeromq/libzmq/doc/zmq_tcp.txt

@@ -0,0 +1,118 @@
+zmq_tcp(7)
+==========
+
+
+NAME
+----
+zmq_tcp - 0MQ unicast transport using TCP
+
+
+SYNOPSIS
+--------
+TCP is an ubiquitous, reliable, unicast transport. When connecting distributed
+applications over a network with 0MQ, using the TCP transport will likely be
+your first choice.
+
+
+ADDRESSING
+----------
+A 0MQ endpoint is a string consisting of a 'transport'`://` followed by an
+'address'. The 'transport' specifies the underlying protocol to use. The
+'address' specifies the transport-specific address to connect to.
+
+For the TCP transport, the transport is `tcp`, and the meaning of the
+'address' part is defined below.
+
+
+Assigning a local address to a socket
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+When assigning a local address to a socket using _zmq_bind()_ with the 'tcp'
+transport, the 'endpoint' shall be interpreted as an 'interface' followed by a
+colon and the TCP port number to use.
+
+An 'interface' may be specified by either of the following:
+
+* The wild-card `*`, meaning all available interfaces.
+* The primary IPv4 or IPv6 address assigned to the interface, in its numeric
+  representation.
+* The non-portable interface name as defined by the operating system.
+
+The TCP port number may be specified by:
+
+* A numeric value, usually above 1024 on POSIX systems.
+* The wild-card `*`, meaning a system-assigned ephemeral port.
+
+When using ephemeral ports, the caller should retrieve the actual assigned
+port using the ZMQ_LAST_ENDPOINT socket option. See linkzmq:zmq_getsockopt[3]
+for details.
+
+Unbinding wild-card address from a socket
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+When wild-card `*` 'endpoint' was used in _zmq_bind()_, the caller should use
+real 'endpoint' obtained from the ZMQ_LAST_ENDPOINT socket option to unbind 
+this 'endpoint' from a socket using _zmq_unbind()_.
+
+Connecting a socket
+~~~~~~~~~~~~~~~~~~~
+When connecting a socket to a peer address using _zmq_connect()_ with the 'tcp'
+transport, the 'endpoint' shall be interpreted as a 'peer address' followed by
+a colon and the TCP port number to use.
+You can optionally specify a 'source_endpoint' which will be used as the source
+address for your connection; tcp://'source_endpoint';'endpoint', see the
+'interface' description above for details.
+
+A 'peer address' may be specified by either of the following:
+
+* The DNS name of the peer.
+* The IPv4 or IPv6 address of the peer, in its numeric representation.
+
+Note: A description of the ZeroMQ Message Transport Protocol (ZMTP) which is 
+used by the TCP transport can be found at <http://rfc.zeromq.org/spec:15>
+
+EXAMPLES
+--------
+.Assigning a local address to a socket
+----
+//  TCP port 5555 on all available interfaces
+rc = zmq_bind(socket, "tcp://*:5555");
+assert (rc == 0);
+//  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
+rc = zmq_bind(socket, "tcp://eth0:5555");
+assert (rc == 0);
+----
+
+.Connecting a socket
+----
+//  Connecting using an IP address
+rc = zmq_connect(socket, "tcp://192.168.1.1:5555");
+assert (rc == 0);
+//  Connecting using a DNS name
+rc = zmq_connect(socket, "tcp://server1:5555");
+assert (rc == 0);
+//  Connecting using a DNS name and bind to eth1
+rc = zmq_connect(socket, "tcp://eth1:0;server1:5555");
+assert (rc == 0);
+//  Connecting using a IP address and bind to an IP address
+rc = zmq_connect(socket, "tcp://192.168.1.17:5555;192.168.1.1:5555");
+assert (rc == 0);
+----
+
+
+SEE ALSO
+--------
+linkzmq:zmq_bind[3]
+linkzmq:zmq_connect[3]
+linkzmq:zmq_pgm[7]
+linkzmq:zmq_ipc[7]
+linkzmq:zmq_inproc[7]
+linkzmq:zmq_vmci[7]
+linkzmq:zmq[7]
+
+
+AUTHORS
+-------
+This page was written by the 0MQ community. To make a change please
+read the 0MQ Contribution Policy at <http://www.zeromq.org/docs:contributing>.