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.\" $FreeBSD: head/lib/libc/sys/kenv.2 267774 2014-06-23 08:25:03Z bapt $ 28.\" 29.Dd March 19, 2016 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_UNSET" 53.It Dv KENV_GET 54Returns the value associated with the named kernel environment variable. 55If the variable is not found, \-1 is returned and 56the global variable 57.Va errno 58is set to 59.Er ENOENT . 60Only the number of bytes available in 61.Fa value 62are copied out. 63.It Dv KENV_SET 64Sets or adds a new kernel environment variable. 65This option is only available to the superuser. 66.It Dv KENV_UNSET 67Unsets the kernel environment variable 68.Fa name . 69If the variable does not exist, \-1 is returned and 70the global variable 71.Va errno 72is set to 73.Er EINVAL . 74This option is only available to the superuser. 75.It Dv KENV_DUMP 76Dumps as much of the kernel environment as will fit in 77.Fa value . 78If 79.Fa value 80is 81.Dv NULL , 82.Fn kenv 83will return the number of bytes required to copy out the entire environment. 84.El 85.Pp 86The 87.Fa name 88argument is the name of the environment variable to be affected. 89In the case of 90.Dv KENV_DUMP 91it is ignored. 92.Pp 93The 94.Fa value 95argument contains either the value to set the environment variable 96.Fa name 97to in the case of 98.Dv KENV_SET , 99or it points to the location where 100.Fn kenv 101should copy return data to in the case of 102.Dv KENV_DUMP 103and 104.Dv KENV_GET . 105If 106.Fa value 107is 108.Dv NULL 109in the case of 110.Dv KENV_DUMP , 111.Fn kenv 112will return the number of bytes required to copy out the entire environment. 113.Pp 114The 115.Fa len 116argument indicates how many bytes of storage 117.Fa value 118points to. 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_SET 155or 156.Dv KENV_UNSET . 157.It Bq Er EPERM 158a user other than the superuser attempted to set or unset a kernel 159environment variable. 160.It Bq Er EFAULT 161bad address was encountered while attempting to copy in user arguments, 162or copy out value(s). 163.It Bq Er ENAMETOOLONG 164the name of a variable supplied by the user is longer than 165.Dv KENV_MNAMELEN 166or the value of a variable is longer than 167.Dv KENV_MVALLEN . 168.El 169.Sh SEE ALSO 170.Xr kenv 1 171.Sh AUTHORS 172.An -nosplit 173This manual page was written by 174.An Chad David Aq Mt davidc@FreeBSD.org . 175.Pp 176The 177.Fn kenv 178system call was written by 179.An Maxime Henrion Aq Mt mux@FreeBSD.org . 180