Sort by section.
[dragonfly.git] / 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.6 2007/03/01 12:37:19 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 sysctl 3 ,
158 .Xr loader.conf 5 ,
159 .Xr loader 8 ,
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 .