ZMQ_UNBIND(3)

💅 ZMQ_UNBIND 💅

okay bestie, welcome to the 0MQ manual, page ZMQ_UNBIND(3) — yes you read that right, we're in section 3, the library-functions section, and this one is chef's kiss important if you've ever bound a socket and then been like "ok but how do I un-bind it 🥲". Sit down, grab a strawberry, let's go. 🍓

---

✨ NAME ✨

zmq_unbind — stop accepting connections on a socket. that's it, that's the vibe. 💖

---

🌸 SYNOPSIS 🌸

int zmq_unbind (void *socket, const char *endpoint);

---

🦋 DESCRIPTION 🦋

so like, zmq_unbind() shall unbind a socket — the one you pass in as the socket argument — from the endpoint you give it in the endpoint argument. bye bye connection, you are released, go live your truth. 💅

and also, the incoming message queue associated with that endpoint will be discarded. which means — and listen closely, this is the lowkey confusing part — after you unbind an endpoint, it is possible to receive messages originating from that same endpoint if they were already present in the incoming message queue before unbinding. so like, the queue gets nuked but messages that were already chillin' there before the unbind? yeah those can still show up. no cap. 😭

the endpoint argument is as described in zmq_bind(3). go read that one, it's giving details. 📖

🎀 Unbinding wild-card address from a socket 🎀

when a wild-card * endpoint (which is described in zmq_tcp(7), zmq_ipc(7), zmq_udp(7) and zmq_vmci(7) — yes, all four, go look) was used in zmq_bind(), the caller should use the real endpoint obtained from the ZMQ_LAST_ENDPOINT socket option to unbind this endpoint from a socket.

basically: you can't unbind the *, bestie. you gotta ask the socket what its actual address turned out to be first. 👑

---

⭐ RETURN VALUE ⭐

zmq_unbind() shall return zero if everything went slay. otherwise it shall return -1 and set errno to one of the values defined below. not slay. 💀

---

🔥 ERRORS 🔥

• EINVAL — the endpoint you supplied is invalid. you made it up. it's not real. 🙈
• ETERM — the 0MQ context associated with the specified socket was terminated. rip context, gone too soon. 😭
• ENOTSOCK — the provided socket was invalid. that's not a socket, bestie, that's a vibe. and not a good one. 💀
• ENOENT — the endpoint supplied was not previously bound. you're trying to unbind something that was never bound in the first place. iconically messy behaviour. 🫠

---

🌈 EXAMPLES 🌈

Unbind a subscriber socket from a TCP transport.

/* Create a ZMQ_SUB socket */
void *socket = zmq_socket (context, ZMQ_SUB);
assert (socket);
/* Connect it to the host server001, port 5555 using a TCP transport */
rc = zmq_bind (socket, "tcp://127.0.0.1:5555");
assert (rc == 0);
/* Disconnect from the previously connected endpoint */
rc = zmq_unbind (socket, "tcp://127.0.0.1:5555");
assert (rc == 0);

Unbind wild-card * binded socket.

/* Create a ZMQ_SUB socket */
void *socket = zmq_socket (context, ZMQ_SUB);
assert (socket);
/* Bind it to the system-assigned ephemeral port using a TCP transport */
rc = zmq_bind (socket, "tcp://127.0.0.1:*");
assert (rc == 0);
/* Obtain real endpoint */
const size_t buf_size = 32;
char buf[buf_size];
rc = zmq_getsockopt (socket, ZMQ_LAST_ENDPOINT, buf, (size_t *)&buf_size);
assert (rc == 0);
/* Unbind socket by real endpoint */
rc = zmq_unbind (socket, buf);
assert (rc == 0);

---

💜 NOTE 💜

note that while the implementation is similar to zmq_disconnect(), the semantics are different and the two functions should not be used interchangeably. bound sockets should be unbound, and connected sockets should be disconnected. that's the rule. bound → unbind, connected → disconnect. do not mix them, do not freestyle, do not play. 🚨

---

👑 SEE ALSO 👑

zmq_bind(3) zmq_socket(3) 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. they're literally so welcoming, go contribute bestie, main character energy fr fr. 💖

---

and that's the whole page!! this lil manual situation is from 0MQ version 4.3.5, dated 10/09/2023 — shoutout to the ZMQ_UNBIND(3) of it all. now go unbind responsibly, and remember: bound sockets get unbound, connected sockets get disconnected, and you? you get to slay. periodt. 💅✨