NAME

       freeenv,  getenv, getenv_int, getenv_long, getenv_string, getenv_quad, getenv_uint, getenv_ulong, setenv,
       testenv, unsetenv — kernel environment 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 caller 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 freeenv() function is used to release the resources allocated by a previous call  to  getenv().   The
       env  argument passed to freeenv() is the pointer returned by the earlier call to getenv().  Like free(3),
       the env argument can be NULL, in which case no action occurs.

       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 functions 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
       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:

             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 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  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.

Debian                                          October 22, 2015                                       GETENV(9)