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