1.\" 2.\" Copyright (C) 2002 Chad David <[email protected]>. 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.\" 1. Redistributions of source code must retain the above copyright 8.\" notice(s), this list of conditions and the following disclaimer as 9.\" the first lines of this file unmodified other than the possible 10.\" addition of one or more copyright notices. 11.\" 2. Redistributions in binary form must reproduce the above copyright 12.\" notice(s), this list of conditions and the following disclaimer in the 13.\" documentation and/or other materials provided with the distribution. 14.\" 15.\" THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDER(S) ``AS IS'' AND ANY 16.\" EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED 17.\" WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE 18.\" DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER(S) BE LIABLE FOR ANY 19.\" DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES 20.\" (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR 21.\" SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER 22.\" CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 23.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 24.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH 25.\" DAMAGE. 26.\" 27.\" $FreeBSD$ 28.\" 29.Dd June 20, 2021 30.Dt KENV 2 31.Os 32.Sh NAME 33.Nm kenv 34.Nd kernel environment 35.Sh LIBRARY 36.Lb libc 37.Sh SYNOPSIS 38.In kenv.h 39.Ft int 40.Fn kenv "int action" "const char *name" "char *value" "int len" 41.Sh DESCRIPTION 42The 43.Fn kenv 44system call manipulates kernel environment variables. 45It supports the well known userland actions of getting, setting and unsetting 46environment variables, as well as the ability to dump all of the entries in 47the kernel environment. 48.Pp 49The 50.Fa action 51argument can be one of the following: 52.Bl -tag -width ".Dv KENV_DUMP_LOADER" 53.It Dv KENV_GET 54Get the 55.Fa value 56of the variable with the given 57.Fa name . 58The size of the 59.Fa value 60buffer is given by 61.Fa len , 62which should be at least 63.Dv KENV_MVALLEN 64+ 1 bytes to avoid truncation and to ensure NUL termination. 65.It Dv KENV_SET 66Set or add a variable. 67The 68.Fa name 69and 70.Fa value 71are limited to 72.Dv KENV_MNAMELEN 73and 74.Dv KENV_MVALLEN 75characters, respectively 76.Pq not including the NUL terminator. 77The 78.Fa len 79argument indicates the length of the 80.Fa value 81and must include the NUL terminator. 82This option is only available to the superuser. 83.It Dv KENV_UNSET 84Unset the variable with the given 85.Fa name . 86The 87.Fa value 88and 89.Fa len 90arguments are ignored. 91This option is only available to the superuser. 92.It Dv KENV_DUMP 93Dump as much of the dynamic kernel environment as will fit in 94.Fa value , 95whose size is given in 96.Fa len . 97If 98.Fa value 99is 100.Dv NULL , 101.Fn kenv 102will return the number of bytes required to copy out the entire environment. 103The 104.Fa name 105is ignored. 106.It Dv KENV_DUMP_LOADER 107Dump the static environment provided by 108.Xr loader 8 , 109with semantics identical to 110.Dv KENV_DUMP . 111Duplicate and malformed variables originally present in this environment are 112discarded by the kernel and will not appear in the output. 113.It Dv KENV_DUMP_STATIC 114Dump the static environment defined by the kernel 115.Xr config 5 . 116The semantics are identical to 117.Dv KENV_DUMP_LOADER . 118.El 119.Sh RETURN VALUES 120The 121.Fn kenv 122system call returns 0 if successful in the case of 123.Dv KENV_SET 124and 125.Dv KENV_UNSET , 126and the number of bytes copied into 127.Fa value 128in the case of 129.Dv KENV_DUMP 130and 131.Dv KENV_GET . 132If an error occurs, a value of \-1 is returned and 133the global variable 134.Va errno 135is set to indicate the error. 136.Sh ERRORS 137The 138.Fn kenv 139system call 140will fail if: 141.Bl -tag -width Er 142.It Bq Er EINVAL 143The 144.Fa action 145argument 146is not a valid option, or the length of the 147.Fa value 148is less than 1 for a 149.Dv KENV_SET . 150.It Bq Er ENOENT 151No value could be found for 152.Fa name 153for a 154.Dv KENV_GET 155or 156.Dv KENV_UNSET . 157.It Bq Er ENOENT 158The requested environment is not available for a 159.Dv KENV_DUMP_LOADER 160or 161.Dv KENV_DUMP_STATIC . 162The kernel is configured to destroy these environments by default. 163.It Bq Er EPERM 164A user other than the superuser attempted to set or unset a kernel 165environment variable. 166.It Bq Er EFAULT 167A bad address was encountered while attempting to copy in user arguments 168or copy out value(s). 169.It Bq Er ENAMETOOLONG 170The 171.Fa name 172or the 173.Fa value 174is longer than 175.Dv KENV_MNAMELEN 176or 177.Dv KENV_MVALLEN 178characters, respectively, or 179.Fa len 180did not include the NUL terminator for a 181.Dv KENV_SET . 182.El 183.Sh SEE ALSO 184.Xr kenv 1 185.Sh AUTHORS 186.An -nosplit 187This manual page was written by 188.An Chad David Aq Mt [email protected] . 189.Pp 190The 191.Fn kenv 192system call was written by 193.An Maxime Henrion Aq Mt [email protected] . 194