Date: Tue, 22 Oct 2013 20:10:38 +0000 (UTC) From: John Baldwin <jhb@FreeBSD.org> To: src-committers@freebsd.org, svn-src-all@freebsd.org, svn-src-head@freebsd.org Subject: svn commit: r256927 - head/share/man/man9 Message-ID: <201310222010.r9MKAc8j024220@svn.freebsd.org>
next in thread | raw e-mail | index | archive | help
Author: jhb Date: Tue Oct 22 20:10:38 2013 New Revision: 256927 URL: http://svnweb.freebsd.org/changeset/base/256927 Log: Add a manpage for the getenv() family of functions in the kernel. Added: head/share/man/man9/getenv.9 (contents, props changed) Modified: head/share/man/man9/Makefile Modified: head/share/man/man9/Makefile ============================================================================== --- head/share/man/man9/Makefile Tue Oct 22 19:55:04 2013 (r256926) +++ head/share/man/man9/Makefile Tue Oct 22 20:10:38 2013 (r256927) @@ -118,6 +118,7 @@ MAN= accept_filter.9 \ g_consumer.9 \ g_data.9 \ get_cyclecount.9 \ + getenv.9 \ getnewvnode.9 \ g_event.9 \ g_geom.9 \ @@ -677,6 +678,14 @@ MLINKS+=g_consumer.9 g_destroy_consumer. g_consumer.9 g_new_consumer.9 MLINKS+=g_data.9 g_read_data.9 \ g_data.9 g_write_data.9 +MLINKS+=getenv.9 freeenv.9 \ + getenv.9 getenv_int.9 \ + getenv.9 getenv_long.9 \ + getenv.9 getenv_string.9 \ + getenv.9 getenv_quad.9 \ + getenv.9 getenv_uint.9 \ + getenv.9 getenv_ulong.9 \ + getenv.9 testenv.9 MLINKS+=g_event.9 g_cancel_event.9 \ g_event.9 g_post_event.9 \ g_event.9 g_waitfor_event.9 Added: head/share/man/man9/getenv.9 ============================================================================== --- /dev/null 00:00:00 1970 (empty, because file is newly added) +++ head/share/man/man9/getenv.9 Tue Oct 22 20:10:38 2013 (r256927) @@ -0,0 +1,210 @@ +.\" -*- nroff -*- +.\" +.\" Copyright (c) 2013 Advanced Computing Technologies LLC +.\" Written by: John H. Baldwin <jhb@FreeBSD.org> +.\" 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, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, 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 AUTHOR AND CONTRIBUTORS ``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 AUTHOR OR CONTRIBUTORS 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 October 22, 2013 +.Dt getenv 9 +.Os +.Sh NAME +.Nm freeenv , +.Nm getenv , +.Nm getenv_int , +.Nm getenv_long , +.Nm getenv_string , +.Nm getenv_quad , +.Nm getenv_uint , +.Nm getenv_ulong , +.Nm setenv , +.Nm testenv , +.Nm unsetenv +.Nd kernel environment variable functions +.Sh SYNOPSIS +.In sys/param.h +.In sys/systm.h +.Ft void +.Fn freeenv "char *env" +.Ft char * +.Fn getenv "const char *name" +.Ft int +.Fn getenv_int "const char *name" "int *data" +.Ft int +.Fn getenv_long "const char *name" "long *data" +.Ft int +.Fn getenv_string "const char *name" "char *data" "int size" +.Ft int +.Fn getenv_quad "const char *name" "quad_t *data" +.Ft int +.Fn getenv_uint "const char *name" "unsigned int *data" +.Ft int +.Fn getenv_ulong "const char *name" "unsigned long *data" +.Ft int +.Fn setenv "const char *name" "const char *value" +.Ft int +.Fn testenv "const char *name" +.Ft int +.Fn unsetenv "const char *name" +.Sh DESCRIPTION +These functions set, unset, fetch, and parse variables from the kernel's +environment. +.Pp +The +.Fn getenv +function obtains the current value of the kernel environment variable +.Fa name +and returns a pointer to the string value. +The caller should not modify the string pointed to by the return value. +.Pp +The +.Fn getenv +function may allocate temporary storage, +so the +.Fn freeenv +function must be called to release any allocated resources when the value +returned by +.Fn getenv +is no longer needed. +The +.Fa env +argument passed to +.Fn freeenv +is the pointer returned by the earlier call to +.Fn getenv . +.Pp +The +.Fn setenv +function inserts or resets the kernel environment variable +.Fa name +to +.Fa value . +If the variable +.Fa name +already exists, +its value is replaced. +This function can fail if an internal limit on the number of environment +variables is exceeded. +.Pp +The +.Fn unsetenv +function deletes the kernel environment variable +.Fa name . +.Pp +The +.Fn testenv +function is used to determine if a kernel environment variable exists. +It returns a non-zero value if the variable +.Fa name +exists and zero if it does not. +.Pp +The +.Fn getenv_int , +.Fn getenv_long , +.Fn getenv_quad , +.Fn getenv_uint , +and +.Fn getenv_ulong +functions look for a kernel environment variable +.Fa name +and parse it as a signed integer, +long integer, +signed 64-bit integer, +unsigned integer, +or an unsigned long integer, +respectively. +These functions fail and return zero if +.Fa name +does not exist or if any invalid characters are present in its value. +On success, +these function store the parsed value in the integer variable pointed to +by +.Fa data . +If the parsed value overflows the integer type, +a truncated value is stored in +.Fa data +and zero is returned. +If the value begins with a prefix of +.Dq 0x +it is interpreted as hexadecimal. +If it begins with a prefix of +.Dq 0 +it is interpreted as octal. +Otherwise, +the value is interpreted as decimal. +The value may contain a single character suffix specifying a unit for +the value. +The interpreted value is multipled by the unit's magnitude before being returned. +The following unit suffixes are supported: +.Bl -column -offset indent ".Sy Unit" ".Sy Magnitude" +.It Sy Unit Ta Sy Magnitude +.It k Ta 2^10 +.It m Ta 2^20 +.It g Ta 2^30 +.It t Ta 2^40 +.El +.Pp +The +.Fn getenv_string +function stores a copy of the kernel environment variable +.Fa name +in the buffer described by +.Fa data +and +.Fa size. +If the variable does not exist, +zero is returned. +If the variable exists, +up to +.Fa size - 1 +characters of it's value are copied to the buffer pointed to by +.Fa data +followed by a null character and a non-zero value is returned. +.Sh RETURN VALUES +The +.Fn getenv +function returns a pointer to an environment variable's value on success or +.Dv NULL +if the variable does not exist. +.Pp +The +.Fn setenv +and +.Fn unsetenv +functions return zero on success and -1 on failure. +.Pp +The +.Fn testenv +function returns zero if the specified environment variable does not exist and +a non-zero value if it does exist. +The +.Fn getenv_int , +.Fn getenv_long , +.Fn getenv_string , +.Fn getenv_quad , +.Fn getenv_uint , +and +.Fn getenv_ulong +functions return a non-zero value on success and zero on failure.
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?201310222010.r9MKAc8j024220>