getenv_string (9)

Leading comments

Copyright (c) 2013 Hudson River Trading LLC
Written by: John H. Baldwin <jhb@FreeBSD.org>
All rights reserved.

Redistribution and use in source and binary forms, with or without
modification, are permitted provided that the following conditions
are met:
1. Redistributions of source code must retain the above copyright
   notice, this list of conditions and the following disclaimer.
2. Redistributions in binary form must reproduce the above copyright
   notice, this list of conditions and t...

(The comments found at the beginning of the groff file "man9/getenv_string.9freebsd".)

NAME

freeenv getenv getenv_int getenv_long getenv_string getenv_quad getenv_uint getenv_ulong setenv testenv unsetenv - kernel environment variable functions

SYNOPSIS

In sys/param.h In sys/systm.h Ft void Fn freeenv char *env Ft char * Fn getenv const char *name Ft int Fn getenv_int const char *name int *data Ft int Fn getenv_long const char *name long *data Ft int Fn getenv_string const char *name char *data int size Ft int Fn getenv_quad const char *name quad_t *data Ft int Fn getenv_uint const char *name unsigned int *data Ft int Fn getenv_ulong const char *name unsigned long *data Ft int Fn setenv const char *name const char *value Ft int Fn testenv const char *name Ft int Fn unsetenv const char *name

DESCRIPTION

These functions set, unset, fetch, and parse variables from the kernel's environment.

The Fn getenv function obtains the current value of the kernel environment variable Fa name and returns a pointer to the string value. The caller should not modify the string pointed to by the return value. The Fn getenv function may allocate temporary storage, so the Fn freeenv function must be called to release any allocated resources when the value returned by Fn getenv is no longer needed.

The Fn freeenv function is used to release the resources allocated by a previous call to Fn getenv . The Fa env argument passed to Fn freeenv is the pointer returned by the earlier call to Fn getenv . Like free(3), the Fa env argument can be NULL in which case no action occurs.

The Fn setenv function inserts or resets the kernel environment variable Fa name to Fa value . If the variable Fa name already exists, its value is replaced. This function can fail if an internal limit on the number of environment variables is exceeded.

The Fn unsetenv function deletes the kernel environment variable Fa name .

The Fn testenv function is used to determine if a kernel environment variable exists. It returns a non-zero value if the variable Fa name exists and zero if it does not.

The Fn getenv_int , Fn getenv_long , Fn getenv_quad , Fn getenv_uint , and Fn getenv_ulong functions look for a kernel environment variable Fa 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 Fa 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 Fa data . If the parsed value overflows the integer type, a truncated value is stored in Fa 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 Ta Magnitude

k Ta 2^10

m Ta 2^20

g Ta 2^30

t Ta 2^40

The Fn getenv_string function stores a copy of the kernel environment variable Fa name in the buffer described by Fa data and Fa size. If the variable does not exist, zero is returned. If the variable exists, up to Fa size - 1 characters of its value are copied to the buffer pointed to by Fa data followed by a null character and a non-zero value is returned.

RETURN VALUES

The Fn getenv function returns a pointer to an environment variable's value on success or NULL if the variable does not exist.

The Fn setenv and Fn unsetenv functions return zero on success and -1 on failure.

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