svn commit: r256927 - head/share/man/man9

Tue Oct 22 20:10:39 UTC 2013

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 at 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.
