1.\" -*- nroff -*- 2.\" 3.\" Copyright (c) 2013 Hudson River Trading LLC 4.\" Written by: John H. Baldwin <jhb@FreeBSD.org> 5.\" All rights reserved. 6.\" 7.\" Redistribution and use in source and binary forms, with or without 8.\" modification, are permitted provided that the following conditions 9.\" are met: 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. 15.\" 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 26.\" SUCH DAMAGE. 27.\" 28.Dd September 21, 2020 29.Dt GETENV 9 30.Os 31.Sh NAME 32.Nm freeenv , 33.Nm kern_getenv , 34.Nm getenv_int , 35.Nm getenv_long , 36.Nm getenv_string , 37.Nm getenv_quad , 38.Nm getenv_uint , 39.Nm getenv_ulong , 40.Nm getenv_bool , 41.Nm getenv_is_true , 42.Nm getenv_is_false , 43.Nm kern_setenv , 44.Nm testenv , 45.Nm kern_unsetenv 46.Nd kernel environment variable functions 47.Sh SYNOPSIS 48.In sys/param.h 49.In sys/systm.h 50.Ft void 51.Fn freeenv "char *env" 52.Ft char * 53.Fn kern_getenv "const char *name" 54.Ft int 55.Fn getenv_int "const char *name" "int *data" 56.Ft int 57.Fn getenv_long "const char *name" "long *data" 58.Ft int 59.Fn getenv_string "const char *name" "char *data" "int size" 60.Ft int 61.Fn getenv_quad "const char *name" "quad_t *data" 62.Ft int 63.Fn getenv_uint "const char *name" "unsigned int *data" 64.Ft int 65.Fn getenv_ulong "const char *name" "unsigned long *data" 66.Ft int 67.Fn getenv_bool "const char *name" "bool *data" 68.Ft bool 69.Fn getenv_is_true "const char *name" 70.Ft bool 71.Fn getenv_is_false "const char *name" 72.Ft int 73.Fn kern_setenv "const char *name" "const char *value" 74.Ft int 75.Fn testenv "const char *name" 76.Ft int 77.Fn kern_unsetenv "const char *name" 78.Sh DESCRIPTION 79These functions set, unset, fetch, and parse variables from the kernel's 80environment. 81.Pp 82The 83.Fn kern_getenv 84function obtains the current value of the kernel environment variable 85.Fa name 86and returns a pointer to the string value. 87The caller should not modify the string pointed to by the return value. 88The 89.Fn kern_getenv 90function may allocate temporary storage, 91so the 92.Fn freeenv 93function must be called to release any allocated resources when the value 94returned by 95.Fn kern_getenv 96is no longer needed. 97.Pp 98The 99.Fn freeenv 100function is used to release the resources allocated by a previous call to 101.Fn kern_getenv . 102The 103.Fa env 104argument passed to 105.Fn freeenv 106is the pointer returned by the earlier call to 107.Fn kern_getenv . 108Like 109.Xr free 3 , 110the 111.Fa env 112argument can be 113.Va NULL , 114in which case no action occurs. 115.Pp 116The 117.Fn kern_setenv 118function inserts or resets the kernel environment variable 119.Fa name 120to 121.Fa value . 122If the variable 123.Fa name 124already exists, 125its value is replaced. 126This function can fail if an internal limit on the number of environment 127variables is exceeded. 128.Pp 129The 130.Fn kern_unsetenv 131function deletes the kernel environment variable 132.Fa name . 133.Pp 134The 135.Fn testenv 136function is used to determine if a kernel environment variable exists. 137It returns a non-zero value if the variable 138.Fa name 139exists and zero if it does not. 140.Pp 141The 142.Fn getenv_int , 143.Fn getenv_long , 144.Fn getenv_quad , 145.Fn getenv_uint , 146and 147.Fn getenv_ulong 148functions look for a kernel environment variable 149.Fa name 150and parse it as a signed integer, 151long integer, 152signed 64-bit integer, 153unsigned integer, 154or an unsigned long integer, 155respectively. 156These functions fail and return zero if 157.Fa name 158does not exist or if any invalid characters are present in its value. 159On success, 160these function store the parsed value in the integer variable pointed to 161by 162.Fa data . 163If the parsed value overflows the integer type, 164a truncated value is stored in 165.Fa data 166and zero is returned. 167If the value begins with a prefix of 168.Dq 0x 169it is interpreted as hexadecimal. 170If it begins with a prefix of 171.Dq 0 172it is interpreted as octal. 173Otherwise, 174the value is interpreted as decimal. 175The value may contain a single character suffix specifying a unit for 176the value. 177The interpreted value is multiplied by the unit's magnitude before being 178returned. 179The following unit suffixes are supported: 180.Bl -column -offset indent ".Sy Unit" ".Sy Magnitude" 181.It Sy Unit Ta Sy Magnitude 182.It k Ta 2^10 183.It m Ta 2^20 184.It g Ta 2^30 185.It t Ta 2^40 186.El 187.Pp 188The 189.Fn getenv_string 190function stores a copy of the kernel environment variable 191.Fa name 192in the buffer described by 193.Fa data 194and 195.Fa size . 196If the variable does not exist, 197zero is returned. 198If the variable exists, 199up to 200.Fa size - 1 201characters of its value are copied to the buffer pointed to by 202.Fa data 203followed by a null character and a non-zero value is returned. 204.Pp 205The 206.Fn getenv_bool 207function interprets the value of the kernel environment variable 208.Fa name 209as a boolean value by performing a case-insensitive comparison against the 210strings "1", 211"0", 212"true", 213and "false". 214If the environment variable exists and has a valid boolean value, then that 215value will be copied to the variable pointed to by 216.Fa data . 217If the environment variable exists but is not a boolean value, then a warning 218will be printed to the kernel message buffer. 219The 220.Fn getenv_is_true 221and 222.Fn getenv_is_false 223functions are wrappers around 224.Fn getenv_bool 225that simplify testing for a desired boolean value. 226.Sh RETURN VALUES 227The 228.Fn kern_getenv 229function returns a pointer to an environment variable's value on success or 230.Dv NULL 231if the variable does not exist. 232.Pp 233The 234.Fn kern_setenv 235and 236.Fn kern_unsetenv 237functions return zero on success and -1 on failure. 238.Pp 239The 240.Fn testenv 241function returns zero if the specified environment variable does not exist and 242a non-zero value if it does exist. 243.Pp 244The 245.Fn getenv_int , 246.Fn getenv_long , 247.Fn getenv_string , 248.Fn getenv_quad , 249.Fn getenv_uint , 250.Fn getenv_ulong , 251and 252.Fn getenv_bool 253functions return a non-zero value on success and zero on failure. 254.Pp 255The 256.Fn getenv_is_true 257and 258.Fn getenv_is_false 259functions return 260.Dv true 261if the specified environment variable exists and its value matches the desired 262boolean condition, and 263.Dv false 264otherwise. 265