3 .\" Copyright (c) 2013 Hudson River Trading LLC
4 .\" Written by: John H. Baldwin <jhb@FreeBSD.org>
5 .\" All rights reserved.
7 .\" Redistribution and use in source and binary forms, with or without
8 .\" modification, are permitted provided that the following conditions
10 .\" 1. Redistributions of source code must retain the above copyright
11 .\" notice, this list of conditions and the following disclaimer.
12 .\" 2. Redistributions in binary form must reproduce the above copyright
13 .\" notice, this list of conditions and the following disclaimer in the
14 .\" documentation and/or other materials provided with the distribution.
16 .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
17 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
18 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
19 .\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
20 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
21 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
22 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
23 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
24 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
25 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
30 .Dd September 21, 2020
48 .Nd kernel environment variable functions
53 .Fn freeenv "char *env"
55 .Fn kern_getenv "const char *name"
57 .Fn getenv_int "const char *name" "int *data"
59 .Fn getenv_long "const char *name" "long *data"
61 .Fn getenv_string "const char *name" "char *data" "int size"
63 .Fn getenv_quad "const char *name" "quad_t *data"
65 .Fn getenv_uint "const char *name" "unsigned int *data"
67 .Fn getenv_ulong "const char *name" "unsigned long *data"
69 .Fn getenv_bool "const char *name" "bool *data"
71 .Fn getenv_is_true "const char *name"
73 .Fn getenv_is_false "const char *name"
75 .Fn kern_setenv "const char *name" "const char *value"
77 .Fn testenv "const char *name"
79 .Fn kern_unsetenv "const char *name"
81 These functions set, unset, fetch, and parse variables from the kernel's
86 function obtains the current value of the kernel environment variable
88 and returns a pointer to the string value.
89 The caller should not modify the string pointed to by the return value.
92 function may allocate temporary storage,
95 function must be called to release any allocated resources when the value
102 function is used to release the resources allocated by a previous call to
108 is the pointer returned by the earlier call to
116 in which case no action occurs.
120 function inserts or resets the kernel environment variable
127 its value is replaced.
128 This function can fail if an internal limit on the number of environment
129 variables is exceeded.
133 function deletes the kernel environment variable
138 function is used to determine if a kernel environment variable exists.
139 It returns a non-zero value if the variable
141 exists and zero if it does not.
150 functions look for a kernel environment variable
152 and parse it as a signed integer,
154 signed 64-bit integer,
156 or an unsigned long integer,
158 These functions fail and return zero if
160 does not exist or if any invalid characters are present in its value.
162 these function store the parsed value in the integer variable pointed to
165 If the parsed value overflows the integer type,
166 a truncated value is stored in
168 and zero is returned.
169 If the value begins with a prefix of
171 it is interpreted as hexadecimal.
172 If it begins with a prefix of
174 it is interpreted as octal.
176 the value is interpreted as decimal.
177 The value may contain a single character suffix specifying a unit for
179 The interpreted value is multiplied by the unit's magnitude before being
181 The following unit suffixes are supported:
182 .Bl -column -offset indent ".Sy Unit" ".Sy Magnitude"
183 .It Sy Unit Ta Sy Magnitude
192 function stores a copy of the kernel environment variable
194 in the buffer described by
198 If the variable does not exist,
200 If the variable exists,
203 characters of its value are copied to the buffer pointed to by
205 followed by a null character and a non-zero value is returned.
209 function interprets the value of the kernel environment variable
211 as a boolean value by performing a case-insensitive comparison against the
216 If the environment variable exists and has a valid boolean value, then that
217 value will be copied to the variable pointed to by
219 If the environment variable exists but is not a boolean value, then a warning
220 will be printed to the kernel message buffer.
225 functions are wrappers around
227 that simplify testing for a desired boolean value.
231 function returns a pointer to an environment variable's value on success or
233 if the variable does not exist.
239 functions return zero on success and -1 on failure.
243 function returns zero if the specified environment variable does not exist and
244 a non-zero value if it does exist.
255 functions return a non-zero value on success and zero on failure.
263 if the specified environment variable exists and its value matches the desired
264 boolean condition, and