ZMQ_MSG_INIT_DATA(3)

💖 ZMQ_MSG_INIT_DATA(3) 💖

okay bestie, gather round, because we're talking about zmq_msg_init_data from the 0MQ manual and it is lowkey one of the most main-character functions in the whole zmq_msg family. no cap. 🫶

---

✨ NAME ✨

zmq_msg_init_data — initialise a 0MQ message from a supplied buffer 💅

---

🌸 SYNOPSIS 🌸

typedef void (zmq_free_fn) (void *data, void *hint);

int zmq_msg_init_data (zmq_msg_t *msg, void *data, size_t size,
zmq_free_fn *ffn, void *hint);

---

🦋 DESCRIPTION 🦋

so the way that zmq_msg_init_data() works is: it shall initialise the message object referenced by msg so it represents the content referenced by the buffer sitting at address data, which is size bytes long. 🎀

and here's the iconic part — no copy of data shall be performed and 0MQ shall take ownership of the supplied buffer. like, it's yours until it's theirs. no dupe, no backup, just vibes and ownership transfer. 👑

if provided, the deallocation function ffn shall be called once the data buffer is no longer required by 0MQ, with the data and hint arguments supplied to zmq_msg_init_data(). so you hand it the cleanup function and it calls it later with the exact same args. mutual trust. 🤝

⚠️ Caution — Never access zmq_msg_t members directly, instead always use the zmq_msg family of functions. do NOT peek behind the curtain, bestie, that's not the vibe. 🙈

⚠️ Caution — The deallocation function ffn needs to be thread-safe, since it will be called from an arbitrary thread. it's giving "any thread, any time, no warning" energy. be ready. 💀

⚠️ Caution — If the deallocation function is not provided, the allocated memory will not be freed, and this may cause a memory leak. bestie. BESTIE. that memory is never coming back. it's a leak. 😭

⚠️ Caution — The functions zmq_msg_init(), zmq_msg_init_data(), zmq_msg_init_size() and zmq_msg_init_buffer() are mutually exclusive. Never initialise the same zmq_msg_t twice. pick ONE. not two. never two. periodt. ✋

---

🌈 RETURN VALUE 🌈

zmq_msg_init_data() shall return zero if successful. otherwise it shall return -1 and set errno to one of the values defined below. zero = slay, -1 = check your errno, girl. ✨

---

💜 ERRORS 💜

• ENOMEM — Insufficient storage space is available. the storage is not storing. the space is not spaced. 😔

---

🍓 EXAMPLE 🍓

Initialising a message from a supplied buffer. look at her go 🎀

void my_free (void *data, void *hint)
{
    free (data);
}

    /*  ...  */

void *data = malloc (6);
assert (data);
memcpy (data, "ABCDEF", 6);
zmq_msg_t msg;
rc = zmq_msg_init_data (&msg, data, 6, my_free, NULL);
assert (rc == 0);

see how my_free just goes poof and frees the data when 0MQ is done with it? that's the whole contract. that's the arrangement. iconic behaviour honestly. 🔥

---

👑 SEE ALSO 👑

zmq_msg_init_size(3) zmq_msg_init_buffer(3) zmq_msg_init(3) zmq_msg_close(3) zmq_msg_data(3) zmq_msg_size(3) zmq(7)

like, go read the rest of the family, they're all connected, iykyk 💫

---

🧚 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.

so yeah, it's a community thing, come contribute, we'd love to have you 🫶

---

aaaaand that's the whole page babes 🌸 this was 0MQ version 4.3.5, dated 10/09/2023, and the page is ZMQ_MSG_INIT_DATA(3) — mwah, stay leak-free, use your free function, and never init the same message twice 💅✨💖