chiark / gitweb /
Manpages: Move manpages (back?) into the top-level directory.
[mLib] / env.3
CommitLineData
e19206c2 1.\" -*-nroff-*-
fbf20b5b 2.TH env 3 "26 July 1999" "Straylight/Edgeware" "mLib utilities library"
e19206c2 3.SH "NAME"
00667e86 4env \- efficient fiddling with environment variables
e19206c2 5.\" @env_get
6.\" @env_put
7.\" @env_import
8.\" @env_export
9.\" @env_destroy
10.SH "SYNOPSIS"
11.nf
12.B "#include <mLib/env.h>"
13
14.BI "char *env_get(sym_table *" t ", const char *" name );
f4d2cec8 15.BI "void env_put(sym_table *" t ,
e19206c2 16.BI " const char *" name ", const char *" value );
17.BI "void env_import(sym_table *" t ", char **" env );
18.BI "char **env_export(sym_table *" t );
19.fi
20.SH "DESCRIPTION"
21The functions in the
22.B "<mLib/env.h>"
23header manipulate environment variables stored in a hash table.
24.PP
25The function
26.B env_import
27reads a standard Unix environment array and stores the variables in the
28symbol table. (A standard Unix environment array is an array of
29pointers to strings of the form
30.IB name = value
31terminated by a null pointer. This format is used for the global
32.B environ
33variable, and by the
34.BR execve (2)
35function.) The symbol table must have already been created (see
36.BR sym_create (3)).
37.PP
38The function
39.B env_export
40creates a Unix environment array from a symbol table. The environment
41array is one big block of memory allocated using
39e23af4 42.BR xmalloc (3);
e19206c2 43hence, one call to
39e23af4 44.BR xfree (3)
e19206c2 45releases all the memory used for the pointer array and the strings.
46.PP
47The
48.B env_get
49function looks up a variable in an environment symbol table. The
50returned result is the variable's value if it exists, or a null pointer
51if not.
52.PP
53The
54.B env_put
55function sets or deletes environment variables. If the
56.I name
57argument contains an
58.RB ` = '
59character, it is assumed to be of the form
60.IB n = v\fR;
61the
1f75302b 62.I value
63argument is ignored, and the variable
e19206c2 64.I n
65is assigned the value
66.IR v .
67Otherwise, if
68.I value
69is not a null pointer, the variable
70.I name
1f75302b 71is assigned
72.IR value .
e19206c2 73Finally, if
74.I value
75is null, the variable
76.I name
77is deleted.
78.PP
79The
80.B env_destroy
1f75302b 81function frees an environment symbol table, together with all of the
82environment variables.
e19206c2 83.SH "SEE ALSO"
84.BR sym (3),
85.BR mLib (3).
86.SH "AUTHOR"
9b5ac6ff 87Mark Wooding, <mdw@distorted.org.uk>