From fa5515af77ba1c632b6110b11d6c31cc46a53a01 Mon Sep 17 00:00:00 2001 From: mux Date: Thu, 18 Apr 2002 16:45:57 +0000 Subject: Add a manpage for the kenv(2) syscall that Chad David kindly wrote for me. Submitted by: davidc --- lib/libc/sys/kenv.2 | 172 ++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 172 insertions(+) create mode 100644 lib/libc/sys/kenv.2 (limited to 'lib') diff --git a/lib/libc/sys/kenv.2 b/lib/libc/sys/kenv.2 new file mode 100644 index 0000000..cbda216 --- /dev/null +++ b/lib/libc/sys/kenv.2 @@ -0,0 +1,172 @@ +.\" +.\" Copyright (C) 2001 Chad David . 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 +function 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 +parameter can be one of the following: +.Bl -tag -width ".Dv KENV_DUMP" +.It Dv KENV_GET +Returns the value associated with the named kernel environment variable. +If the variable is not found -1 is returned and +.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 avaiable to the superuser. +.It Dv KENV_UNSET +Unsets the kernel environment variable +.Fa name . +If the variable does not exists -1 is returned and +.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 +parameter is the name of the environment variable to be affected. +In the case of +.Dv KENV_DUMP +it is ignored. +.Pp +The +.Fa value +parameter 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 +parameter indicates how many bytes of storage +.Fa value +points to. +.Sh RETURN VALUES +The +.Fn kenv +function 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 +.Va errno +is set to indicate the error. +.Sh ERRORS +.Fn kenv +will fail if: +.Bl -tag -width Er +.It Bq Er EINVAL +.Fa action +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 an kernel +environment variable. +.It Bq Er EFAULT +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 +.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 man page was written by +.An Chad David Aq davidc@FreeBSD.org . +.Pp +The +.Fn kenv +system call was written by +.An Maxime Henrion Aq mux@FreeBSD.org . -- cgit v1.1