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