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