ZMQ_SOCKET_MONITOR(3)

💖 ZMQ_SOCKET_MONITOR(3) 💖

okay bestie, pull up a chair, we're reading a 0MQ manual page together ✨ this one lives in the 0MQ Manual, section 3, and it's literally about watching your sockets like they're the main characters. no cap. 🫶

---

🌸 NAME 🌸

zmq_socket_monitor — monitor socket events 👀

---

✨ SYNOPSIS ✨

int zmq_socket_monitor (void *socket, char *endpoint, int events);

---

🦋 DESCRIPTION 🦋

So like. The zmq_socket_monitor() method lets one of your application threads track socket events (like connects, bestie, the whole dramatic saga) on a ZeroMQ socket. Every single time you call this method, it creates a ZMQ_PAIR socket and binds that to the inproc:// endpoint you specified. To actually collect the socket events, you gotta make your own ZMQ_PAIR socket and connect it to that endpoint. yes you have to do it yourself. it's giving DIY era. 💅

Also, heads up, there's a DRAFT function zmq_socket_monitor_versioned(3) that lets you subscribe to events carrying more info. Calling zmq_socket_monitor is equivalent to calling zmq_socket_monitor_versioned with the event_version parameter set to 1 — with the exception of error cases. so close to twins but not quite. 🙈

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 get added, the catch-all value will start returning them too. 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. (iconic warning honestly, listen to it 🔥)

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 endpoint. two frames, one glow-up. ✨

The zmq_socket_monitor() method supports only connection-oriented transports, that is, TCP, IPC, and TIPC. 💀 no UDP, no inproc-as-a-target, don't even try it.

---

🎀 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. (the FD is a former main character by then, ngl 😭)

🌈 ZMQ_EVENT_CONNECT_DELAYED

A connect request on the socket is pending. The event value is unspecified. it's in its waiting era ⏳

🌈 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. (it keeps doing the math. every time. 💀)

🌈 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. rejection arc, we've all been there 🥲

🌈 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. IPC only bestie, don't @ me 🧚

🌈 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. that's the outro music 🎵

🌈 ZMQ_EVENT_HANDSHAKE_FAILED_NO_DETAIL

Unspecified error during handshake. The event value is an errno.

🌈 ZMQ_EVENT_HANDSHAKE_SUCCEEDED

The ZMTP security mechanism handshake succeeded. The event value is unspecified. slay 💅✨

🌈 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

🌈 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). 🚫🔐

---

⭐ 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. (binary outcome, very demure, very mindful 🎀)

---

💜 ERRORS 💜

• ETERM — The 0MQ context associated with the specified socket was terminated. rip context 💀
• EPROTONOSUPPORT — The requested transport protocol is not supported. Monitor sockets are required to use the inproc:// transport. (read: you must use inproc://, that's the whole vibe)
• EINVAL — The endpoint supplied is invalid. 🙈

---

🌟 EXAMPLE 🌟

Monitoring client and server sockets. here's the whole thing, character for character, don't skip it, it's literally the bestie tutorial 🫶

//  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_HANDSHAKE_SUCCEEDED);
    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_HANDSHAKE_SUCCEEDED);
    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 🔍

• 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. (community-written, community-loved, periodt 💖)

---

and that's the whole page bestie!! this one came from 0MQ version 4.3.5, dated 10/09/2023, in the classic ZMQ_SOCKET_MONITOR(3) spot. go monitor something, you ate. 🦋✨