ZMQ_MSG_GETS(3)

ZMQ_MSG_GETS 💖 (3)

okay so bestie, welcome to the 0MQ Manual section 3 — this is the one where we get metadata properties off a message, and honestly? it's giving ✨detective energy✨. let's go. 🕵️♀️

---

🌸 NAME 🌸

zmq_msg_gets — get message metadata property. that's it, that's the whole vibe. 🎀

---

✨ SYNOPSIS ✨

const char *zmq_msg_gets (zmq_msg_t *message, const char *property);

---

💅 DESCRIPTION 💅

so the zmq_msg_gets() function shall return the string value for the metadata property you asked for — that's the property argument — for the message that message points at. both the property argument and the value are NULL-terminated UTF8-encoded strings, no cap. 🧚

metadata gets defined on a per-connection basis during the ZeroMQ connection handshake, as specified in <rfc.zeromq.org/spec:37>. your app can set metadata properties using the ZMQ_METADATA option of zmq_setsockopt(3). and bestie, listen — application metadata properties must be prefixed with X-. no X-, no entry. periodt. 💀

on top of application metadata, these ZMTP properties can be retrieved with zmq_msg_gets() too:

• Socket-Type
• Routing-Id

note: Identity is a deprecated alias for Routing-Id. it's giving "still works but please move on" 😭

also, when it's available for the underlying transport, the Peer-Address property will return the IP address of the remote endpoint, exactly as returned by getnameinfo(2). slay. 🔥

the names of these properties are also defined in zmq.h as ZMQ_MSG_PROPERTY_SOCKET_TYPE, ZMQ_MSG_PROPERTY_ROUTING_ID, and ZMQ_MSG_PROPERTY_PEER_ADDRESS. currently these definitions are only available as a DRAFT API — so like, handle with care, she's still in beta. 🙈

other properties may be defined based on the underlying security mechanism — see the ZAP authenticated connection sample below. 👑

---

🌈 RETURN VALUE 🌈

if it works, zmq_msg_gets() shall return the string value for the property. if not, it shall return NULL and set errno to one of the values defined below. 🫶

and this is important, bestie: the caller shall not modify or free the returned value — it shall be owned by the message. hands off, it's not yours. 🚫

the encoding of the property and the value shall be UTF8. always. 💜

---

💀 ERRORS 💀

• EINVAL — the requested property is unknown. like, girl, who? never heard of her. 🙅♀️

---

🎀 EXAMPLE 🎀

getting the ZAP authenticated user id for a message:

zmq_msg_t msg;
zmq_msg_init (&msg);
rc = zmq_msg_recv (&msg, dealer, 0);
assert (rc != -1);
const char *user_id = zmq_msg_gets (&msg, ZMQ_MSG_PROPERTY_USER_ID);
zmq_msg_close (&msg);

look at her go. iconic. ⭐

---

🦋 SEE ALSO 🦋

• zmq(7)
• zmq_setsockopt(3)

---

👑 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, 10/10. 💖

---

and that's a wrap on the ZMQ_MSG_GETS(3) page from the 0MQ Manual, dated 10/09/2023, shipped with 0MQ 4.3.5 — go forth and read your metadata, bestie, you're gonna eat. 💅✨🌸