.\" -*-nroff-*-
.TH env 3 "26 July 1999" "Straylight/Edgeware" "mLib utilities library"
.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 xmalloc (3);
hence, one call to
.BR xfree (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
.IR value .
Finally, if
.I value
is null, the variable
.I name
is deleted.
.PP
The
.B env_destroy
function frees an environment symbol table, together with all of the
environment variables.
.SH "SEE ALSO"
.BR sym (3),
.BR mLib (3).
.SH "AUTHOR"
Mark Wooding, <mdw@distorted.org.uk>