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