Debian Codegraph @

upstream/debian-unstable/man3/envz_add.3

raw
1 '\" t
2 .\" Copyright 2002, Walter Harms <[email protected]>
3 .\" Copyright, the authors of the Linux man-pages project
4 .\"
5 .\" SPDX-License-Identifier: GPL-1.0-or-later
6 .\"
7 .TH envz_add 3 2026-02-08 "Linux man-pages 6.18"
8 .SH NAME
9 envz_add, envz_entry, envz_get, envz_merge,
10 envz_remove, envz_strip \- environment string support
11 .SH LIBRARY
12 Standard C library
13 .RI ( libc ,\~ \-lc )
14 .SH SYNOPSIS
15 .nf
16 .B #include <envz.h>
17 .P
18 .BI "error_t envz_add(char **restrict " envz ", size_t *restrict " envz_len ,
19 .BI " const char *restrict " name \
20 ", const char *restrict " value );
21 .P
22 .BI "char *envz_entry(const char *restrict " envz ", size_t " envz_len ,
23 .BI " const char *restrict " name );
24 .P
25 .BI "char *envz_get(const char *restrict " envz ", size_t " envz_len ,
26 .BI " const char *restrict " name );
27 .P
28 .BI "error_t envz_merge(char **restrict " envz ", size_t *restrict " envz_len ,
29 .BI " const char *restrict " envz2 ", size_t " envz2_len ,
30 .BI " int " override );
31 .P
32 .BI "void envz_remove(char **restrict " envz ", size_t *restrict " envz_len ,
33 .BI " const char *restrict " name );
34 .P
35 .BI "void envz_strip(char **restrict " envz ", size_t *restrict " envz_len );
36 .fi
37 .SH DESCRIPTION
38 These functions are glibc-specific.
39 .P
40 An argz vector is a pointer to a character buffer together with a length,
41 see
42 .BR argz_add (3).
43 An envz vector is a special argz vector, namely one where the strings
44 have the form "name=value".
45 Everything after the first \[aq]=\[aq] is considered
46 to be the value.
47 If there is no \[aq]=\[aq], the value is taken to be NULL.
48 (While the value in case of a trailing \[aq]=\[aq] is the empty string "".)
49 .P
50 These functions are for handling envz vectors.
51 .P
52 .BR envz_add ()
53 adds the string
54 .RI \&" name = value \&"
55 (in case
56 .I value
57 is non-NULL) or
58 .RI \&" name \&"
59 (in case
60 .I value
61 is NULL) to the envz vector
62 .RI ( *envz ,\ *envz_len )
63 and updates
64 .I *envz
65 and
66 .IR *envz_len .
67 If an entry with the same
68 .I name
69 existed, it is removed.
70 .P
71 .BR envz_entry ()
72 looks for
73 .I name
74 in the envz vector
75 .RI ( envz ,\ envz_len )
76 and returns the entry if found, or NULL if not.
77 .P
78 .BR envz_get ()
79 looks for
80 .I name
81 in the envz vector
82 .RI ( envz ,\ envz_len )
83 and returns the value if found, or NULL if not.
84 (Note that the value can also be NULL, namely when there is
85 an entry for
86 .I name
87 without \[aq]=\[aq] sign.)
88 .P
89 .BR envz_merge ()
90 adds each entry in
91 .I envz2
92 to
93 .IR *envz ,
94 as if with
95 .BR envz_add ().
96 If
97 .I override
98 is true, then values in
99 .I envz2
100 will supersede those with the same name in
101 .IR *envz ,
102 otherwise not.
103 .P
104 .BR envz_remove ()
105 removes the entry for
106 .I name
107 from
108 .RI ( *envz ,\ *envz_len )
109 if there was one.
110 .P
111 .BR envz_strip ()
112 removes all entries with value NULL.
113 .SH RETURN VALUE
114 All envz functions that do memory allocation have a return type of
115 .I error_t
116 (an integer type),
117 and return 0 for success, and
118 .B ENOMEM
119 if an allocation error occurs.
120 .SH ATTRIBUTES
121 For an explanation of the terms used in this section, see
122 .BR attributes (7).
123 .TS
124 allbox;
125 lbx lb lb
126 l l l.
127 Interface Attribute Value
128 T{
129 .na
130 .nh
131 .BR envz_add (),
132 .BR envz_entry (),
133 .BR envz_get (),
134 .BR envz_merge (),
135 .BR envz_remove (),
136 .BR envz_strip ()
137 T} Thread safety MT-Safe
138 .TE
139 .SH STANDARDS
140 GNU.
141 .SH EXAMPLES
142 .\" SRC BEGIN (envz_add.c)
143 .EX
144 #include <envz.h>
145 #include <stdio.h>
146 #include <stdlib.h>
147 \&
148 int
149 main(int argc, char *argv[], char *envp[])
150 {
151 char *str;
152 size_t e_len = 0;
153 \&
154 for (size_t i = 0; envp[i] != NULL; i++)
155 e_len += strlen(envp[i]) + 1;
156 \&
157 str = envz_entry(*envp, e_len, "HOME");
158 printf("%s\[rs]n", str);
159 str = envz_get(*envp, e_len, "HOME");
160 printf("%s\[rs]n", str);
161 exit(EXIT_SUCCESS);
162 }
163 .EE
164 .\" SRC END
165 .SH SEE ALSO
166 .BR argz_add (3)