CNV(9)

💅 CNV(9) 💅

okay bestie, welcome to the Kernel Developer's Manual page for cnvlist_get, cnvlist_take, and cnvlist_free — the whole "manage name/value pairs by cookie" situation. yes, cookies. not the edible kind 😭 but honestly still iconic.

---

✨ NAME ✨

cnvlist_get, cnvlist_take, cnvlist_free — the API for managing name/value pairs by cookie 🍪

---

📚 LIBRARY 📚

library “libnv” — that's the one, no cap.

---

🌸 SYNOPSIS 🌸

#include <sys/cnv.h>

const char *
cnvlist_name(const void *cookie);

int
cnvlist_type(const void *cookie);

bool
cnvlist_get_bool(const void *cookie);

uint64_t
cnvlist_get_number(const void *cookie);

const char *
cnvlist_get_string(const void *cookie);

const nvlist_t *
cnvlist_get_nvlist(const void *cookie);

const void *
cnvlist_get_binary(const void *cookie, size_t *sizep);

const bool *
cnvlist_get_bool_array(const void *cookie, size_t *nitemsp);

const uint64_t *
cnvlist_get_number_array(const void *cookie, size_t *nitemsp);

const char * const *
cnvlist_get_string_array(const void *cookie, size_t *nitemsp);

const nvlist_t * const *
cnvlist_get_nvlist_array(const void *cookie, size_t *nitemsp);

int
cnvlist_get_descriptor(const void *cookie);

const int *
cnvlist_get_descriptor_array(const void *cookie, size_t *nitemsp);

bool
cnvlist_take_bool(void *cookie);

uint64_t
cnvlist_take_number(void *cookie);

const char *
cnvlist_take_string(void *cookie);

const nvlist_t *
cnvlist_take_nvlist(void *cookie);

const void *
cnvlist_take_binary(void *cookie, size_t *sizep);

const bool *
cnvlist_take_bool_array(void *cookie, size_t *nitemsp);

const uint64_t *
cnvlist_take_number_array(void *cookie, size_t *nitemsp);

const char * const *
cnvlist_take_string_array(void *cookie, size_t *nitemsp);

const nvlist_t * const *
cnvlist_take_nvlist_array(void *cookie, size_t *nitemsp);

int
cnvlist_take_descriptor(void *cookie);

const int *
cnvlist_take_descriptor_array(void *cookie, size_t *nitemsp);

void
cnvlist_free_null(void *cookie);

void
cnvlist_free_bool(void *cookie);

void
cnvlist_free_number(void *cookie);

void
cnvlist_free_string(void *cookie);

void
cnvlist_free_nvlist(void *cookie);

void
cnvlist_free_descriptor(void *cookie);

void
cnvlist_free_binary(void *cookie);

void
cnvlist_free_bool_array(void *cookie);

void
cnvlist_free_number_array(void *cookie);

void
cnvlist_free_string_array(void *cookie);

void
cnvlist_free_nvlist_array(void *cookie);

void
cnvlist_free_descriptor_array(void *cookie);

---

🎀 DESCRIPTION 🎀

so the libnv library is literally the easiest way to manage name/value pairs, and it can also send and receive them over sockets 🔥. more deets over in nv(9), mwah.

and the whole "cookies" concept? that's explained in nvlist_next(), nvlist_get_parent(), and nvlist_get_pararr() from nv(9). go read those, iykyk 🫶

---

🦋 the getters 🦋

• cnvlist_name() — returns the name of the element chillin' with cookie. like a little name tag at a party 🎀
• cnvlist_type() — returns the type of the element associated with cookie. all the possible types that can come back are described in nv(9). vibe check on the element, basically ✨
• the cnvlist_get functions — these return the value associated with cookie. and bestie, listen: any returned strings, nvlists, descriptors, binaries, or arrays must not be modified by the user, because they still belong to the nvlist 💅. also the nvlist must not be in an error state. periodt.

---

🔥 the take functions 🔥

• the cnvlist_take functions — they return the value associated with the given cookie and remove the element from the nvlist. main character behaviour, honestly. and because ownership literally changes hands:
  • if the value is a string, binary, or array value, you (the caller) are responsible for freeing the returned memory with free(3) 🗑️
  • if the value is an nvlist, you are responsible for destroying the returned nvlist with nvlist_destroy()
  • if the value is a descriptor, you are responsible for closing the returned descriptor with close(2)

no returns, no take-backs — it's yours now, you own it 💖

---

💀 the free functions 💀

• the cnvlist_free functions — they remove the element identified by cookie and free any associated resources. clean, cute, done.

⚠️ but okay, warning time: if the element identified by cookie has the wrong type or does not exist, the program aborts. like, full on yeets itself 😭 not a drill, be careful.

---

🧚 EXAMPLES 🧚

here's a little demo of how to deal with the cnvlist API. copy it, love it, run it 🍓

int type;
void *cookie, *scookie, *bcookie;
nvlist_t *nvl;
char *name;

nvl = nvlist_create(0);
nvlist_add_bool(nvl, "test", 1 == 2);
nvlist_add_string(nvl, "test2", "cnvlist");
cookie = NULL;

while (nvlist_next(nvl, &type, &cookie) != NULL) {
    switch (type) {
    case NV_TYPE_BOOL:
        printf("test: %d\n", cnvlist_get_bool(cookie));
        bcookie = cookie;
        break;
    case NV_TYPE_STRING:
        printf("test2: %s\n", cnvlist_get_string(cookie));
        scookie = cookie;
        break;
    }
}

name = cnvlist_take_string(scookie);
cnvlist_free_bool(bcookie);

printf("test2: %s\n", name);
free(name);

printf("nvlist_empty = %d\n", nvlist_empty(nvl));
nvlist_destroy(nvl);

return (0);

---

🌈 SEE ALSO 🌈

close(2), free(3), nv(9) — go read 'em, they're all lowkey essential 🫶

---

👑 AUTHORS 👑

the cnv API was created during the Google Summer Of Code 2016 by Adam Starak. king behaviour, honestly 👑✨

---

and that's the whole page, bestie 🎀💖 this one came from Debian, dated January 3, 2025 — slay, go write some cookies 🍪💅