.\" -*-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>