]>
Commit | Line | Data |
---|---|---|
fea681da MK |
1 | .\" Copyright 2002 walter harms (walter.harms@informatik.uni-oldenburg.de) |
2 | .\" Distributed under GPL | |
3 | .\" based on the description in glibc source and infopages | |
c13182ef | 4 | .\" |
fea681da | 5 | .\" Corrections and additions, aeb |
e127c16a | 6 | .TH ENVZ_ADD 3 2007-05-18 "" "Linux Programmer's Manual" |
fea681da MK |
7 | .SH NAME |
8 | envz_add, envz_entry, envz_get, envz_merge, | |
9 | envz_remove, envz_strip \- environment string support | |
10 | .SH SYNOPSIS | |
11 | .nf | |
12 | .sp | |
13 | .B "#include <envz.h>" | |
14 | .sp | |
e7c0f078 MK |
15 | .BI "error_t envz_add(char **" envz ", size_t *" envz_len , |
16 | .ti 20n | |
fea681da MK |
17 | .BI "const char *" name ", const char *" value ); |
18 | .sp | |
e7c0f078 MK |
19 | .BI "char *envz_entry(const char *" envz ", size_t *" envz_len \ |
20 | ", const char *" name ); | |
fea681da | 21 | .sp |
e7c0f078 MK |
22 | .BI "char *envz_get(const char *" envz ", size_t *" envz_len \ |
23 | ", const char *" name ); | |
fea681da | 24 | .sp |
e7c0f078 MK |
25 | .BI "error_t envz_merge(char **" envz ", size_t *" envz_len , |
26 | .ti 20n | |
fea681da MK |
27 | .BI "const char *" envz2 ", size_t " envz2_len ", int " override ); |
28 | .sp | |
e7c0f078 MK |
29 | .BI "void envz_remove(char **" envz ", size_t *" envz_len \ |
30 | ", const char *" name ); | |
fea681da | 31 | .sp |
e7c0f078 | 32 | .BI "void envz_strip(char **" envz ", size_t *" envz_len ); |
c8250206 | 33 | .fi |
fea681da | 34 | .SH DESCRIPTION |
8382f16d | 35 | These functions are glibc-specific. |
fea681da MK |
36 | .LP |
37 | An argz vector is a pointer to a character buffer together with a length, | |
38 | see | |
39 | .BR argz_add (3). | |
40 | An envz vector is a special argz vector, namely one where the strings | |
c13182ef MK |
41 | have the form "name=value". |
42 | Everything after the first '=' is considered | |
43 | to be the value. | |
44 | If there is no '=', the value is taken to be NULL. | |
fea681da MK |
45 | (While the value in case of a trailing '=' is the empty string "".) |
46 | .LP | |
47 | These functions are for handling envz vectors. | |
48 | .LP | |
63aa9df0 | 49 | .BR envz_add () |
fea681da MK |
50 | adds the string |
51 | .RI \&" name = value \&" | |
52 | (in case | |
53 | .I value | |
54 | is non-NULL) or | |
55 | .RI \&" name \&" | |
56 | (in case | |
57 | .I value | |
58 | is NULL) to the envz vector | |
e7c0f078 | 59 | .RI ( *envz ,\ *envz_len ) |
fea681da | 60 | and updates |
e7c0f078 | 61 | .I *envz |
fea681da | 62 | and |
e7c0f078 | 63 | .IR *envz_len . |
fea681da MK |
64 | If an entry with the same |
65 | .I name | |
66 | existed, it is removed. | |
67 | .LP | |
63aa9df0 | 68 | .BR envz_entry () |
fea681da MK |
69 | looks for |
70 | .I name | |
71 | in the envz vector | |
e7c0f078 | 72 | .RI ( envz ,\ envz_len ) |
fea681da MK |
73 | and returns the entry if found, or NULL if not. |
74 | .LP | |
63aa9df0 | 75 | .BR envz_get () |
fea681da MK |
76 | looks for |
77 | .I name | |
78 | in the envz vector | |
e7c0f078 | 79 | .RI ( envz ,\ envz_len ) |
fea681da MK |
80 | and returns the value if found, or NULL if not. |
81 | (Note that the value can also be NULL, namely when there is | |
82 | an entry for | |
83 | .I name | |
84 | without '=' sign.) | |
85 | .LP | |
63aa9df0 | 86 | .BR envz_merge () |
fea681da MK |
87 | adds each entry in |
88 | .I envz2 | |
89 | to | |
e7c0f078 | 90 | .IR *envz , |
fea681da | 91 | as if with |
63aa9df0 | 92 | .BR envz_add (). |
fea681da MK |
93 | If |
94 | .I override | |
95 | is true, then values in | |
96 | .I envz2 | |
97 | will supersede those with the same name in | |
e7c0f078 | 98 | .IR *envz , |
fea681da MK |
99 | otherwise not. |
100 | .LP | |
63aa9df0 | 101 | .BR envz_remove () |
fea681da MK |
102 | removes the entry for |
103 | .I name | |
104 | from | |
e7c0f078 | 105 | .RI ( *envz ,\ *envz_len ) |
fea681da MK |
106 | if there was one. |
107 | .LP | |
e511ffb6 | 108 | .BR envz_strip () |
fea681da MK |
109 | removes all entries with value NULL. |
110 | .SH "RETURN VALUE" | |
111 | All envz functions that do memory allocation have a return type of | |
826b3f27 | 112 | \fIerror_t\fP, and return 0 for success, and \fBENOMEM\fP |
fea681da | 113 | if an allocation error occurs. |
2b2581ee MK |
114 | .SH "CONFORMING TO" |
115 | These functions are a GNU extension. | |
116 | Handle with care. | |
fea681da MK |
117 | .SH EXAMPLE |
118 | .sp | |
119 | .nf | |
120 | #include <stdio.h> | |
af9c7ff2 | 121 | #include <stdlib.h> |
fea681da | 122 | #include <envz.h> |
cf0a9ace | 123 | |
fea681da | 124 | int |
cf0a9ace MK |
125 | main(int argc, char *argv[], char *envp[]) |
126 | { | |
127 | int i, e_len = 0; | |
128 | char *str; | |
fea681da | 129 | |
cf0a9ace MK |
130 | for (i=0; envp[i] != NULL; i++) |
131 | e_len += strlen(envp[i]) + 1; | |
fea681da | 132 | |
cf0a9ace MK |
133 | str = envz_entry(*envp, e_len, "HOME"); |
134 | printf("%s\en", str); | |
135 | str = envz_get(*envp, e_len, "HOME"); | |
136 | printf("%s\en", str); | |
5bc8c34c | 137 | exit(EXIT_SUCCESS); |
fea681da MK |
138 | } |
139 | .fi | |
fea681da | 140 | .SH "SEE ALSO" |
d122bd56 | 141 | .BR argz_add (3) |