share/man/man9/getenv.9

   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
  81 These functions set, unset, fetch, and parse variables from the kernel's
  82 environment.
  83 .Pp
  84 The
  85 .Fn kern_getenv
  86 function obtains the current value of the kernel environment variable
  87 .Fa name
  88 and returns a pointer to the string value.
  89 The caller should not modify the string pointed to by the return value.
  90 The
  91 .Fn kern_getenv
  92 function may allocate temporary storage,
  93 so the
  94 .Fn freeenv
  95 function must be called to release any allocated resources when the value
  96 returned by
  97 .Fn kern_getenv
  98 is no longer needed.
  99 .Pp
 100 The
 101 .Fn freeenv
 102 function is used to release the resources allocated by a previous call to
 103 .Fn kern_getenv .
 104 The
 105 .Fa env
 106 argument passed to
 107 .Fn freeenv
 108 is the pointer returned by the earlier call to
 109 .Fn kern_getenv .
 110 Like
 111 .Xr free 3 ,
 112 the
 113 .Fa env
 114 argument can be
 115 .Va NULL ,
 116 in which case no action occurs.
 117 .Pp
 118 The
 119 .Fn kern_setenv
 120 function inserts or resets the kernel environment variable
 121 .Fa name
 122 to
 123 .Fa value .
 124 If the variable
 125 .Fa name
 126 already exists,
 127 its value is replaced.
 128 This function can fail if an internal limit on the number of environment
 129 variables is exceeded.
 130 .Pp
 131 The
 132 .Fn kern_unsetenv
 133 function deletes the kernel environment variable
 134 .Fa name .
 135 .Pp
 136 The
 137 .Fn testenv
 138 function is used to determine if a kernel environment variable exists.
 139 It returns a non-zero value if the variable
 140 .Fa name
 141 exists and zero if it does not.
 142 .Pp
 143 The
 144 .Fn getenv_int ,
 145 .Fn getenv_long ,
 146 .Fn getenv_quad ,
 147 .Fn getenv_uint ,
 148 and
 149 .Fn getenv_ulong
 150 functions look for a kernel environment variable
 151 .Fa name
 152 and parse it as a signed integer,
 153 long integer,
 154 signed 64-bit integer,
 155 unsigned integer,
 156 or an unsigned long integer,
 157 respectively.
 158 These functions fail and return zero if
 159 .Fa name
 160 does not exist or if any invalid characters are present in its value.
 161 On success,
 162 these function store the parsed value in the integer variable pointed to
 163 by
 164 .Fa data .
 165 If the parsed value overflows the integer type,
 166 a truncated value is stored in
 167 .Fa data
 168 and zero is returned.
 169 If the value begins with a prefix of
 170 .Dq 0x
 171 it is interpreted as hexadecimal.
 172 If it begins with a prefix of
 173 .Dq 0
 174 it is interpreted as octal.
 175 Otherwise,
 176 the value is interpreted as decimal.
 177 The value may contain a single character suffix specifying a unit for
 178 the value.
 179 The interpreted value is multiplied by the unit's magnitude before being
 180 returned.
 181 The 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
 190 The
 191 .Fn getenv_string
 192 function stores a copy of the kernel environment variable
 193 .Fa name
 194 in the buffer described by
 195 .Fa data
 196 and
 197 .Fa size .
 198 If the variable does not exist,
 199 zero is returned.
 200 If the variable exists,
 201 up to
 202 .Fa size - 1
 203 characters of its value are copied to the buffer pointed to by
 204 .Fa data
 205 followed by a null character and a non-zero value is returned.
 206 .Pp
 207 The
 208 .Fn getenv_bool
 209 function interprets the value of the kernel environment variable
 210 .Fa name
 211 as a boolean value by performing a case-insensitive comparison against the
 212 strings "1",
 213 "0",
 214 "true",
 215 and "false".
 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
 218 .Fa data .
 219 If the environment variable exists but is not a boolean value, then a warning
 220 will be printed to the kernel message buffer.
 221 The
 222 .Fn getenv_is_true
 223 and
 224 .Fn getenv_is_false
 225 functions are wrappers around
 226 .Fn getenv_bool
 227 that simplify testing for a desired boolean value.
 228 .Sh RETURN VALUES
 229 The
 230 .Fn kern_getenv
 231 function returns a pointer to an environment variable's value on success or
 232 .Dv NULL
 233 if the variable does not exist.
 234 .Pp
 235 The
 236 .Fn kern_setenv
 237 and
 238 .Fn kern_unsetenv
 239 functions return zero on success and -1 on failure.
 240 .Pp
 241 The
 242 .Fn testenv
 243 function returns zero if the specified environment variable does not exist and
 244 a non-zero value if it does exist.
 245 .Pp
 246 The
 247 .Fn getenv_int ,
 248 .Fn getenv_long ,
 249 .Fn getenv_string ,
 250 .Fn getenv_quad ,
 251 .Fn getenv_uint ,
 252 .Fn getenv_ulong ,
 253 and
 254 .Fn getenv_bool
 255 functions return a non-zero value on success and zero on failure.
 256 .Pp
 257 The
 258 .Fn getenv_is_true
 259 and
 260 .Fn getenv_is_false
 261 functions return
 262 .Dv true
 263 if the specified environment variable exists and its value matches the desired
 264 boolean condition, and
 265 .Dv false
 266 otherwise.