share/man/man9/getenv.9

   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
  72 These functions set, unset, fetch, and parse variables from the kernel's
  73 environment.
  74 .Pp
  75 The
  76 .Fn 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 .Pp
  82 The
  83 .Fn getenv
  84 function may allocate temporary storage,
  85 so the
  86 .Fn freeenv
  87 function must be called to release any allocated resources when the value
  88 returned by
  89 .Fn getenv
  90 is no longer needed.
  91 The
  92 .Fa env
  93 argument passed to
  94 .Fn freeenv
  95 is the pointer returned by the earlier call to
  96 .Fn getenv .
  97 .Pp
  98 The
  99 .Fn setenv
 100 function inserts or resets the kernel environment variable
 101 .Fa name
 102 to
 103 .Fa value .
 104 If the variable
 105 .Fa name
 106 already exists,
 107 its value is replaced.
 108 This function can fail if an internal limit on the number of environment
 109 variables is exceeded.
 110 .Pp
 111 The
 112 .Fn unsetenv
 113 function deletes the kernel environment variable
 114 .Fa name .
 115 .Pp
 116 The
 117 .Fn testenv
 118 function is used to determine if a kernel environment variable exists.
 119 It returns a non-zero value if the variable
 120 .Fa name
 121 exists and zero if it does not.
 122 .Pp
 123 The
 124 .Fn getenv_int ,
 125 .Fn getenv_long ,
 126 .Fn getenv_quad ,
 127 .Fn getenv_uint ,
 128 and
 129 .Fn getenv_ulong
 130 functions look for a kernel environment variable
 131 .Fa name
 132 and parse it as a signed integer,
 133 long integer,
 134 signed 64-bit integer,
 135 unsigned integer,
 136 or an unsigned long integer,
 137 respectively.
 138 These functions fail and return zero if
 139 .Fa name
 140 does not exist or if any invalid characters are present in its value.
 141 On success,
 142 these function store the parsed value in the integer variable pointed to
 143 by
 144 .Fa data .
 145 If the parsed value overflows the integer type,
 146 a truncated value is stored in
 147 .Fa data
 148 and zero is returned.
 149 If the value begins with a prefix of
 150 .Dq 0x
 151 it is interpreted as hexadecimal.
 152 If it begins with a prefix of
 153 .Dq 0
 154 it is interpreted as octal.
 155 Otherwise,
 156 the value is interpreted as decimal.
 157 The value may contain a single character suffix specifying a unit for
 158 the value.
 159 The interpreted value is multipled by the unit's magnitude before being returned.
 160 The 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
 169 The
 170 .Fn getenv_string
 171 function stores a copy of the kernel environment variable
 172 .Fa name
 173 in the buffer described by
 174 .Fa data
 175 and
 176 .Fa size.
 177 If the variable does not exist,
 178 zero is returned.
 179 If the variable exists,
 180 up to
 181 .Fa size - 1
 182 characters of it's value are copied to the buffer pointed to by
 183 .Fa data
 184 followed by a null character and a non-zero value is returned.
 185 .Sh RETURN VALUES
 186 The
 187 .Fn getenv
 188 function returns a pointer to an environment variable's value on success or
 189 .Dv NULL
 190 if the variable does not exist.
 191 .Pp
 192 The
 193 .Fn setenv
 194 and
 195 .Fn unsetenv
 196 functions return zero on success and -1 on failure.
 197 .Pp
 198 The
 199 .Fn testenv
 200 function returns zero if the specified environment variable does not exist and
 201 a non-zero value if it does exist.
 202 The
 203 .Fn getenv_int ,
 204 .Fn getenv_long ,
 205 .Fn getenv_string ,
 206 .Fn getenv_quad ,
 207 .Fn getenv_uint ,
 208 and
 209 .Fn getenv_ulong
 210 functions return a non-zero value on success and zero on failure.