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 69provides an API for manipulation of the kernel environment of a live system by 70.Dq consumers 71(other kernel subsystems). 72Upon boot, the kernel environment is inherited from 73.Xr loader 8 . 74The static environment inherited is converted to a dynamic array at the end of 75the 76.Nm kmem 77subsystem configure phase of the kernel booting process. 78.Pp 79The 80.Fn kfreeenv 81function reclaims an array of characters earlier allocated by one of the 82.Fn kgetenv 83functions for use by the caller. 84.Pp 85The 86.Fn kgetenv* 87functions look up a given entry in the kernel environment, and return it if 88found. 89The 90.Fn kgetenv_int , 91.Fn kgetenv_quad , 92.Fn kgetenv_string , 93and 94.Fn kgetenv_ulong 95functions return 96.Dv 1 97if unsuccessful, 98.Dv 0 99if successful, and return the 100found value in the given destination. 101.Pp 102The 103.Fn kgetenv 104function returns the value string or 105.Dv NULL 106if it failed. 107.Pp 108The 109.Fn ksetenv 110function sets a given environment key to the given value. It returns 111.Dv -1 112if either the 113.Fa name 114or 115.Fa value 116arguments were too large, the maxmimum number of entries in the dynamic 117environment was reached, or if the dynamic environment was not setup yet. 118The latter can happen when calling 119.Fn ksetenv 120before the 121.Nm kmem 122subsystem is initialized. 123.Pp 124The 125.Fn ktestenv 126function tests whether a given key exists in the kernel environment, returning 127.Dv 1 128if it does and 129.Dv 0 130if it does not. 131.Pp 132The 133.Fn kunsetenv 134function removes a given key and its associated value from the dynamic kernel 135environment. 136It returns 137.Dv -1 138if the key does not exist, or if the dynamic was not setup yet. 139If successful, it returns 140.Dv 0 . 141.Sh SYSCTLS 142.Bl -tag -width indent 143.It Va kern.environment 144Current 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 156A 157.Fn getenv 158function first appeared in 159.Fx 3.0 , 160.Fn getenv_int 161in 162.Fx 3.1 , 163.Fn getenv_quad 164in 165.Fx 3.4 , 166.Fn getenv_string 167in 168.Fx 4.5 169and other functions first appeared in 170.Fx 5.0 171and subsequently 172.Dx 1.7 . 173.Sh AUTHORS 174.An -nosplit 175The original 176.Nm kenv 177implementation was written by 178.An Michael Smith . 179It was subsequently extended by 180.An Matt Jacob , 181.An John Baldwin 182and 183.An Maxime Henrion . 184This manual page was written by 185.An Thomas E. Spanjaard . 186.Sh BUGS 187The 188.Va kern.environment 189sysctl OID currently only reports information about the static kernel 190environment, not the dynamic one. 191.Pp 192The return values from various functions could do with some standardisation, 193using the error codes from 194.In sys/errno.h . 195