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.2 2007/01/15 22:42:55 tgen Exp $ 32.\" 33.Dd January 15, 2007 34.Os 35.Dt KENV 9 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.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 ksetenv "const char *name" "const char *value" 59.Ft int 60.Fn ktestenv "const char *name" 61.Ft int 62.Fn kunsetenv "const char *name" 63.Sh DESCRIPTION 64The 65.Fn k*env* 66family of functions manipulate and provide data from the kernel 67environment of a live system. 68Upon boot, the kernel environment is inherited from 69.Xr loader 8 . 70The static environment inherited is converted to a dynamic array at the end of 71the 72.Nm kmem 73subsystem configure phase of the kernel booting process. 74.Pp 75The 76.Fn kfreeenv 77function reclaims an array of characters earlier allocated by one of the 78.Fn kgetenv 79functions for use by the caller. 80.Pp 81The 82.Fn kgetenv* 83functions look up a given entry in the kernel environment, and return it if 84found. 85The 86.Fn kgetenv_{int,quad.string} 87functions return 88.Dv 1 89if unsuccessful, 90.Dv 0 91if successful, and return the 92found value in the given destination. 93.Pp 94The 95.Fn kgetenv 96function returns the value string or 97.Dv NULL 98if it failed. 99.Pp 100The 101.Fn ksetenv 102function sets a given environment key to the given value. It returns 103.Dv -1 104if either the 105.Fa name 106or 107.Fa value 108arguments were too large, the maxmimum number of entries in the dynamic 109environment was reached, or if the dynamic environment was not setup yet. 110The latter can happen when calling 111.Fn ksetenv 112before the 113.Nm kmem 114subsystem is initialized. 115.Pp 116The 117.Fn ktestenv 118function tests whether a given key exists in the kernel environment, returning 119.Dv 1 120if it does and 121.Dv 0 122if it does not. 123.Pp 124The 125.Fn kunsetenv 126function removes a given key and its associated value from the dynamic kernel 127environment. 128It returns 129.Dv -1 130if the key does not exist, or if the dynamic was not setup yet. 131If successful, it returns 132.Dv 0 . 133.Sh COMPATIBILITY 134For compatibility reasons, 135.Fn freeenv 136and 137.Fn testenv 138are mapped to 139.Fn kfreeenv 140and 141.Fn ktestenv 142respectively. 143However, this compatibility is set to be removed in the future, so new 144consumers should use the right calls. 145Also, existing code needs to be converted. 146.Sh SEE ALSO 147.Xr loader 8 , 148.Xr loader.conf 5 149.Sh HISTORY 150A 151.Fn getenv 152function first appeared in 153.Fx 3.0 , 154.Fn getenv_int 155in 156.Fx 3.1 , 157.Fn getenv_quad 158in 159.Fx 3.4 , 160.Fn getenv_string 161in 162.Fx 4.5 163and other functions first appeared in 164.Fx 5.0 165and subsequently 166.Dx 1.7 . 167.Sh AUTHORS 168.An -nosplit 169The original 170.Nm kenv 171implementation was written by 172.An Michael Smith . 173It was subsequently extended by 174.An Matt Jacob , 175.An John Baldwin 176and 177.An Maxime Henrion . 178This manual page was written by 179.An Thomas E. Spanjaard . 180