e19206c2 |
1 | .\" -*-nroff-*- |
fbf20b5b |
2 | .TH env 3 "26 July 1999" "Straylight/Edgeware" "mLib utilities library" |
e19206c2 |
3 | .SH "NAME" |
00667e86 |
4 | env \- 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" |
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 |
39e23af4 |
42 | .BR xmalloc (3); |
e19206c2 |
43 | hence, one call to |
39e23af4 |
44 | .BR xfree (3) |
e19206c2 |
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 |
1f75302b |
62 | .I value |
63 | argument is ignored, and the variable |
e19206c2 |
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 |
1f75302b |
71 | is assigned |
72 | .IR value . |
e19206c2 |
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 |
1f75302b |
81 | function frees an environment symbol table, together with all of the |
82 | environment variables. |
e19206c2 |
83 | .SH "SEE ALSO" |
84 | .BR sym (3), |
85 | .BR mLib (3). |
86 | .SH "AUTHOR" |
9b5ac6ff |
87 | Mark Wooding, <mdw@distorted.org.uk> |