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