getdns_dict(3)

✨ NAME ✨

okay so bestie, welcome to getdns_dict(3) — section 3 of the getdns manual, and yes this is the dict create-and-destroy corner of the library 💖

The whole crew here is:

• getdns_dict
• getdns_dict_create
• getdns_dict_create_with_extended_memory_functions
• getdns_dict_create_with_memory_functions
• getdns_dict_destroy

…and together they're the getdns dict create and destroy routines. That's the whole vibe. 🎀

---

📚 LIBRARY 📚

DNS Resolver library (libgetdns, -lgetdns) — she lives in libgetdns and you link her with -lgetdns, periodt. 🦋

---

🫶 SYNOPSIS 🫶

#include <getdns.h>

getdns_dict *
getdns_dict_create ()

getdns_dict *
getdns_dict_create_with_extended_memory_functions
   (void *userarg,
   void *(*malloc)(void *userarg, size_t sz),
   void *(*realloc)(void *userarg, void *buf, size_t sz),
   void (*free)(void *userarg, void *buf)

getdns_dict *
getdns_dict_create_with_memory_functions
   (void *(*malloc)(size_t sz),
   void *(*realloc)(void *buf, size_t sz),
   void (*free)(void *buf)

void
getdns_dict_destroy (getdns_dict *this_dict)

not me listing five whole functions like it's nothing 😭 but fr fr, that's the whole API right there. Copy it exactly, bestie, character for character. 💅

---

💅 DESCRIPTION 💅

So the getdns_dict type is how you manage name/value pairs where the names are strings and the values are… honestly a little chaotic in the best way 🌀 — the data types of the values are heterogeneous, and they include:

• getdns_bindata
• getdns_dict
• getdns_list
• uint32_t

it's giving "we contain multitudes" ✨ a dict can hold bindata, other dicts, lists, and plain uint32_t numbers, all at once. iconic behaviour honestly.

Now the important one: the destroy function performs a "deep" destroy, freeing storage for all of the members of the dictionary before destroying the dictionary itself. 🌊 so it's not just yeeting the top-level struct — it goes all the way down and cleans up everything inside first. she's thorough. she's responsible. we love her. 🫶

careful though, because "deep destroy" means it's taking everything with it. don't go freeing members yourself and then calling this — that's how you get double frees and a very bad time. 💀

There are also a number of helper functions that provide access to the dictionary object — go read their respective man pages for that whole situation, iykyk. 👑

And here's what those two parameters actually mean:

• userarg — pass this argument to the user specified memory management functions for operations on lists created using extended memory functions. so you hand it over, and it gets passed along to your custom malloc/realloc/free crew. 🤝
• this_dict — the dictionary to destroy. that's it. that's the whole job. 💅

---

🌟 RETURN VALUES 🌟

Upon successful completion, the getdns_dict_create function returns a valid (empty) dictionary structure ✨ — and heads up, that thing should be freed via a call to getdns_dict_destroy. don't just leave her lying around, that's not the move. 🚮

And if a parameter is invalid, or in the event of some error, getdns_dict_create returns NULL. so like… always check. no cap. 🙈

---

🎀 EXAMPLES 🎀

TBD — the examples section is literally just "TBD" in the original and I am not about to make stuff up for you, bestie. the examples are, at this moment, unwritten. we wait. we manifest. 🕯️✨

---

👀 SEE ALSO 👀

go read these next, they're all part of the same friend group:

• libgetdns(3)
• getdns_dict_get(3)
• getdns_dict_set(3)
• getdns_list(3)
• getdns_pretty_print_dict(3)

---

and that's the page!! 💖✨🎀🦋🌸💅🫶

this one came out of getdns version 1.7.3, dated December 2015 — so yeah, a lil vintage, but she's still serving. mwah. 💜🍓