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
45 .Nd kernel environment variable functions
50 .Fn freeenv "char *env"
52 .Fn kern_getenv "const char *name"
54 .Fn getenv_int "const char *name" "int *data"
56 .Fn getenv_long "const char *name" "long *data"
58 .Fn getenv_string "const char *name" "char *data" "int size"
60 .Fn getenv_quad "const char *name" "quad_t *data"
62 .Fn getenv_uint "const char *name" "unsigned int *data"
64 .Fn getenv_ulong "const char *name" "unsigned long *data"
66 .Fn kern_setenv "const char *name" "const char *value"
68 .Fn testenv "const char *name"
70 .Fn kern_unsetenv "const char *name"
72 These functions set, unset, fetch, and parse variables from the kernel's
77 function obtains the current value of the kernel environment variable
79 and returns a pointer to the string value.
80 The caller should not modify the string pointed to by the return value.
83 function may allocate temporary storage,
86 function must be called to release any allocated resources when the value
93 function is used to release the resources allocated by a previous call to
99 is the pointer returned by the earlier call to
107 in which case no action occurs.
111 function inserts or resets the kernel environment variable
118 its value is replaced.
119 This function can fail if an internal limit on the number of environment
120 variables is exceeded.
124 function deletes the kernel environment variable
129 function is used to determine if a kernel environment variable exists.
130 It returns a non-zero value if the variable
132 exists and zero if it does not.
141 functions look for a kernel environment variable
143 and parse it as a signed integer,
145 signed 64-bit integer,
147 or an unsigned long integer,
149 These functions fail and return zero if
151 does not exist or if any invalid characters are present in its value.
153 these function store the parsed value in the integer variable pointed to
156 If the parsed value overflows the integer type,
157 a truncated value is stored in
159 and zero is returned.
160 If the value begins with a prefix of
162 it is interpreted as hexadecimal.
163 If it begins with a prefix of
165 it is interpreted as octal.
167 the value is interpreted as decimal.
168 The value may contain a single character suffix specifying a unit for
170 The interpreted value is multiplied by the unit's magnitude before being
172 The following unit suffixes are supported:
173 .Bl -column -offset indent ".Sy Unit" ".Sy Magnitude"
174 .It Sy Unit Ta Sy Magnitude
183 function stores a copy of the kernel environment variable
185 in the buffer described by
189 If the variable does not exist,
191 If the variable exists,
194 characters of its value are copied to the buffer pointed to by
196 followed by a null character and a non-zero value is returned.
200 function returns a pointer to an environment variable's value on success or
202 if the variable does not exist.
208 functions return zero on success and -1 on failure.
212 function returns zero if the specified environment variable does not exist and
213 a non-zero value if it does exist.
222 functions return a non-zero value on success and zero on failure.