KENV(9)

NAME
kfreeenv, kgetenv, kgetenv_int, kgetenv_quad, kgetenv_string, kgetenv_ulong, ksetenv, ktestenv, kunsetenv - API for manipulation of the kernel environment

SYNOPSIS
#include <sys/systm.h>
void
kfreeenv(char *env);
char *
kgetenv(const char *name);
int
kgetenv_int(const char *name, int *data);
int
kgetenv_quad(const char *name, quad_t *data);
int
kgetenv_string(const char *name, char *data, int size);
int
kgetenv_ulong(const char *name, unsigned long *data);
int
ksetenv(const char *name, const char *value);
int
ktestenv(const char *name);
int
kunsetenv(const char *name);

DESCRIPTION
kenv provides an API for manipulation of the kernel environment of a live system by “consumers” (other kernel subsystems). Upon boot, the kernel environment is inherited from loader(8). The static environment inherited is converted to a dynamic array at the end of the kmem subsystem configure phase of the kernel booting process.

The kfreeenv() function reclaims an array of characters earlier allocated by one of the kgetenv() functions for use by the caller.

The kgetenv*() functions look up a given entry in the kernel environment, and return it if found. The kgetenv_int(), kgetenv_quad(), kgetenv_string(), and kgetenv_ulong() functions return 0 if unsuccessful, 1 if successful, and return the found value in the given destination.

The kgetenv() function returns the value string or NULL if it failed.

The ksetenv() function sets a given environment key to the given value. It returns -1 if either the name or value arguments were too large, the maxmimum number of entries in the dynamic environment was reached, or if the dynamic environment was not setup yet. The latter can happen when calling ksetenv() before the kmem subsystem is initialized.

The ktestenv() function tests whether a given key exists in the kernel environment, returning 1 if it does and 0 if it does not.

The kunsetenv() function removes a given key and its associated value from the dynamic kernel environment. It returns -1 if the key does not exist, or if the dynamic was not setup yet. If successful, it returns 0.

SYSCTLS

kern.environment
    Current static kernel environment query OID.

FILES

sys/kern/kern_environment.c

SEE ALSO
sysctl(3), loader.conf(5), loader(8), sysctl(8)

HISTORY
A getenv() function first appeared in FreeBSD 3.0, getenv_int() in FreeBSD 3.1, getenv_quad() in FreeBSD 3.4, getenv_string() in FreeBSD 4.5 and other functions first appeared in FreeBSD 5.0 and subsequently DragonFly 1.7.

AUTHORS
-nosplit The original kenv implementation was written by Michael Smith. It was subsequently extended by Matt Jacob, John Baldwin and Maxime Henrion. This manual page was written by Thomas E. Spanjaard.

BUGS
The kern.environment sysctl OID currently only reports information about the static kernel environment, not the dynamic one.

The return values from various functions could do with some standardisation, using the error codes from <sys/errno.h>.