cba446e2c2
This adds the getenv_bool() function, to parse a boolean value from a kernel environment variable or tunable. This works for traditional boolean values like "0" and "1", and also "true" and "false" (case-insensitive). These semantics do not yet apply to sysctls declared using SYSCTL_BOOL with CTLFLAG_TUN (they still only parse 1 and 0). Also added are two wrapper functions, getenv_is_true() and getenv_is_false(). These are slightly simpler for callers wishing to perform a single check of a configuration variable. Reviewed by: jhb (slightly earlier version) Sponsored by: NetApp, Inc. Sponsored by: Klara, Inc. Differential Revision: https://reviews.freebsd.org/D26270
267 lines
6.7 KiB
Groff
267 lines
6.7 KiB
Groff
.\" -*- nroff -*-
|
|
.\"
|
|
.\" 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 the following disclaimer in the
|
|
.\" documentation and/or other materials provided with the distribution.
|
|
.\"
|
|
.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
|
|
.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
|
|
.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
|
|
.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
|
|
.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
|
|
.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
|
|
.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
|
|
.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
|
|
.\" 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
|
|
.\" SUCH DAMAGE.
|
|
.\"
|
|
.\" $FreeBSD$
|
|
.\"
|
|
.Dd September 21, 2020
|
|
.Dt GETENV 9
|
|
.Os
|
|
.Sh NAME
|
|
.Nm freeenv ,
|
|
.Nm kern_getenv ,
|
|
.Nm getenv_int ,
|
|
.Nm getenv_long ,
|
|
.Nm getenv_string ,
|
|
.Nm getenv_quad ,
|
|
.Nm getenv_uint ,
|
|
.Nm getenv_ulong ,
|
|
.Nm getenv_bool ,
|
|
.Nm getenv_is_true ,
|
|
.Nm getenv_is_false ,
|
|
.Nm kern_setenv ,
|
|
.Nm testenv ,
|
|
.Nm kern_unsetenv
|
|
.Nd kernel environment variable functions
|
|
.Sh SYNOPSIS
|
|
.In sys/param.h
|
|
.In sys/systm.h
|
|
.Ft void
|
|
.Fn freeenv "char *env"
|
|
.Ft char *
|
|
.Fn kern_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 getenv_bool "const char *name" "bool *data"
|
|
.Ft bool
|
|
.Fn getenv_is_true "const char *name"
|
|
.Ft bool
|
|
.Fn getenv_is_false "const char *name"
|
|
.Ft int
|
|
.Fn kern_setenv "const char *name" "const char *value"
|
|
.Ft int
|
|
.Fn testenv "const char *name"
|
|
.Ft int
|
|
.Fn kern_unsetenv "const char *name"
|
|
.Sh DESCRIPTION
|
|
These functions set, unset, fetch, and parse variables from the kernel's
|
|
environment.
|
|
.Pp
|
|
The
|
|
.Fn kern_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 kern_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 kern_getenv
|
|
is no longer needed.
|
|
.Pp
|
|
The
|
|
.Fn freeenv
|
|
function is used to release the resources allocated by a previous call to
|
|
.Fn kern_getenv .
|
|
The
|
|
.Fa env
|
|
argument passed to
|
|
.Fn freeenv
|
|
is the pointer returned by the earlier call to
|
|
.Fn kern_getenv .
|
|
Like
|
|
.Xr free 3 ,
|
|
the
|
|
.Fa env
|
|
argument can be
|
|
.Va NULL ,
|
|
in which case no action occurs.
|
|
.Pp
|
|
The
|
|
.Fn kern_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.
|
|
.Pp
|
|
The
|
|
.Fn kern_unsetenv
|
|
function deletes the kernel environment variable
|
|
.Fa name .
|
|
.Pp
|
|
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.
|
|
.Pp
|
|
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
|
|
.Dq 0x
|
|
it is interpreted as hexadecimal.
|
|
If it begins with a prefix of
|
|
.Dq 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:
|
|
.Bl -column -offset indent ".Sy Unit" ".Sy Magnitude"
|
|
.It Sy Unit Ta Sy Magnitude
|
|
.It k Ta 2^10
|
|
.It m Ta 2^20
|
|
.It g Ta 2^30
|
|
.It t Ta 2^40
|
|
.El
|
|
.Pp
|
|
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.
|
|
.Pp
|
|
The
|
|
.Fn getenv_bool
|
|
function interprets the value of the kernel environment variable
|
|
.Fa name
|
|
as a boolean value by performing a case-insensitive comparison against the
|
|
strings "1",
|
|
"0",
|
|
"true",
|
|
and "false".
|
|
If the environment variable exists and has a valid boolean value, then that
|
|
value will be copied to the variable pointed to by
|
|
.Fa data .
|
|
If the environment variable exists but is not a boolean value, then a warning
|
|
will be printed to the kernel message buffer.
|
|
The
|
|
.Fn getenv_is_true
|
|
and
|
|
.Fn getenv_is_false
|
|
functions are wrappers around
|
|
.Fn getenv_bool
|
|
that simplify testing for a desired boolean value.
|
|
.Sh RETURN VALUES
|
|
The
|
|
.Fn kern_getenv
|
|
function returns a pointer to an environment variable's value on success or
|
|
.Dv NULL
|
|
if the variable does not exist.
|
|
.Pp
|
|
The
|
|
.Fn kern_setenv
|
|
and
|
|
.Fn kern_unsetenv
|
|
functions return zero on success and -1 on failure.
|
|
.Pp
|
|
The
|
|
.Fn testenv
|
|
function returns zero if the specified environment variable does not exist and
|
|
a non-zero value if it does exist.
|
|
.Pp
|
|
The
|
|
.Fn getenv_int ,
|
|
.Fn getenv_long ,
|
|
.Fn getenv_string ,
|
|
.Fn getenv_quad ,
|
|
.Fn getenv_uint ,
|
|
.Fn getenv_ulong ,
|
|
and
|
|
.Fn getenv_bool
|
|
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.
|