ZMONITOR(3)

✨ ZMONITOR(3) ✨ — like, the CZMQ manual, but make it make sense 💅

okay bestie, pull up a chair 🫶 this is zmonitor, from the CZMQ manual, and it is genuinely one of the cutest little classes in the whole library. no cap.

---

🎀 NAME 🎀

zmonitor — a class for socket event monitor. that's it, that's the vibe. it watches your sockets and tells you what they're going through. emotional support for your file descriptors fr fr 💖

---

✨ SYNOPSIS ✨

here's the whole deal, verbatim, don't touch the code bestie:

//  Create new zmonitor actor instance to monitor a zsock_t socket:
//
//      zactor_t *monitor = zactor_new (zmonitor, mysocket);
//
//  Destroy zmonitor instance.
//
//      zactor_destroy (&monitor);
//
//  Enable verbose logging of commands and activity.
//
//      zstr_send (monitor, "VERBOSE");
//
//  Listen to monitor event type (zero or types, ending in NULL):
//      zstr_sendx (monitor, "LISTEN", type, ..., NULL);
//
//      Events:
//      CONNECTED
//      CONNECT_DELAYED
//      CONNECT_RETRIED
//      LISTENING
//      BIND_FAILED
//      ACCEPTED
//      ACCEPT_FAILED
//      CLOSED
//      CLOSE_FAILED
//      DISCONNECTED
//      MONITOR_STOPPED
//      ALL
//
//  Start monitor; after this, any further LISTEN commands are ignored.
//
//      zstr_send (monitor, "START");
//      zsock_wait (monitor);
//
//  Receive next monitor event:
//
//      zmsg_t *msg = zmsg_recv (monitor);
//
//  This is the zmonitor constructor as a zactor_fn; the argument can be a
//  zactor_t, zsock_t, or libzmq void * socket:
CZMQ_EXPORT void
    zmonitor (zsock_t *pipe, void *sock);

//  Selftest
CZMQ_EXPORT void
    zmonitor_test (bool verbose);

and then there's this little note sitting there: Please add '@interface' section in './../src/zmonitor.c'. — yeah, that's a whole TODO just vibing in the docs. iconic honestly 🙈

---

💜 DESCRIPTION 💜

so the zmonitor actor gives you an API for catching socket events — the connected, listen, disconnected kinda stuff, all of it. heads up tho: socket events are only available for sockets that are connecting or bound to ipc:// and tcp:// endpoints. that's the rule, periodt.

this class is basically wrapping the ZMQ socket monitor API — go read zmq_socket_monitor for the details if you want the full lore. it works on all versions of libzmq from 3.2 onwards, which is honestly so generous of it. and it replaces zproxy_v2, so if you're still on that... bestie. it's meant for applications that use the CZMQ v3 API — meaning, zsock. that's the whole assignment. 💅

---

🌸 EXAMPLE 🌸

straight from the zmonitor_test method, no edits:

zsock_t *client = zsock_new (ZMQ_DEALER);
assert (client);
zactor_t *clientmon = zactor_new (zmonitor, client);
assert (clientmon);
if (verbose)
    zstr_sendx (clientmon, "VERBOSE", NULL);
zstr_sendx (clientmon, "LISTEN", "LISTENING", "ACCEPTED", NULL);
#if defined (ZMQ_EVENT_HANDSHAKE_SUCCEED)
zstr_sendx (clientmon, "LISTEN", "HANDSHAKE_SUCCEED", NULL);
#endif
#if defined (ZMQ_EVENT_HANDSHAKE_SUCCEEDED)
zstr_sendx (clientmon, "LISTEN", "HANDSHAKE_SUCCEEDED", NULL);
#endif
zstr_sendx (clientmon, "START", NULL);
zsock_wait (clientmon);

zsock_t *server = zsock_new (ZMQ_DEALER);
assert (server);
zactor_t *servermon = zactor_new (zmonitor, server);
assert (servermon);
if (verbose)
    zstr_sendx (servermon, "VERBOSE", NULL);
zstr_sendx (servermon, "LISTEN", "CONNECTED", "DISCONNECTED", NULL);
zstr_sendx (servermon, "START", NULL);
zsock_wait (servermon);

//  Allow a brief time for the message to get there...
zmq_poll (NULL, 0, 200);

//  Check client is now listening
int port_nbr = zsock_bind (client, "tcp://127.0.0.1:*");
assert (port_nbr != -1);
s_assert_event (clientmon, "LISTENING");

//  Check server connected to client
zsock_connect (server, "tcp://127.0.0.1:%d", port_nbr);
s_assert_event (servermon, "CONNECTED");

//  Check client accepted connection
s_assert_event (clientmon, "ACCEPTED");
#if defined (ZMQ_EVENT_HANDSHAKE_SUCCEED)
s_assert_event (clientmon, "HANDSHAKE_SUCCEED");
#endif
#if defined (ZMQ_EVENT_HANDSHAKE_SUCCEEDED)
s_assert_event (clientmon, "HANDSHAKE_SUCCEEDED");
#endif

zactor_destroy (&clientmon);
zactor_destroy (&servermon);
zsock_destroy (&client);
zsock_destroy (&server);

#if defined (__WINDOWS__)
zsys_shutdown();
#endif

like... the way it spins up a client, spins up a server, and just waits for them to find each other 🥹 main character energy from both sockets honestly.

---

👑 AUTHORS 👑

the czmq manual was written by the authors in the AUTHORS file. shoutout to them, they ate. 🫶

---

🌈 RESOURCES 🌈

Main web site:

(the page says "Main web site:" and then... nothing. the URL is just not there. we love a mysterious queen 💀)

Report bugs to the email zeromq-dev@lists.zeromq.org — go tell them everything, they want to know.

---

💖 COPYRIGHT 💖

Copyright (c) the Contributors as noted in the AUTHORS file. This file is part of CZMQ, the high-level C binding for 0MQ: http://czmq.zeromq.org. This Source Code Form is subject to the terms of the Mozilla Public License, v. 2.0. If a copy of the MPL was not distributed with this file, You can obtain one at http://mozilla.org/MPL/2.0/. LICENSE included with the czmq distribution.

(legal girlies rise up, that's the whole paragraph, don't skip it 📜)

---

⭐ NOTES ⭐

1. zeromq-dev@lists.zeromq.org — mailto:zeromq-dev@lists.zeromq.org

---

okay and that's the page!! CZMQ 4.2.1, dated 01/16/2026 — that's the version and the date bestie, go forth and monitor some sockets 💅✨🦋