MFC r314055

Make several improvements and corrections in the kenv(2) man page

Sponsored by:	Dell EMC

1 files changed, 54 insertions, 58 deletions

diff --git a/lib/libc/sys/kenv.2 b/lib/libc/sys/kenv.2
index 866c0d38..1e50afe 100644
--- a/lib/libc/sys/kenv.2
+++ b/lib/libc/sys/kenv.2
@@ -26,7 +26,7 @@
 .\"
 .\" $FreeBSD$
 .\"
-.Dd April 17, 2002
+.Dd February 20, 2017
 .Dt KENV 2
 .Os
 .Sh NAME
@@ -51,71 +51,59 @@ The
 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
+Get the
+.Fa value
+of the variable with the given
+.Fa name .
+The size of the
 .Fa value
-are copied out.
+buffer is given by
+.Fa len ,
+which should be at least
+.Dv KENV_MVALLEN
++ 1 bytes to avoid truncation and to ensure NUL termination.
 .It Dv KENV_SET
-Sets or adds a new kernel environment variable.
+Set or add a variable.
+The
+.Fa name
+and
+.Fa value
+are limited to
+.Dv KENV_MNAMELEN
+and
+.Dv KENV_MVALLEN
+characters, respectively
+.Pq not including the NUL terminator.
+The
+.Fa len
+argument indicates the length of the
+.Fa value
+and must include the NUL terminator.
 This option is only available to the superuser.
 .It Dv KENV_UNSET
-Unsets the kernel environment variable
+Unset the variable with the given
 .Fa name .
-If the variable does not exist, \-1 is returned and
-the global variable
-.Va errno
-is set to
-.Er EINVAL .
+The
+.Fa value
+and
+.Fa len
+arguments are ignored.
 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 .
+Dump as much of the kernel environment as will fit in
+.Fa value ,
+whose size is given in
+.Fa len .
 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.
+is ignored.
+.El
 .Sh RETURN VALUES
 The
 .Fn kenv
@@ -148,23 +136,31 @@ is not a valid option, or the length of the
 is less than 1 for a
 .Dv KENV_SET .
 .It Bq Er ENOENT
-no value could be found for
+No value could be found for
 .Fa name
 for a
-.Dv KENV_SET
+.Dv KENV_GET
 or
 .Dv KENV_UNSET .
 .It Bq Er EPERM
-a user other than the superuser attempted to set or unset a kernel
+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,
+A 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
+The
+.Fa name
+or the
+.Fa value
+is longer than
 .Dv KENV_MNAMELEN
-or the value of a variable is longer than
-.Dv KENV_MVALLEN .
+or
+.Dv KENV_MVALLEN
+characters, respectively, or
+.Fa len
+did not include the NUL terminator for a
+.Dv KENV_SET .
 .El
 .Sh SEE ALSO
 .Xr kenv 1