1.\" 2.\" Copyright (C) 2002 Chad David <davidc@FreeBSD.org>. 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.Dd June 20, 2021 28.Dt KENV 2 29.Os 30.Sh NAME 31.Nm kenv 32.Nd kernel environment 33.Sh LIBRARY 34.Lb libc 35.Sh SYNOPSIS 36.In kenv.h 37.Ft int 38.Fn kenv "int action" "const char *name" "char *value" "int len" 39.Sh DESCRIPTION 40The 41.Fn kenv 42system call manipulates kernel environment variables. 43It supports the well known userland actions of getting, setting and unsetting 44environment variables, as well as the ability to dump all of the entries in 45the kernel environment. 46.Pp 47The 48.Fa action 49argument can be one of the following: 50.Bl -tag -width ".Dv KENV_DUMP_LOADER" 51.It Dv KENV_GET 52Get the 53.Fa value 54of the variable with the given 55.Fa name . 56The size of the 57.Fa value 58buffer is given by 59.Fa len , 60which should be at least 61.Dv KENV_MVALLEN 62+ 1 bytes to avoid truncation and to ensure NUL termination. 63.It Dv KENV_SET 64Set or add a variable. 65The 66.Fa name 67and 68.Fa value 69are limited to 70.Dv KENV_MNAMELEN 71and 72.Dv KENV_MVALLEN 73characters, respectively 74.Pq not including the NUL terminator. 75The 76.Fa len 77argument indicates the length of the 78.Fa value 79and must include the NUL terminator. 80This option is only available to the superuser. 81.It Dv KENV_UNSET 82Unset the variable with the given 83.Fa name . 84The 85.Fa value 86and 87.Fa len 88arguments are ignored. 89This option is only available to the superuser. 90.It Dv KENV_DUMP 91Dump as much of the dynamic kernel environment as will fit in 92.Fa value , 93whose size is given in 94.Fa len . 95If 96.Fa value 97is 98.Dv NULL , 99.Fn kenv 100will return the number of bytes required to copy out the entire environment. 101The 102.Fa name 103is ignored. 104.It Dv KENV_DUMP_LOADER 105Dump the static environment provided by 106.Xr loader 8 , 107with semantics identical to 108.Dv KENV_DUMP . 109Duplicate and malformed variables originally present in this environment are 110discarded by the kernel and will not appear in the output. 111.It Dv KENV_DUMP_STATIC 112Dump the static environment defined by the kernel 113.Xr config 5 . 114The semantics are identical to 115.Dv KENV_DUMP_LOADER . 116.El 117.Sh RETURN VALUES 118The 119.Fn kenv 120system call returns 0 if successful in the case of 121.Dv KENV_SET 122and 123.Dv KENV_UNSET , 124and the number of bytes copied into 125.Fa value 126in the case of 127.Dv KENV_DUMP 128and 129.Dv KENV_GET . 130If an error occurs, a value of \-1 is returned and 131the global variable 132.Va errno 133is set to indicate the error. 134.Sh ERRORS 135The 136.Fn kenv 137system call 138will fail if: 139.Bl -tag -width Er 140.It Bq Er EINVAL 141The 142.Fa action 143argument 144is not a valid option, or the length of the 145.Fa value 146is less than 1 for a 147.Dv KENV_SET . 148.It Bq Er ENOENT 149No value could be found for 150.Fa name 151for a 152.Dv KENV_GET 153or 154.Dv KENV_UNSET . 155.It Bq Er ENOENT 156The requested environment is not available for a 157.Dv KENV_DUMP_LOADER 158or 159.Dv KENV_DUMP_STATIC . 160The kernel is configured to destroy these environments by default. 161.It Bq Er EPERM 162A user other than the superuser attempted to set or unset a kernel 163environment variable. 164.It Bq Er EFAULT 165A bad address was encountered while attempting to copy in user arguments 166or copy out value(s). 167.It Bq Er ENAMETOOLONG 168The 169.Fa name 170or the 171.Fa value 172is longer than 173.Dv KENV_MNAMELEN 174or 175.Dv KENV_MVALLEN 176characters, respectively, or 177.Fa len 178did not include the NUL terminator for a 179.Dv KENV_SET . 180.El 181.Sh SEE ALSO 182.Xr kenv 1 183.Sh AUTHORS 184.An -nosplit 185This manual page was written by 186.An Chad David Aq Mt davidc@FreeBSD.org . 187.Pp 188The 189.Fn kenv 190system call was written by 191.An Maxime Henrion Aq Mt mux@FreeBSD.org . 192