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 .Dd July 21, 2012
  32 .Dt KENV 9
  33 .Os
  34 .Sh NAME
  35 .Nm kfreeenv ,
  36 .Nm kgetenv ,
  37 .Nm kgetenv_int ,
  38 .Nm kgetenv_quad ,
  39 .Nm kgetenv_string ,
  40 .Nm kgetenv_ulong ,
  41 .Nm ksetenv ,
  42 .Nm ktestenv ,
  43 .Nm kunsetenv
  44 .Nd API for manipulation of the kernel environment
  45 .Sh SYNOPSIS
  46 .In sys/systm.h
  47 .Ft void
  48 .Fn kfreeenv "char *env"
  49 .Ft char *
  50 .Fn kgetenv "const char *name"
  51 .Ft int
  52 .Fn kgetenv_int "const char *name" "int *data"
  53 .Ft int
  54 .Fn kgetenv_quad "const char *name" "quad_t *data"
  55 .Ft int
  56 .Fn kgetenv_string "const char *name" "char *data" "int size"
  57 .Ft int
  58 .Fn kgetenv_ulong "const char *name" "unsigned long *data"
  59 .Ft int
  60 .Fn ksetenv "const char *name" "const char *value"
  61 .Ft int
  62 .Fn ktestenv "const char *name"
  63 .Ft int
  64 .Fn kunsetenv "const char *name"
  65 .Sh DESCRIPTION
  66 .Nm kenv
  67 provides an API for manipulation of the kernel environment of a live system by
  68 .Dq consumers
  69 (other kernel subsystems).
  70 Upon boot, the kernel environment is inherited from
  71 .Xr loader 8 .
  72 The static environment inherited is converted to a dynamic array at the end of
  73 the
  74 .Nm kmem
  75 subsystem configure phase of the kernel booting process.
  76 .Pp
  77 The
  78 .Fn kfreeenv
  79 function reclaims an array of characters earlier allocated by one of the
  80 .Fn kgetenv
  81 functions for use by the caller.
  82 .Pp
  83 The
  84 .Fn kgetenv*
  85 functions look up a given entry in the kernel environment, and return it if
  86 found.
  87 The
  88 .Fn kgetenv_int ,
  89 .Fn kgetenv_quad ,
  90 .Fn kgetenv_string ,
  91 and
  92 .Fn kgetenv_ulong
  93 functions return
  94 .Dv 0
  95 if unsuccessful,
  96 .Dv 1
  97 if successful, and return the found value in the given destination.
  98 .Pp
  99 The
 100 .Fn kgetenv
 101 function returns the value string or
 102 .Dv NULL
 103 if it failed.
 104 .Pp
 105 The
 106 .Fn ksetenv
 107 function sets a given environment key to the given value. It returns
 108 .Dv -1
 109 if either the
 110 .Fa name
 111 or
 112 .Fa value
 113 arguments were too large, the maxmimum number of entries in the dynamic
 114 environment was reached, or if the dynamic environment was not setup yet.
 115 The latter can happen when calling
 116 .Fn ksetenv
 117 before the
 118 .Nm kmem
 119 subsystem is initialized.
 120 .Pp
 121 The
 122 .Fn ktestenv
 123 function tests whether a given key exists in the kernel environment, returning
 124 .Dv 1
 125 if it does and
 126 .Dv 0
 127 if it does not.
 128 .Pp
 129 The
 130 .Fn kunsetenv
 131 function removes a given key and its associated value from the dynamic kernel
 132 environment.
 133 It returns
 134 .Dv -1
 135 if the key does not exist, or if the dynamic was not setup yet.
 136 If successful, it returns
 137 .Dv 0 .
 138 .Sh SYSCTLS
 139 .Bl -tag -width indent
 140 .It Va kern.environment
 141 Current static kernel environment query OID.
 142 .El
 143 .Sh FILES
 144 .Bl -tag -width ".Pa sys/kern/kern_environment.c"
 145 .It Pa sys/kern/kern_environment.c
 146 .El
 147 .Sh SEE ALSO
 148 .Xr sysctl 3 ,
 149 .Xr loader.conf 5 ,
 150 .Xr loader 8 ,
 151 .Xr sysctl 8
 152 .Sh HISTORY
 153 A
 154 .Fn getenv
 155 function first appeared in
 156 .Fx 3.0 ,
 157 .Fn getenv_int
 158 in
 159 .Fx 3.1 ,
 160 .Fn getenv_quad
 161 in
 162 .Fx 3.4 ,
 163 .Fn getenv_string
 164 in
 165 .Fx 4.5
 166 and other functions first appeared in
 167 .Fx 5.0
 168 and subsequently
 169 .Dx 1.7 .
 170 .Sh AUTHORS
 171 .An -nosplit
 172 The original
 173 .Nm kenv
 174 implementation was written by
 175 .An Michael Smith .
 176 It was subsequently extended by
 177 .An Matt Jacob ,
 178 .An John Baldwin
 179 and
 180 .An Maxime Henrion .
 181 This manual page was written by
 182 .An Thomas E. Spanjaard .
 183 .Sh BUGS
 184 The
 185 .Va kern.environment
 186 sysctl OID currently only reports information about the static kernel
 187 environment, not the dynamic one.
 188 .Pp
 189 The return values from various functions could do with some standardisation,
 190 using the error codes from
 191 .In sys/errno.h .