Changeset View
Changeset View
Standalone View
Standalone View
share/man/man9/getenv.9
Show All 21 Lines | |||||
.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) | .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) | ||||
.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT | .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT | ||||
.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY | .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY | ||||
.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF | .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF | ||||
.\" SUCH DAMAGE. | .\" SUCH DAMAGE. | ||||
.\" | .\" | ||||
.\" $FreeBSD$ | .\" $FreeBSD$ | ||||
.\" | .\" | ||||
.Dd June 1, 2017 | .Dd August 31, 2020 | ||||
.Dt GETENV 9 | .Dt GETENV 9 | ||||
.Os | .Os | ||||
.Sh NAME | .Sh NAME | ||||
.Nm freeenv , | .Nm freeenv , | ||||
.Nm kern_getenv , | .Nm kern_getenv , | ||||
.Nm getenv_int , | .Nm getenv_int , | ||||
.Nm getenv_long , | .Nm getenv_long , | ||||
.Nm getenv_string , | .Nm getenv_string , | ||||
.Nm getenv_quad , | .Nm getenv_quad , | ||||
.Nm getenv_uint , | .Nm getenv_uint , | ||||
.Nm getenv_ulong , | .Nm getenv_ulong , | ||||
.Nm getenv_is_true , | |||||
.Nm getenv_is_false , | |||||
.Nm kern_setenv , | .Nm kern_setenv , | ||||
.Nm testenv , | .Nm testenv , | ||||
.Nm kern_unsetenv | .Nm kern_unsetenv | ||||
.Nd kernel environment variable functions | .Nd kernel environment variable functions | ||||
.Sh SYNOPSIS | .Sh SYNOPSIS | ||||
.In sys/param.h | .In sys/param.h | ||||
.In sys/systm.h | .In sys/systm.h | ||||
.Ft void | .Ft void | ||||
.Fn freeenv "char *env" | .Fn freeenv "char *env" | ||||
.Ft char * | .Ft char * | ||||
.Fn kern_getenv "const char *name" | .Fn kern_getenv "const char *name" | ||||
.Ft int | .Ft int | ||||
.Fn getenv_int "const char *name" "int *data" | .Fn getenv_int "const char *name" "int *data" | ||||
.Ft int | .Ft int | ||||
.Fn getenv_long "const char *name" "long *data" | .Fn getenv_long "const char *name" "long *data" | ||||
.Ft int | .Ft int | ||||
.Fn getenv_string "const char *name" "char *data" "int size" | .Fn getenv_string "const char *name" "char *data" "int size" | ||||
.Ft int | .Ft int | ||||
.Fn getenv_quad "const char *name" "quad_t *data" | .Fn getenv_quad "const char *name" "quad_t *data" | ||||
.Ft int | .Ft int | ||||
.Fn getenv_uint "const char *name" "unsigned int *data" | .Fn getenv_uint "const char *name" "unsigned int *data" | ||||
.Ft int | .Ft int | ||||
.Fn getenv_ulong "const char *name" "unsigned long *data" | .Fn getenv_ulong "const char *name" "unsigned long *data" | ||||
.Ft bool | |||||
.Fn getenv_is_true "const char *name" | |||||
.Ft bool | |||||
.Fn getenv_is_false "const char *name" | |||||
.Ft int | .Ft int | ||||
.Fn kern_setenv "const char *name" "const char *value" | .Fn kern_setenv "const char *name" "const char *value" | ||||
.Ft int | .Ft int | ||||
.Fn testenv "const char *name" | .Fn testenv "const char *name" | ||||
.Ft int | .Ft int | ||||
.Fn kern_unsetenv "const char *name" | .Fn kern_unsetenv "const char *name" | ||||
.Sh DESCRIPTION | .Sh DESCRIPTION | ||||
These functions set, unset, fetch, and parse variables from the kernel's | These functions set, unset, fetch, and parse variables from the kernel's | ||||
▲ Show 20 Lines • Show All 116 Lines • ▼ Show 20 Lines | |||||
If the variable does not exist, | If the variable does not exist, | ||||
zero is returned. | zero is returned. | ||||
If the variable exists, | If the variable exists, | ||||
up to | up to | ||||
.Fa size - 1 | .Fa size - 1 | ||||
characters of its value are copied to the buffer pointed to by | characters of its value are copied to the buffer pointed to by | ||||
.Fa data | .Fa data | ||||
followed by a null character and a non-zero value is returned. | followed by a null character and a non-zero value is returned. | ||||
.Pp | |||||
The | |||||
.Fn getenv_is_true | |||||
and | |||||
.Fn getenv_is_false | |||||
functions are wrappers around | |||||
.Fn kern_getenv | |||||
that simplify the parsing of boolean values. | |||||
The | |||||
.Fn getenv_is_true | |||||
function performs a case-insensitive comparison of the value of the kernel | |||||
environment variable | |||||
.Fa name | |||||
to the strings "1" and "true". | |||||
mhorne: Is there a preferred way to represent string literals in mdoc? | |||||
The | |||||
.Fn getenv_is_false | |||||
function works similarly for the values "0" and "false". | |||||
.Sh RETURN VALUES | .Sh RETURN VALUES | ||||
The | The | ||||
.Fn kern_getenv | .Fn kern_getenv | ||||
function returns a pointer to an environment variable's value on success or | function returns a pointer to an environment variable's value on success or | ||||
.Dv NULL | .Dv NULL | ||||
if the variable does not exist. | if the variable does not exist. | ||||
.Pp | .Pp | ||||
The | The | ||||
.Fn kern_setenv | .Fn kern_setenv | ||||
and | and | ||||
.Fn kern_unsetenv | .Fn kern_unsetenv | ||||
functions return zero on success and -1 on failure. | functions return zero on success and -1 on failure. | ||||
.Pp | .Pp | ||||
The | The | ||||
.Fn testenv | .Fn testenv | ||||
function returns zero if the specified environment variable does not exist and | function returns zero if the specified environment variable does not exist and | ||||
a non-zero value if it does exist. | a non-zero value if it does exist. | ||||
.Pp | |||||
The | The | ||||
.Fn getenv_int , | .Fn getenv_int , | ||||
.Fn getenv_long , | .Fn getenv_long , | ||||
.Fn getenv_string , | .Fn getenv_string , | ||||
.Fn getenv_quad , | .Fn getenv_quad , | ||||
.Fn getenv_uint , | .Fn getenv_uint , | ||||
and | and | ||||
.Fn getenv_ulong | .Fn getenv_ulong | ||||
functions return a non-zero value on success and zero on failure. | functions return a non-zero value on success and zero on failure. | ||||
.Pp | |||||
The | |||||
.Fn getenv_is_true | |||||
and | |||||
.Fn getenv_is_false | |||||
functions return | |||||
.Dv true | |||||
if the specified environment variable exists and its value matches the desired | |||||
boolean condition, and | |||||
.Dv false | |||||
otherwise. |
Is there a preferred way to represent string literals in mdoc?