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.5 2007/02/04 04:31:13 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 COMPATIBILITY 140For compatibility reasons, 141.Fn freeenv 142and 143.Fn testenv 144are mapped to 145.Fn kfreeenv 146and 147.Fn ktestenv 148respectively. 149However, this compatibility is set to be removed in the future, so new 150consumers should use the right calls. 151Also, 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 loader 8 , 158.Xr loader.conf 5 , 159.Xr sysctl 3 , 160.Xr sysctl 8 161.Sh HISTORY 162A 163.Fn getenv 164function first appeared in 165.Fx 3.0 , 166.Fn getenv_int 167in 168.Fx 3.1 , 169.Fn getenv_quad 170in 171.Fx 3.4 , 172.Fn getenv_string 173in 174.Fx 4.5 175and other functions first appeared in 176.Fx 5.0 177and subsequently 178.Dx 1.7 . 179.Sh AUTHORS 180.An -nosplit 181The original 182.Nm kenv 183implementation was written by 184.An Michael Smith . 185It was subsequently extended by 186.An Matt Jacob , 187.An John Baldwin 188and 189.An Maxime Henrion . 190This manual page was written by 191.An Thomas E. Spanjaard . 192.Sh BUGS 193The 194.Fa kern.environment 195sysctl OID currently only reports information about the static kernel 196environment, not the dynamic one. 197.Pp 198The return values from various functions could do with some standardisation, 199using the error codes from 200.In sys/errno.h . 201