GETENV(9)

💖 GETENV — the kernel environment variable functions, bestie 💖

okay so this is a page from the Kernel Developer's Manual, section 9 (that's the kernel-functions girlies 💅), and it's all about the freeenv, kern_getenv, getenv_int, getenv_long, getenv_string, getenv_quad, getenv_uint, getenv_ulong, kern_setenv, testenv, and kern_unsetenv functions. yes, that's a lot of names, breathe, we got this 🌸

---

✨ NAME ✨

freeenv, kern_getenv, getenv_int, getenv_long, getenv_string, getenv_quad, getenv_uint, getenv_ulong, kern_setenv, testenv, kern_unsetenv — kernel environment variable functions 🫶

---

✨ SYNOPSIS ✨

first, the vibe check includes you need to bring:

#include <sys/param.h>
#include <sys/systm.h>

then the whole squad, one by one:

void
freeenv(char *env);

char *
kern_getenv(const char *name);

int
getenv_int(const char *name, int *data);

int
getenv_long(const char *name, long *data);

int
getenv_string(const char *name, char *data, int size);

int
getenv_quad(const char *name, quad_t *data);

int
getenv_uint(const char *name, unsigned int *data);

int
getenv_ulong(const char *name, unsigned long *data);

int
kern_setenv(const char *name, const char *value);

int
testenv(const char *name);

int
kern_unsetenv(const char *name);

---

✨ DESCRIPTION ✨

so like, these functions set, unset, fetch, and parse variables from the kernel's environment. that's the whole gig. it's giving backstage-pass-to-the-kernel energy 👑

💫 kern_getenv()

The kern_getenv() function obtains the current value of the kernel environment variable name and returns a pointer to the string value. 🎀

⚠️ bestie, do NOT modify the string pointed to by the return value. hands off. no touchy. 🙈

and here's the thing: kern_getenv() may allocate temporary storage, so the freeenv() function must be called to release any allocated resources when the value returned by kern_getenv() is no longer needed. yes queen, you have to clean up after yourself, it's called being a responsible main character ✨

🧹 freeenv()

The freeenv() function is used to release the resources allocated by a previous call to kern_getenv(). The env argument passed to freeenv() is the pointer returned by the earlier call to kern_getenv(). Like free(3), the env argument can be NULL, in which case no action occurs. so if you pass NULL it just... does nothing. iconic, zero drama 💅

🪄 kern_setenv()

The kern_setenv() function inserts or resets the kernel environment variable name to value. If the variable name already exists, its value is replaced. 🔥

lowkey important: this function can fail if an internal limit on the number of environment variables is exceeded. there is a cap, and you can hit it. 😭

🗑️ kern_unsetenv()

The kern_unsetenv() function deletes the kernel environment variable name. bye bestie, blocked, unfollowed, gone 🌈

🔍 testenv()

The testenv() function is used to determine if a kernel environment variable exists. It returns a non-zero value if the variable name exists and zero if it does not. literally just a yes-or-no vibe check ✅❌

🔢 the number-parsing girlies

The getenv_int(), getenv_long(), getenv_quad(), getenv_uint(), and getenv_ulong() functions look for a kernel environment variable name and parse it as a signed integer, long integer, signed 64-bit integer, unsigned integer, or an unsigned long integer, respectively. 🧮

• These functions fail and return zero if name does not exist or if any invalid characters are present in its value.
• On success, these functions store the parsed value in the integer variable pointed to by data.
• If the parsed value overflows the integer type, a truncated value is stored in data and zero is returned. (sneaky. it looks like a fail but it wrote to your buffer. stay woke 💀)

and now the base rules, because parsing is a whole aesthetic:

• If the value begins with a prefix of “0x” it is interpreted as hexadecimal.
• If it begins with a prefix of “0” it is interpreted as octal.
• Otherwise, the value is interpreted as decimal.

The value may contain a single character suffix specifying a unit for the value. The interpreted value is multiplied by the unit's magnitude before being returned. 💫

The following unit suffixes are supported:

• k — magnitude 2^10
• m — magnitude 2^20
• g — magnitude 2^30
• t — magnitude 2^40

(yes, binary magnitudes. little k is doing the heavy lifting here 🫶)

📝 getenv_string()

The getenv_string() function stores a copy of the kernel environment variable name in the buffer described by data and size.

• If the variable does not exist, zero is returned.
• If the variable exists, up to size - 1 characters of its value are copied to the buffer pointed to by data, followed by a null character, and a non-zero value is returned. ✨

---

✨ RETURN VALUES ✨

The kern_getenv() function returns a pointer to an environment variable's value on success or NULL if the variable does not exist. 🔍

The kern_setenv() and kern_unsetenv() functions return zero on success and -1 on failure. 🎯

The testenv() function returns zero if the specified environment variable does not exist and a non-zero value if it does exist. The getenv_int(), getenv_long(), getenv_string(), getenv_quad(), getenv_uint(), and getenv_ulong() functions return a non-zero value on success and zero on failure. periodt 💅

---

and that's the whole page, bestie 💖 this one came from Debian, dated June 1, 2017 — so like, a classic, but still eating fr fr. go forth and read your kernel env vars responsibly 🦋🌸✨