[mLib] / man / env.3

.\" -*-nroff-*-
.TH env 3 "26 July 1999" mLib
.SH "NAME"
env \- efficient fiddling with environment variables
.\" @env_get
.\" @env_put
.\" @env_import
.\" @env_export
.\" @env_destroy
.SH "SYNOPSIS"
.nf
.B "#include <mLib/env.h>"

.BI "char *env_get(sym_table *" t ", const char *" name );
.BI "void env_put(sym_table *" t ,
.BI "             const char *" name ", const char *" value );
.BI "void env_import(sym_table *" t ", char **" env );
.BI "char **env_export(sym_table *" t );
.fi
.SH "DESCRIPTION"
The functions in the
.B "<mLib/env.h>"
header manipulate environment variables stored in a hash table.
.PP
The function
.B env_import
reads a standard Unix environment array and stores the variables in the
symbol table.  (A standard Unix environment array is an array of
pointers to strings of the form
.IB name = value
terminated by a null pointer.  This format is used for the global
.B environ
variable, and by the
.BR execve (2)
function.)  The symbol table must have already been created (see
.BR sym_create (3)).
.PP
The function
.B env_export
creates a Unix environment array from a symbol table.  The environment
array is one big block of memory allocated using
.BR malloc (3);
hence, one call to
.BR free (3)
releases all the memory used for the pointer array and the strings.
.PP
The
.B env_get
function looks up a variable in an environment symbol table.  The
returned result is the variable's value if it exists, or a null pointer
if not.
.PP
The
.B env_put
function sets or deletes environment variables.  If the
.I name
argument contains an
.RB ` = '
character, it is assumed to be of the form
.IB n = v\fR;
the
.I value argument is ignored, and the variable
.I n
is assigned the value
.IR v .
Otherwise, if
.I value
is not a null pointer, the variable
.I name
is assigned the value
.I value .
Finally, if
.I value
is null, the variable
.I name
is deleted.
.PP
The
.B env_destroy
function frees all the memory used by an environment symbol table.  The
table itself is destroyed too.
.SH "SEE ALSO"
.BR sym (3),
.BR mLib (3).
.SH "AUTHOR"
Mark Wooding, <mdw@nsict.org>
Commit	Line	Data
e19206c2	1	.\" --nroff--
	2	.TH env 3 "26 July 1999" mLib
	3	.SH "NAME"
00667e86	4	env \- efficient fiddling with environment variables
e19206c2	5	.\" @env_get
	6	.\" @env_put
	7	.\" @env_import
	8	.\" @env_export
	9	.\" @env_destroy
	10	.SH "SYNOPSIS"
	11	.nf
	12	.B "#include <mLib/env.h>"
	13
	14	.BI "char env_get(sym_table " t ", const char *" name );
f4d2cec8	15	.BI "void env_put(sym_table *" t ,
e19206c2	16	.BI " const char " name ", const char " value );
	17	.BI "void env_import(sym_table " t ", char *" env );
	18	.BI "char *env_export(sym_table " t );
	19	.fi
	20	.SH "DESCRIPTION"
	21	The functions in the
	22	.B "<mLib/env.h>"
	23	header manipulate environment variables stored in a hash table.
	24	.PP
	25	The function
	26	.B env_import
	27	reads a standard Unix environment array and stores the variables in the
	28	symbol table. (A standard Unix environment array is an array of
	29	pointers to strings of the form
	30	.IB name = value
	31	terminated by a null pointer. This format is used for the global
	32	.B environ
	33	variable, and by the
	34	.BR execve (2)
	35	function.) The symbol table must have already been created (see
	36	.BR sym_create (3)).
	37	.PP
	38	The function
	39	.B env_export
	40	creates a Unix environment array from a symbol table. The environment
	41	array is one big block of memory allocated using
	42	.BR malloc (3);
	43	hence, one call to
	44	.BR free (3)
	45	releases all the memory used for the pointer array and the strings.
	46	.PP
	47	The
	48	.B env_get
	49	function looks up a variable in an environment symbol table. The
	50	returned result is the variable's value if it exists, or a null pointer
	51	if not.
	52	.PP
	53	The
	54	.B env_put
	55	function sets or deletes environment variables. If the
	56	.I name
	57	argument contains an
	58	.RB ` = '
	59	character, it is assumed to be of the form
	60	.IB n = v\fR;
	61	the
	62	.I value argument is ignored, and the variable
	63	.I n
	64	is assigned the value
	65	.IR v .
	66	Otherwise, if
	67	.I value
	68	is not a null pointer, the variable
	69	.I name
	70	is assigned the value
	71	.I value .
	72	Finally, if
	73	.I value
	74	is null, the variable
	75	.I name
	76	is deleted.
	77	.PP
	78	The
	79	.B env_destroy
80	function frees all the memory used by an environment symbol table. The
81	table itself is destroyed too.
82	.SH "SEE ALSO"
83	.BR sym (3),
84	.BR mLib (3).
85	.SH "AUTHOR"
86	Mark Wooding, <mdw@nsict.org>