Manpages: Move manpages (back?) into the top-level directory.

[mLib] / env.3

diff --git a/env.3 b/env.3
new file mode 100644 (file)
index 0000000..1818b37
--- /dev/null
+++ b/env.3
@@ -0,0 +1,87 @@
+.\" -*-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>