DNV(9)

✨ DNV(9) ✨

okay bestie, you're reading the Kernel Developer's Manual page for dnvlist_get, dnvlist_take — aka the API for getting name/value pairs 💅 and the whole entire point is that nonexistent pairs do not raise an error. no drama, no meltdown, it just hands you the default. iconic behavior fr fr 🫶

---

🌸 NAME 🌸

dnvlist_get, dnvlist_take — API for getting name/value pairs. Nonexistent pairs do not raise an error. 🎀

---

📚 LIBRARY 📚

library “libnv” — that's where all the good stuff lives 💜

---

🦋 SYNOPSIS 🦋

#include <sys/dnv.h>

bool
dnvlist_get_bool(const nvlist_t *nvl, const char *name, bool defval);

uint64_t
dnvlist_get_number(const nvlist_t *nvl, const char *name,
    uint64_t defval);

char *
dnvlist_get_string(const nvlist_t *nvl, const char *name,
    const char *defval);

nvlist_t *
dnvlist_get_nvlist(const nvlist_t *nvl, const char *name,
    nvlist_t *defval);

int
dnvlist_get_descriptor(const nvlist_t *nvl, const char *name,
    int defval);

void *
dnvlist_get_binary(const nvlist_t *nvl, const char *name, size_t *sizep,
    void *defval, size_t defsize);

bool
dnvlist_take_bool(const nvlist_t *nvl, const char *name, bool defval);

uint64_t
dnvlist_take_number(const nvlist_t *nvl, const char *name,
    uint64_t defval);

char *
dnvlist_take_string(const nvlist_t *nvl, const char *name,
    const char *defval);

nvlist_t *
dnvlist_take_nvlist(const nvlist_t *nvl, const char *name,
    nvlist_t *defval);

int
dnvlist_take_descriptor(const nvlist_t *nvl, const char *name,
    int defval);

void *
dnvlist_take_binary(const nvlist_t *nvl, const char *name,
    size_t *sizep, void *defval, size_t defsize);

like, twelve functions. twelve. all of them your besties. ✨

---

💖 DESCRIPTION 💖

so the libnv library lets you manage name/value pairs like it's nothing, and it can send and receive them over sockets too. main character energy honestly 👑 for even more lore, go peek at nv(9).

🫶 the dnvlist_get family

the dnvlist_get squad returns the value that's chilling next to the name you asked for. and if an element with that name literally does not exist?? no worries babe, it just returns the value you handed over in defval. 🌈

⚠️ okay listen. returned strings, nvlists, descriptors, binaries, or arrays must not be modified by the user. not even a little. they still belong to the nvlist, they're not yours, you're just borrowing them 💀

🚨 and if the nvlist is in an error state, any attempt to use any of these functions will cause the program to abort. like, full on. no takebacks. 😭

🎀 the dnvlist_take family

the dnvlist_take squad is the same vibe but with commitment — it returns the value associated with the specified name and removes the element from the nvlist. take it and it's gone, periodt 💅

if an element of the supplied name does not exist, you get the value provided in defval back, same as before.

and now, the cleanup duties bestie, because with great taking comes great responsibility:

• when the value is a string, binary, or array value — you are responsible for freeing the returned memory with free(3) 🧚
• when the value is an nvlist — you are responsible for destroying the returned nvlist with nvlist_destroy() 🌸
• when the value is a descriptor — you are responsible for closing the returned descriptor with close(2) ✨

---

👀 SEE ALSO 👀

close(2), free(3), nv(9) — go read them, iykyk 📖

---

📜 HISTORY 📜

the dnv API appeared in FreeBSD 11.0. a classic. a legend. ⭐

---

👑 AUTHORS 👑

the dnv API was implemented by Pawel Jakub Dawidek <pawel@dawidek.net> under sponsorship from the FreeBSD Foundation. 🫶

this manual page was written by Adam Starak <starak.adam@gmail.com>. 🎀

---

and that's the whole page bestie!! 🌈✨ this Debian build is dated July 26, 2016 and it ships as part of the DNV(9) page in the Kernel Developer's Manual — now go forth and get those name/value pairs 💖🦋🌸