1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
|
.\"
.\" Copyright (C) 2002 Chad David <davidc@FreeBSD.org>. All rights reserved.
.\"
.\" Redistribution and use in source and binary forms, with or without
.\" modification, are permitted provided that the following conditions
.\" are met:
.\" 1. Redistributions of source code must retain the above copyright
.\" notice(s), this list of conditions and the following disclaimer as
.\" the first lines of this file unmodified other than the possible
.\" addition of one or more copyright notices.
.\" 2. Redistributions in binary form must reproduce the above copyright
.\" notice(s), this list of conditions and the following disclaimer in the
.\" documentation and/or other materials provided with the distribution.
.\"
.\" THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDER(S) ``AS IS'' AND ANY
.\" EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
.\" WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
.\" DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER(S) BE LIABLE FOR ANY
.\" DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
.\" (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
.\" SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
.\" CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH
.\" DAMAGE.
.\"
.\" $FreeBSD$
.\"
.Dd April 17, 2002
.Dt KENV 2
.Os
.Sh NAME
.Nm kenv
.Nd kernel environment
.Sh LIBRARY
.Lb libc
.Sh SYNOPSIS
.In kenv.h
.Ft int
.Fn kenv "int action" "const char *name" "char *value" "int len"
.Sh DESCRIPTION
The
.Fn kenv
system call manipulates kernel environment variables.
It supports the well known userland actions of getting, setting and unsetting
environment variables, as well as the ability to dump all of the entries in
the kernel environment.
.Pp
The
.Fa action
argument can be one of the following:
.Bl -tag -width ".Dv KENV_UNSET"
.It Dv KENV_GET
Returns the value associated with the named kernel environment variable.
If the variable is not found, \-1 is returned and
the global variable
.Va errno
is set to
.Er ENOENT .
Only the number of bytes available in
.Fa value
are copied out.
.It Dv KENV_SET
Sets or adds a new kernel environment variable.
This option is only available to the superuser.
.It Dv KENV_UNSET
Unsets the kernel environment variable
.Fa name .
If the variable does not exist, \-1 is returned and
the global variable
.Va errno
is set to
.Er EINVAL .
This option is only available to the superuser.
.It Dv KENV_DUMP
Dumps as much of the kernel environment as will fit in
.Fa value .
If
.Fa value
is
.Dv NULL ,
.Fn kenv
will return the number of bytes required to copy out the entire environment.
.El
.Pp
The
.Fa name
argument is the name of the environment variable to be affected.
In the case of
.Dv KENV_DUMP
it is ignored.
.Pp
The
.Fa value
argument contains either the value to set the environment variable
.Fa name
to in the case of
.Dv KENV_SET ,
or it points to the location where
.Fn kenv
should copy return data to in the case of
.Dv KENV_DUMP
and
.Dv KENV_GET .
If
.Fa value
is
.Dv NULL
in the case of
.Dv KENV_DUMP ,
.Fn kenv
will return the number of bytes required to copy out the entire environment.
.Pp
The
.Fa len
argument indicates how many bytes of storage
.Fa value
points to.
.Sh RETURN VALUES
The
.Fn kenv
system call returns 0 if successful in the case of
.Dv KENV_SET
and
.Dv KENV_UNSET ,
and the number of bytes copied into
.Fa value
in the case of
.Dv KENV_DUMP
and
.Dv KENV_GET .
If an error occurs, a value of \-1 is returned and
the global variable
.Va errno
is set to indicate the error.
.Sh ERRORS
The
.Fn kenv
system call
will fail if:
.Bl -tag -width Er
.It Bq Er EINVAL
The
.Fa action
argument
is not a valid option, or the length of the
.Fa value
is less than 1 for a
.Dv KENV_SET .
.It Bq Er ENOENT
no value could be found for
.Fa name
for a
.Dv KENV_SET
or
.Dv KENV_UNSET .
.It Bq Er EPERM
a user other than the superuser attempted to set or unset a kernel
environment variable.
.It Bq Er EFAULT
bad address was encountered while attempting to copy in user arguments,
or copy out value(s).
.It Bq Er ENAMETOOLONG
the name of a variable supplied by the user is longer than
.Dv KENV_MNAMELEN
or the value of a variable is longer than
.Dv KENV_MVALLEN .
.El
.Sh SEE ALSO
.Xr kenv 1
.Sh AUTHORS
.An -nosplit
This manual page was written by
.An Chad David Aq Mt davidc@FreeBSD.org .
.Pp
The
.Fn kenv
system call was written by
.An Maxime Henrion Aq Mt mux@FreeBSD.org .
|
