1.\" -*- nroff -*- 2.\" 3.\" Copyright (c) 2013 Advanced Computing Technologies 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 October 22, 2013 31.Dt GETENV 9 32.Os 33.Sh NAME 34.Nm freeenv , 35.Nm 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 setenv , 43.Nm testenv , 44.Nm unsetenv 45.Nd kernel environment variable functions 46.Sh SYNOPSIS 47.In sys/param.h 48.In sys/systm.h 49.Ft void 50.Fn freeenv "char *env" 51.Ft char * 52.Fn getenv "const char *name" 53.Ft int 54.Fn getenv_int "const char *name" "int *data" 55.Ft int 56.Fn getenv_long "const char *name" "long *data" 57.Ft int 58.Fn getenv_string "const char *name" "char *data" "int size" 59.Ft int 60.Fn getenv_quad "const char *name" "quad_t *data" 61.Ft int 62.Fn getenv_uint "const char *name" "unsigned int *data" 63.Ft int 64.Fn getenv_ulong "const char *name" "unsigned long *data" 65.Ft int 66.Fn setenv "const char *name" "const char *value" 67.Ft int 68.Fn testenv "const char *name" 69.Ft int 70.Fn unsetenv "const char *name" 71.Sh DESCRIPTION 72These functions set, unset, fetch, and parse variables from the kernel's 73environment. 74.Pp 75The 76.Fn getenv 77function obtains the current value of the kernel environment variable 78.Fa name 79and returns a pointer to the string value. 80The caller should not modify the string pointed to by the return value. 81.Pp 82The 83.Fn getenv 84function may allocate temporary storage, 85so the 86.Fn freeenv 87function must be called to release any allocated resources when the value 88returned by 89.Fn getenv 90is no longer needed. 91The 92.Fa env 93argument passed to 94.Fn freeenv 95is the pointer returned by the earlier call to 96.Fn getenv . 97.Pp 98The 99.Fn setenv 100function inserts or resets the kernel environment variable 101.Fa name 102to 103.Fa value . 104If the variable 105.Fa name 106already exists, 107its value is replaced. 108This function can fail if an internal limit on the number of environment 109variables is exceeded. 110.Pp 111The 112.Fn unsetenv 113function deletes the kernel environment variable 114.Fa name . 115.Pp 116The 117.Fn testenv 118function is used to determine if a kernel environment variable exists. 119It returns a non-zero value if the variable 120.Fa name 121exists and zero if it does not. 122.Pp 123The 124.Fn getenv_int , 125.Fn getenv_long , 126.Fn getenv_quad , 127.Fn getenv_uint , 128and 129.Fn getenv_ulong 130functions look for a kernel environment variable 131.Fa name 132and parse it as a signed integer, 133long integer, 134signed 64-bit integer, 135unsigned integer, 136or an unsigned long integer, 137respectively. 138These functions fail and return zero if 139.Fa name 140does not exist or if any invalid characters are present in its value. 141On success, 142these function store the parsed value in the integer variable pointed to 143by 144.Fa data . 145If the parsed value overflows the integer type, 146a truncated value is stored in 147.Fa data 148and zero is returned. 149If the value begins with a prefix of 150.Dq 0x 151it is interpreted as hexadecimal. 152If it begins with a prefix of 153.Dq 0 154it is interpreted as octal. 155Otherwise, 156the value is interpreted as decimal. 157The value may contain a single character suffix specifying a unit for 158the value. 159The interpreted value is multipled by the unit's magnitude before being returned. 160The following unit suffixes are supported: 161.Bl -column -offset indent ".Sy Unit" ".Sy Magnitude" 162.It Sy Unit Ta Sy Magnitude 163.It k Ta 2^10 164.It m Ta 2^20 165.It g Ta 2^30 166.It t Ta 2^40 167.El 168.Pp 169The 170.Fn getenv_string 171function stores a copy of the kernel environment variable 172.Fa name 173in the buffer described by 174.Fa data 175and 176.Fa size. 177If the variable does not exist, 178zero is returned. 179If the variable exists, 180up to 181.Fa size - 1 182characters of it's value are copied to the buffer pointed to by 183.Fa data 184followed by a null character and a non-zero value is returned. 185.Sh RETURN VALUES 186The 187.Fn getenv 188function returns a pointer to an environment variable's value on success or 189.Dv NULL 190if the variable does not exist. 191.Pp 192The 193.Fn setenv 194and 195.Fn unsetenv 196functions return zero on success and -1 on failure. 197.Pp 198The 199.Fn testenv 200function returns zero if the specified environment variable does not exist and 201a non-zero value if it does exist. 202The 203.Fn getenv_int , 204.Fn getenv_long , 205.Fn getenv_string , 206.Fn getenv_quad , 207.Fn getenv_uint , 208and 209.Fn getenv_ulong 210functions return a non-zero value on success and zero on failure. 211