]>
Commit | Line | Data |
---|---|---|
a1eaacb1 | 1 | '\" t |
fea681da | 2 | .\" Copyright 2002 walter harms (walter.harms@informatik.uni-oldenburg.de) |
2297bf0e | 3 | .\" |
95fb8859 | 4 | .\" SPDX-License-Identifier: GPL-1.0-or-later |
0389adc9 | 5 | .\" |
fea681da | 6 | .\" based on the description in glibc source and infopages |
c13182ef | 7 | .\" |
fea681da | 8 | .\" Corrections and additions, aeb |
4c1c5274 | 9 | .TH envz_add 3 (date) "Linux man-pages (unreleased)" |
fea681da MK |
10 | .SH NAME |
11 | envz_add, envz_entry, envz_get, envz_merge, | |
12 | envz_remove, envz_strip \- environment string support | |
afa8db94 AC |
13 | .SH LIBRARY |
14 | Standard C library | |
15 | .RI ( libc ", " \-lc ) | |
fea681da MK |
16 | .SH SYNOPSIS |
17 | .nf | |
1ae6b2c7 | 18 | .B #include <envz.h> |
dbfe9c70 | 19 | .PP |
ebf67ad6 AC |
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 ); | |
dbfe9c70 | 23 | .PP |
ebf67ad6 AC |
24 | .BI "char *envz_entry(const char *restrict " envz ", size_t " envz_len , |
25 | .BI " const char *restrict " name ); | |
dbfe9c70 | 26 | .PP |
ebf67ad6 AC |
27 | .BI "char *envz_get(const char *restrict " envz ", size_t " envz_len , |
28 | .BI " const char *restrict " name ); | |
dbfe9c70 | 29 | .PP |
ebf67ad6 AC |
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 ); | |
dbfe9c70 | 33 | .PP |
ebf67ad6 AC |
34 | .BI "void envz_remove(char **restrict " envz ", size_t *restrict " envz_len , |
35 | .BI " const char *restrict " name ); | |
dbfe9c70 | 36 | .PP |
ebf67ad6 | 37 | .BI "void envz_strip(char **restrict " envz ", size_t *restrict " envz_len ); |
c8250206 | 38 | .fi |
fea681da | 39 | .SH DESCRIPTION |
8382f16d | 40 | These functions are glibc-specific. |
dd3568a1 | 41 | .PP |
fea681da MK |
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 | |
c13182ef | 46 | have the form "name=value". |
b957f81f | 47 | Everything after the first \[aq]=\[aq] is considered |
c13182ef | 48 | to be the value. |
b957f81f AC |
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 "".) | |
dd3568a1 | 51 | .PP |
fea681da | 52 | These functions are for handling envz vectors. |
dd3568a1 | 53 | .PP |
63aa9df0 | 54 | .BR envz_add () |
fea681da MK |
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 | |
e7c0f078 | 64 | .RI ( *envz ,\ *envz_len ) |
fea681da | 65 | and updates |
e7c0f078 | 66 | .I *envz |
fea681da | 67 | and |
e7c0f078 | 68 | .IR *envz_len . |
fea681da MK |
69 | If an entry with the same |
70 | .I name | |
71 | existed, it is removed. | |
dd3568a1 | 72 | .PP |
63aa9df0 | 73 | .BR envz_entry () |
fea681da MK |
74 | looks for |
75 | .I name | |
76 | in the envz vector | |
e7c0f078 | 77 | .RI ( envz ,\ envz_len ) |
fea681da | 78 | and returns the entry if found, or NULL if not. |
dd3568a1 | 79 | .PP |
63aa9df0 | 80 | .BR envz_get () |
fea681da MK |
81 | looks for |
82 | .I name | |
83 | in the envz vector | |
e7c0f078 | 84 | .RI ( envz ,\ envz_len ) |
fea681da MK |
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 | |
b957f81f | 89 | without \[aq]=\[aq] sign.) |
dd3568a1 | 90 | .PP |
63aa9df0 | 91 | .BR envz_merge () |
fea681da MK |
92 | adds each entry in |
93 | .I envz2 | |
94 | to | |
e7c0f078 | 95 | .IR *envz , |
fea681da | 96 | as if with |
63aa9df0 | 97 | .BR envz_add (). |
fea681da MK |
98 | If |
99 | .I override | |
100 | is true, then values in | |
101 | .I envz2 | |
102 | will supersede those with the same name in | |
e7c0f078 | 103 | .IR *envz , |
fea681da | 104 | otherwise not. |
dd3568a1 | 105 | .PP |
63aa9df0 | 106 | .BR envz_remove () |
fea681da MK |
107 | removes the entry for |
108 | .I name | |
109 | from | |
e7c0f078 | 110 | .RI ( *envz ,\ *envz_len ) |
fea681da | 111 | if there was one. |
dd3568a1 | 112 | .PP |
e511ffb6 | 113 | .BR envz_strip () |
fea681da | 114 | removes all entries with value NULL. |
47297adb | 115 | .SH RETURN VALUE |
fea681da | 116 | All envz functions that do memory allocation have a return type of |
1ae6b2c7 | 117 | .I error_t |
43891c16 | 118 | (an integer type), |
c6fa0841 MK |
119 | and return 0 for success, and |
120 | .B ENOMEM | |
fea681da | 121 | if an allocation error occurs. |
29a663f7 MS |
122 | .SH ATTRIBUTES |
123 | For an explanation of the terms used in this section, see | |
124 | .BR attributes (7). | |
125 | .TS | |
126 | allbox; | |
c466875e | 127 | lbx lb lb |
29a663f7 MS |
128 | l l l. |
129 | Interface Attribute Value | |
130 | T{ | |
9e54434e BR |
131 | .na |
132 | .nh | |
29a663f7 MS |
133 | .BR envz_add (), |
134 | .BR envz_entry (), | |
29a663f7 MS |
135 | .BR envz_get (), |
136 | .BR envz_merge (), | |
29a663f7 MS |
137 | .BR envz_remove (), |
138 | .BR envz_strip () | |
139 | T} Thread safety MT-Safe | |
140 | .TE | |
847e0d88 | 141 | .sp 1 |
3113c7f3 | 142 | .SH STANDARDS |
4131356c | 143 | GNU. |
a14af333 | 144 | .SH EXAMPLES |
b0b6ab4e | 145 | .\" SRC BEGIN (envz_add.c) |
207050fa | 146 | .EX |
ad3868f0 | 147 | #include <envz.h> |
fea681da | 148 | #include <stdio.h> |
af9c7ff2 | 149 | #include <stdlib.h> |
fe5dba13 | 150 | \& |
fea681da | 151 | int |
cf0a9ace MK |
152 | main(int argc, char *argv[], char *envp[]) |
153 | { | |
48971225 AC |
154 | char *str; |
155 | size_t e_len = 0; | |
fe5dba13 | 156 | \& |
b42296e4 | 157 | for (size_t i = 0; envp[i] != NULL; i++) |
cf0a9ace | 158 | e_len += strlen(envp[i]) + 1; |
fe5dba13 | 159 | \& |
cf0a9ace | 160 | str = envz_entry(*envp, e_len, "HOME"); |
31a6818e | 161 | printf("%s\en", str); |
cf0a9ace | 162 | str = envz_get(*envp, e_len, "HOME"); |
31a6818e | 163 | printf("%s\en", str); |
5bc8c34c | 164 | exit(EXIT_SUCCESS); |
fea681da | 165 | } |
207050fa | 166 | .EE |
b0b6ab4e | 167 | .\" SRC END |
47297adb | 168 | .SH SEE ALSO |
d122bd56 | 169 | .BR argz_add (3) |