lib/libc/sys/kenv.2

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