GETENV(9) BSD Kernel Developer's Manual GETENV(9)
NAME
freeenv, getenv, getenv_int, getenv_long, getenv_string, getenv_quad, getenv_uint, getenv_ulong, setenv, testenv, unsetenv -- kernel environ-
ment variable functions
SYNOPSIS
#include <sys/param.h>
#include <sys/systm.h>
void
freeenv(char *env);
char *
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
setenv(const char *name, const char *value);
int
testenv(const char *name);
int
unsetenv(const char *name);
DESCRIPTION
These functions set, unset, fetch, and parse variables from the kernel's environment.
The getenv() function obtains the current value of the kernel environment variable name and returns a pointer to the string value. The call-
er should not modify the string pointed to by the return value.
The getenv() function may allocate temporary storage, so the freeenv() function must be called to release any allocated resources when the
value returned by getenv() is no longer needed. The env argument passed to freeenv() is the pointer returned by the earlier call to
getenv().
The setenv() function inserts or resets the kernel environment variable name to value. If the variable name already exists, its value is
replaced. This function can fail if an internal limit on the number of environment variables is exceeded.
The unsetenv() function deletes the kernel environment variable name.
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.
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 func-
tions fail and return zero if name does not exist or if any invalid characters are present in its value. On success, these function 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. 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 specify-
ing a unit for the value. The interpreted value is multipled by the unit's magnitude before being returned. The following unit suffixes are
supported:
Unit Magnitude
k 2^10
m 2^20
g 2^30
t 2^40
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 it's 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 getenv() function returns a pointer to an environment variable's value on success or NULL if the variable does not exist.
The setenv() and 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.
BSD
October 22, 2013 BSD