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