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