| 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> |