share/man/man9/kenv.9

   1 .\"
   2 .\" Copyright (c) 2007 The DragonFly Project.  All rights reserved.
   3 .\"
   4 .\" Redistribution and use in source and binary forms, with or without
   5 .\" modification, are permitted provided that the following conditions
   6 .\" are met:
   7 .\"
   8 .\" 1. Redistributions of source code must retain the above copyright
   9 .\"    notice, this list of conditions and the following disclaimer.
  10 .\" 2. Redistributions in binary form must reproduce the above copyright
  11 .\"    notice, this list of conditions and the following disclaimer in
  12 .\"    the documentation and/or other materials provided with the
  13 .\"    distribution.
  14 .\" 3. Neither the name of The DragonFly Project nor the names of its
  15 .\"    contributors may be used to endorse or promote products derived
  16 .\"    from this software without specific, prior written permission.
  17 .\"
  18 .\" THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
  19 .\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
  20 .\" LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS
  21 .\" FOR A PARTICULAR PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL THE
  22 .\" COPYRIGHT HOLDERS OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT,
  23 .\" INCIDENTAL, SPECIAL, EXEMPLARY OR CONSEQUENTIAL DAMAGES (INCLUDING,
  24 .\" BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
  25 .\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED
  26 .\" AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
  27 .\" OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT
  28 .\" OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  29 .\" SUCH DAMAGE.
  30 .\"
  31 .\" $DragonFly: src/share/man/man9/kenv.9,v 1.5 2007/02/04 04:31:13 swildner Exp $
  32 .\"
  33 .Dd January 16, 2007
  34 .Dt KENV 9
  35 .Os
  36 .Sh NAME
  37 .Nm kfreeenv ,
  38 .Nm kgetenv ,
  39 .Nm kgetenv_int ,
  40 .Nm kgetenv_quad ,
  41 .Nm kgetenv_string ,
  42 .Nm ksetenv ,
  43 .Nm ktestenv ,
  44 .Nm kunsetenv
  45 .Nd API for manipulation of the kernel environment
  46 .Sh SYNOPSIS
  47 .In sys/systm.h
  48 .Ft void
  49 .Fn kfreeenv "char *env"
  50 .Ft char *
  51 .Fn kgetenv "const char *name"
  52 .Ft int
  53 .Fn kgetenv_int "const char *name" "int *data"
  54 .Ft int
  55 .Fn kgetenv_quad "const char *name" "quad_t *data"
  56 .Ft int
  57 .Fn kgetenv_string "const char *name" "char *data" "int size"
  58 .Ft int
  59 .Fn ksetenv "const char *name" "const char *value"
  60 .Ft int
  61 .Fn ktestenv "const char *name"
  62 .Ft int
  63 .Fn kunsetenv "const char *name"
  64 .Sh DESCRIPTION
  65 .Nm kenv
  66 provides an API for manipulation of the kernel environment of a live system by
  67 .Dq consumers
  68 (other kernel subsystems).
  69 Upon boot, the kernel environment is inherited from
  70 .Xr loader 8 .
  71 The static environment inherited is converted to a dynamic array at the end of
  72 the
  73 .Nm kmem
  74 subsystem configure phase of the kernel booting process.
  75 .Pp
  76 The
  77 .Fn kfreeenv
  78 function reclaims an array of characters earlier allocated by one of the
  79 .Fn kgetenv
  80 functions for use by the caller.
  81 .Pp
  82 The
  83 .Fn kgetenv*
  84 functions look up a given entry in the kernel environment, and return it if
  85 found.
  86 The
  87 .Fn kgetenv_{int,quad,string}
  88 functions return
  89 .Dv 1
  90 if unsuccessful,
  91 .Dv 0
  92 if successful, and return the
  93 found value in the given destination.
  94 .Pp
  95 The
  96 .Fn kgetenv
  97 function returns the value string or
  98 .Dv NULL
  99 if it failed.
 100 .Pp
 101 The
 102 .Fn ksetenv
 103 function sets a given environment key to the given value. It returns
 104 .Dv -1
 105 if either the
 106 .Fa name
 107 or
 108 .Fa value
 109 arguments were too large, the maxmimum number of entries in the dynamic
 110 environment was reached, or if the dynamic environment was not setup yet.
 111 The latter can happen when calling
 112 .Fn ksetenv
 113 before the
 114 .Nm kmem
 115 subsystem is initialized.
 116 .Pp
 117 The
 118 .Fn ktestenv
 119 function tests whether a given key exists in the kernel environment, returning
 120 .Dv 1
 121 if it does and
 122 .Dv 0
 123 if it does not.
 124 .Pp
 125 The
 126 .Fn kunsetenv
 127 function removes a given key and its associated value from the dynamic kernel
 128 environment.
 129 It returns
 130 .Dv -1
 131 if the key does not exist, or if the dynamic was not setup yet.
 132 If successful, it returns
 133 .Dv 0 .
 134 .Sh SYSCTLS
 135 .Bl -tag -width indent
 136 .It Va kern.environment
 137 Current static kernel environment query OID.
 138 .El
 139 .Sh COMPATIBILITY
 140 For compatibility reasons,
 141 .Fn freeenv
 142 and
 143 .Fn testenv
 144 are mapped to
 145 .Fn kfreeenv
 146 and
 147 .Fn ktestenv
 148 respectively.
 149 However, this compatibility is set to be removed in the future, so new
 150 consumers should use the right calls.
 151 Also, existing code needs to be converted.
 152 .Sh FILES
 153 .Bl -tag -width ".Pa sys/kern/kern_environment.c"
 154 .It Pa sys/kern/kern_environment.c
 155 .El
 156 .Sh SEE ALSO
 157 .Xr loader 8 ,
 158 .Xr loader.conf 5 ,
 159 .Xr sysctl 3 ,
 160 .Xr sysctl 8
 161 .Sh HISTORY
 162 A
 163 .Fn getenv
 164 function first appeared in
 165 .Fx 3.0 ,
 166 .Fn getenv_int
 167 in
 168 .Fx 3.1 ,
 169 .Fn getenv_quad
 170 in
 171 .Fx 3.4 ,
 172 .Fn getenv_string
 173 in
 174 .Fx 4.5
 175 and other functions first appeared in
 176 .Fx 5.0
 177 and subsequently
 178 .Dx 1.7 .
 179 .Sh AUTHORS
 180 .An -nosplit
 181 The original
 182 .Nm kenv
 183 implementation was written by
 184 .An Michael Smith .
 185 It was subsequently extended by
 186 .An Matt Jacob ,
 187 .An John Baldwin
 188 and
 189 .An Maxime Henrion .
 190 This manual page was written by
 191 .An Thomas E. Spanjaard .
 192 .Sh BUGS
 193 The
 194 .Fa kern.environment
 195 sysctl OID currently only reports information about the static kernel
 196 environment, not the dynamic one.
 197 .Pp
 198 The return values from various functions could do with some standardisation,
 199 using the error codes from
 200 .In sys/errno.h .