Debian Codegraph @

upstream/debian-trixie/man3/envz_add.3

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