X-Git-Url: http://www.chiark.greenend.org.uk/ucgi/~mdw/git/mLib/blobdiff_plain/077c6597a446cf118ea3448664c9399efc847b76..e19206c2bfbd24ae9eceb5fbba9324fdcb3a544f:/man/env.3

diff --git a/man/env.3 b/man/env.3
new file mode 100644
index 0000000..7894d7c
--- /dev/null
+++ b/man/env.3
@@ -0,0 +1,86 @@
+.\" -*-nroff-*-
+.TH env 3 "26 July 1999" mLib
+.SH "NAME"
+env \- efficient fiddline 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>