MCD_DUMP_DATA_REGISTER_BIN(3)

✨ MCD_DUMP_DATA_REGISTER_BIN(3) ✨

okay so bestie, quick context before we dive in: this page lives in the minicoredumper manual, section 3 (that's the library-functions section, iykyk 🫶). grab a strawberry 🍓, sit down, and let's talk about registering binary data so it gets dumped when everything goes sideways.

---

🌸 NAME 🌸

mcd_dump_data_register_bin — register binary data to be dumped 💖

---

✨ SYNOPSIS ✨

#include <minicoredumper.h>

int mcd_dump_data_register_bin(const char *ident,
                               unsigned long dump_scope,
                               mcd_dump_data_t *save_ptr,
                               void *data_ptr,
                               size_t data_size,
                               enum mcd_dump_data_flags flags);

Compile and link with -lminicoredumper.

---

💅 DESCRIPTION 💅

mcd_dump_data_register_bin() registers binary data to be dumped. iconic behavior, honestly.

So here's the tea, function by function 🎀:

• ident — a string that identifies this binary dump later. If it's non-NULL, it must be unique! (no cap, the library will not let you double-book.) If ident is NULL, the data only gets dumped if this is the crashing application — in which case it's explicitly stored in the core(5) file.
• dump_scope — the data only gets dumped if a scope value greater than or equal to dump_scope is requested by the minicoredumper(8).
• save_ptr — if it's non-NULL, a pointer to the registered dump gets stored there. you need this if you're gonna call mcd_dump_data_unregister(3) later, bestie.
• data_ptr — a pointer to the memory location of the data to dump (or a pointer to that pointer 👀).
• flags — tells everyone how data_ptr and data_size should be interpreted when dumping data.
• data_size — the number of bytes of data to dump (or, plot twist, a pointer to that number).

---

🌈 DATA FLAGS 🌈

The flags option is the one that says how data_ptr and data_size should be read when dumping data. It can also mess with dump behavior, so pay attention 😤. Flags are bitwise combined to describe the vibe you want. The flags available are:

• MCD_DATA_PTR_DIRECT — data_ptr is a pointer to the data to dump. simple. clean. eat.
• MCD_DATA_PTR_INDIRECT — data_ptr is a pointer to a second pointer that points to the data to dump. that second pointer gets evaluated at dump time. ⚠️ peep BUGS for the deets on why this flag is lowkey dangerous.
• MCD_LENGTH_DIRECT — data_size specifies the size (in bytes) of data to dump.
• MCD_LENGTH_INDIRECT — data_size is a pointer to the size (in bytes) of data to dump. that pointer gets evaluated at dump time. ⚠️ again, BUGS has the warnings about the dangers of this one.
• MCD_DATA_NODUMP — do not dump the specified data and size. only store info about where in memory and where in the core(5) file this data would have been stored. that info lands in the symbol.map dump file, and the coreinject(1) tool can use it to inject data into the registered location. main character energy for the metadata 💅.

---

🫶 RETURN VALUE 🫶

mcd_dump_data_register_bin() returns 0 on success. otherwise, an error value is returned. periodt.

---

💀 ERRORS 💀

• ENOMEM — insufficient memory available to allocate internal structures. 😭
• EINVAL — data_ptr was NULL, data_size was 0, or ident was invalid.
• EEXIST — a binary or text dump matching the non-NULL ident was already registered. bestie we already have one of those.

---

✨ EXAMPLES ✨

Register a binary dump with direct data and direct size.

mcd_dump_data_t dd1;
unsigned long val1;

mcd_dump_data_register_bin("bdump1.bin", 6, &dd1, &val1, sizeof(val1),
                           MCD_DATA_PTR_DIRECT | MCD_LENGTH_DIRECT);

Register a binary dump with indirect data and direct size.

mcd_dump_data_t dd2;
unsigned long *val2;

val2 = malloc(sizeof(unsigned long));

mcd_dump_data_register_bin("bdump2.bin", 6, &dd2, &val2, sizeof(*val2),
                           MCD_DATA_PTR_INDIRECT | MCD_LENGTH_DIRECT);

Register a binary dump with indirect data and indirect size.

mcd_dump_data_t dd3;
unsigned long *val3;
size_t s3;

s3 = sizeof(unsigned long);
val3 = malloc(s3);

mcd_dump_data_register_bin("bdump3.bin", 6, &dd3, &val3, (size_t)&s3,
                           MCD_DATA_PTR_INDIRECT | MCD_LENGTH_INDIRECT);

---

🙈 BUGS 🙈

MCD_DATA_PTR_INDIRECT and MCD_LENGTH_INDIRECT let an application change the size and location of the data to dump at run-time. however 👀 — such changes should be performed carefully, because an application literally cannot know when a dump will occur. it's giving "surprise, you're being dumped right now".

The string specified in ident is also the file name of the dump file. for this reason, characters such as / are not permitted. like, at all. no slashes, bestie, we mean it.

---

🦋 SEE ALSO 🦋

libminicoredumper(7), mcd_dump_data_unregister(3), coreinject(1)

The DiaMon Workgroup: <http://www.diamon.org>

---

okay that's the whole page, you ate it up fr fr 👑💖 this was minicoredumper, dated 2016-09-12, and you found it under MCD_DUMP_DATA_REGISTER_BIN(3). go forth and register your binary data, bestie 🧚✨