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
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
|
'\" t
.\" Copyright 2002 walter harms (walter.harms@informatik.uni-oldenburg.de)
.\"
.\" SPDX-License-Identifier: GPL-1.0-or-later
.\"
.\" based on the description in glibc source and infopages
.\"
.\" Corrections and additions, aeb
.TH envz_add 3 2024-05-02 "Linux man-pages 6.8"
.SH NAME
envz_add, envz_entry, envz_get, envz_merge,
envz_remove, envz_strip \- environment string support
.SH LIBRARY
Standard C library
.RI ( libc ", " \-lc )
.SH SYNOPSIS
.nf
.B #include <envz.h>
.P
.BI "error_t envz_add(char **restrict " envz ", size_t *restrict " envz_len ,
.BI " const char *restrict " name \
", const char *restrict " value );
.P
.BI "char *envz_entry(const char *restrict " envz ", size_t " envz_len ,
.BI " const char *restrict " name );
.P
.BI "char *envz_get(const char *restrict " envz ", size_t " envz_len ,
.BI " const char *restrict " name );
.P
.BI "error_t envz_merge(char **restrict " envz ", size_t *restrict " envz_len ,
.BI " const char *restrict " envz2 ", size_t " envz2_len ,
.BI " int " override );
.P
.BI "void envz_remove(char **restrict " envz ", size_t *restrict " envz_len ,
.BI " const char *restrict " name );
.P
.BI "void envz_strip(char **restrict " envz ", size_t *restrict " envz_len );
.fi
.SH DESCRIPTION
These functions are glibc-specific.
.P
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 \[aq]=\[aq] is considered
to be the value.
If there is no \[aq]=\[aq], the value is taken to be NULL.
(While the value in case of a trailing \[aq]=\[aq] is the empty string "".)
.P
These functions are for handling envz vectors.
.P
.BR 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
.I *envz
and
.IR *envz_len .
If an entry with the same
.I name
existed, it is removed.
.P
.BR envz_entry ()
looks for
.I name
in the envz vector
.RI ( envz ,\ envz_len )
and returns the entry if found, or NULL if not.
.P
.BR 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 \[aq]=\[aq] sign.)
.P
.BR envz_merge ()
adds each entry in
.I envz2
to
.IR *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
.IR *envz ,
otherwise not.
.P
.BR envz_remove ()
removes the entry for
.I name
from
.RI ( *envz ,\ *envz_len )
if there was one.
.P
.BR envz_strip ()
removes all entries with value NULL.
.SH RETURN VALUE
All envz functions that do memory allocation have a return type of
.I error_t
(an integer type),
and return 0 for success, and
.B ENOMEM
if an allocation error occurs.
.SH ATTRIBUTES
For an explanation of the terms used in this section, see
.BR attributes (7).
.TS
allbox;
lbx lb lb
l l l.
Interface Attribute Value
T{
.na
.nh
.BR envz_add (),
.BR envz_entry (),
.BR envz_get (),
.BR envz_merge (),
.BR envz_remove (),
.BR envz_strip ()
T} Thread safety MT-Safe
.TE
.SH STANDARDS
GNU.
.SH EXAMPLES
.\" SRC BEGIN (envz_add.c)
.EX
#include <envz.h>
#include <stdio.h>
#include <stdlib.h>
\&
int
main(int argc, char *argv[], char *envp[])
{
char *str;
size_t e_len = 0;
\&
for (size_t 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);
exit(EXIT_SUCCESS);
}
.EE
.\" SRC END
.SH SEE ALSO
.BR argz_add (3)
|
