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.8 2007/11/25 00:13:28 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 FILES
 140 .Bl -tag -width ".Pa sys/kern/kern_environment.c"
 141 .It Pa sys/kern/kern_environment.c
 142 .El
 143 .Sh SEE ALSO
 144 .Xr sysctl 3 ,
 145 .Xr loader.conf 5 ,
 146 .Xr loader 8 ,
 147 .Xr sysctl 8
 148 .Sh HISTORY
 149 A
 150 .Fn getenv
 151 function first appeared in
 152 .Fx 3.0 ,
 153 .Fn getenv_int
 154 in
 155 .Fx 3.1 ,
 156 .Fn getenv_quad
 157 in
 158 .Fx 3.4 ,
 159 .Fn getenv_string
 160 in
 161 .Fx 4.5
 162 and other functions first appeared in
 163 .Fx 5.0
 164 and subsequently
 165 .Dx 1.7 .
 166 .Sh AUTHORS
 167 .An -nosplit
 168 The original
 169 .Nm kenv
 170 implementation was written by
 171 .An Michael Smith .
 172 It was subsequently extended by
 173 .An Matt Jacob ,
 174 .An John Baldwin
 175 and
 176 .An Maxime Henrion .
 177 This manual page was written by
 178 .An Thomas E. Spanjaard .
 179 .Sh BUGS
 180 The
 181 .Va kern.environment
 182 sysctl OID currently only reports information about the static kernel
 183 environment, not the dynamic one.
 184 .Pp
 185 The return values from various functions could do with some standardisation,
 186 using the error codes from
 187 .In sys/errno.h .