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