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 April 17, 2002
  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 Returns the value associated with the named kernel environment variable.
  55 If the variable is not found, \-1 is returned and
  56 the global variable
  57 .Va errno
  58 is set to
  59 .Er ENOENT .
  60 Only the number of bytes available in
  61 .Fa value
  62 are copied out.
  63 .It Dv KENV_SET
  64 Sets or adds a new kernel environment variable.
  65 This option is only available to the superuser.
  66 .It Dv KENV_UNSET
  67 Unsets the kernel environment variable
  68 .Fa name .
  69 If the variable does not exist, \-1 is returned and
  70 the global variable
  71 .Va errno
  72 is set to
  73 .Er EINVAL .
  74 This option is only available to the superuser.
  75 .It Dv KENV_DUMP
  76 Dumps as much of the kernel environment as will fit in
  77 .Fa value .
  78 If
  79 .Fa value
  80 is
  81 .Dv NULL ,
  82 .Fn kenv
  83 will return the number of bytes required to copy out the entire environment.
  84 .El
  85 .Pp
  86 The
  87 .Fa name
  88 argument is the name of the environment variable to be affected.
  89 In the case of
  90 .Dv KENV_DUMP
  91 it is ignored.
  92 .Pp
  93 The
  94 .Fa value
  95 argument contains either the value to set the environment variable
  96 .Fa name
  97 to in the case of
  98 .Dv KENV_SET ,
  99 or it points to the location where
 100 .Fn kenv
 101 should copy return data to in the case of
 102 .Dv KENV_DUMP
 103 and
 104 .Dv KENV_GET .
 105 If
 106 .Fa value
 107 is
 108 .Dv NULL
 109 in the case of
 110 .Dv KENV_DUMP ,
 111 .Fn kenv
 112 will return the number of bytes required to copy out the entire environment.
 113 .Pp
 114 The
 115 .Fa len
 116 argument indicates how many bytes of storage
 117 .Fa value
 118 points to.
 119 .Sh RETURN VALUES
 120 The
 121 .Fn kenv
 122 system call returns 0 if successful in the case of
 123 .Dv KENV_SET
 124 and
 125 .Dv KENV_UNSET ,
 126 and the number of bytes copied into
 127 .Fa value
 128 in the case of
 129 .Dv KENV_DUMP
 130 and
 131 .Dv KENV_GET .
 132 If an error occurs, a value of \-1 is returned and
 133 the global variable
 134 .Va errno
 135 is set to indicate the error.
 136 .Sh ERRORS
 137 The
 138 .Fn kenv
 139 system call
 140 will fail if:
 141 .Bl -tag -width Er
 142 .It Bq Er EINVAL
 143 The
 144 .Fa action
 145 argument
 146 is not a valid option, or the length of the
 147 .Fa value
 148 is less than 1 for a
 149 .Dv KENV_SET .
 150 .It Bq Er ENOENT
 151 no value could be found for
 152 .Fa name
 153 for a
 154 .Dv KENV_SET
 155 or
 156 .Dv KENV_UNSET .
 157 .It Bq Er EPERM
 158 a user other than the superuser attempted to set or unset a kernel
 159 environment variable.
 160 .It Bq Er EFAULT
 161 bad address was encountered while attempting to copy in user arguments,
 162 or copy out value(s).
 163 .It Bq Er ENAMETOOLONG
 164 the name of a variable supplied by the user is longer than
 165 .Dv KENV_MNAMELEN
 166 or 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
 173 This manual page was written by
 174 .An Chad David Aq davidc@FreeBSD.org .
 175 .Pp
 176 The
 177 .Fn kenv
 178 system call was written by
 179 .An Maxime Henrion Aq mux@FreeBSD.org .