@@@ much mess, mostly manpages

[mLib] / sys / env.3.in

.\" -*-nroff-*-
.\"
.\" Manual for environment variable table
.\"
.\" (c) 1999, 2001, 2005, 2009, 2024 Straylight/Edgeware
.\"
.
.\"----- Licensing notice ---------------------------------------------------
.\"
.\" This file is part of the mLib utilities library.
.\"
.\" mLib is free software: you can redistribute it and/or modify it under
.\" the terms of the GNU Library General Public License as published by
.\" the Free Software Foundation; either version 2 of the License, or (at
.\" your option) any later version.
.\"
.\" mLib is distributed in the hope that it will be useful, but WITHOUT
.\" ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
.\" FITNESS FOR A PARTICULAR PURPOSE.  See the GNU Library General Public
.\" License for more details.
.\"
.\" You should have received a copy of the GNU Library General Public
.\" License along with mLib.  If not, write to the Free Software
.\" Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307,
.\" USA.
.
.\"--------------------------------------------------------------------------
.so ../defs.man \" @@@PRE@@@
.
.\"--------------------------------------------------------------------------
.TH env 3mLib "26 July 1999" "Straylight/Edgeware" "mLib utilities library"
.\" @env_get
.\" @env_put
.\" @env_import
.\" @env_export
.\" @env_destroy
.
.\"--------------------------------------------------------------------------
.SH "NAME"
env \- efficient fiddling with environment variables
.
.\"--------------------------------------------------------------------------
.SH "SYNOPSIS"
.
.nf
.B "#include <mLib/env.h>"
.PP
.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>
.
.\"----- That's all, folks --------------------------------------------------