Add a manpage for the getenv() family of functions in the kernel.
This commit is contained in:
John Baldwin
parent
10016ed51c
commit
fa24b620c0
@ -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.9 \
|
||||
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
|
||||
|
||||
210
share/man/man9/getenv.9
Normal file
210
share/man/man9/getenv.9
Normal file
@ -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.
|
||||
Loading…
Reference in New Issue
Block a user