]>
Commit | Line | Data |
---|---|---|
fea681da | 1 | .\" Copyright 2002 walter harms (walter.harms@informatik.uni-oldenburg.de) |
2297bf0e | 2 | .\" |
95fb8859 | 3 | .\" SPDX-License-Identifier: GPL-1.0-or-later |
a781c7d0 | 4 | .\" |
fea681da | 5 | .\" based on the description in glibc source and infopages |
c13182ef | 6 | .\" |
fea681da | 7 | .\" Corrections and additions, aeb |
4c1c5274 | 8 | .TH argz_add 3 (date) "Linux man-pages (unreleased)" |
fea681da MK |
9 | .SH NAME |
10 | argz_add, argz_add_sep, argz_append, argz_count, argz_create, | |
11 | argz_create_sep, argz_delete, argz_extract, argz_insert, | |
12 | argz_next, argz_replace, argz_stringify \- functions to handle an argz list | |
b813014f AC |
13 | .SH LIBRARY |
14 | Standard C library | |
15 | .RI ( libc ", " \-lc ) | |
fea681da MK |
16 | .SH SYNOPSIS |
17 | .nf | |
fea681da | 18 | .B "#include <argz.h>" |
68e4db0a | 19 | .PP |
a5eaa137 | 20 | .BI "error_t argz_add(char **restrict " argz ", size_t *restrict " argz_len , |
62b60779 | 21 | .BI " const char *restrict " str ); |
68e4db0a | 22 | .PP |
62b60779 AC |
23 | .BI "error_t argz_add_sep(char **restrict " argz \ |
24 | ", size_t *restrict " argz_len , | |
25 | .BI " const char *restrict " str ", int " delim ); | |
68e4db0a | 26 | .PP |
62b60779 AC |
27 | .BI "error_t argz_append(char **restrict " argz ", size_t *restrict " argz_len , |
28 | .BI " const char *restrict " buf ", size_t " buf_len ); | |
68e4db0a | 29 | .PP |
2bbf2292 | 30 | .BI "size_t argz_count(const char *" argz ", size_t " argz_len ); |
68e4db0a | 31 | .PP |
62b60779 AC |
32 | .BI "error_t argz_create(char *const " argv "[], char **restrict " argz , |
33 | .BI " size_t *restrict " argz_len ); | |
68e4db0a | 34 | .PP |
62b60779 AC |
35 | .BI "error_t argz_create_sep(const char *restrict " str ", int " sep , |
36 | .BI " char **restrict " argz ", size_t *restrict " argz_len ); | |
68e4db0a | 37 | .PP |
62b60779 AC |
38 | .BI "void argz_delete(char **restrict " argz ", size_t *restrict " argz_len , |
39 | .BI " char *restrict " entry ); | |
68e4db0a | 40 | .PP |
62b60779 AC |
41 | .BI "void argz_extract(const char *restrict " argz ", size_t " argz_len , |
42 | .BI " char **restrict " argv ); | |
68e4db0a | 43 | .PP |
62b60779 AC |
44 | .BI "error_t argz_insert(char **restrict " argz ", size_t *restrict " argz_len , |
45 | .BI " char *restrict " before ", const char *restrict " entry ); | |
68e4db0a | 46 | .PP |
62b60779 AC |
47 | .BI "char *argz_next(const char *restrict " argz ", size_t " argz_len , |
48 | .BI " const char *restrict " entry ); | |
68e4db0a | 49 | .PP |
62b60779 AC |
50 | .BI "error_t argz_replace(char **restrict " argz \ |
51 | ", size_t *restrict " argz_len , | |
52 | .BI " const char *restrict " str ", const char *restrict " with , | |
53 | .BI " unsigned int *restrict " replace_count ); | |
68e4db0a | 54 | .PP |
2bbf2292 | 55 | .BI "void argz_stringify(char *" argz ", size_t " len ", int " sep ); |
c8250206 | 56 | .fi |
fea681da | 57 | .SH DESCRIPTION |
8382f16d | 58 | These functions are glibc-specific. |
dd3568a1 | 59 | .PP |
fea681da | 60 | An argz vector is a pointer to a character buffer together with a length. |
c3b8df70 | 61 | The intended interpretation of the character buffer is an array |
d1a71985 | 62 | of strings, where the strings are separated by null bytes (\(aq\e0\(aq). |
c7094399 | 63 | If the length is nonzero, the last byte of the buffer must be a null byte. |
dd3568a1 | 64 | .PP |
fea681da MK |
65 | These functions are for handling argz vectors. |
66 | The pair (NULL,0) is an argz vector, and, conversely, | |
b437fdd9 | 67 | argz vectors of length 0 must have null pointer. |
aa796481 | 68 | Allocation of nonempty argz vectors is done using |
fea681da MK |
69 | .BR malloc (3), |
70 | so that | |
71 | .BR free (3) | |
72 | can be used to dispose of them again. | |
dd3568a1 | 73 | .PP |
63aa9df0 | 74 | .BR argz_add () |
fea681da MK |
75 | adds the string |
76 | .I str | |
77 | at the end of the array | |
2bbf2292 | 78 | .IR *argz , |
fea681da | 79 | and updates |
2bbf2292 | 80 | .I *argz |
fea681da | 81 | and |
2bbf2292 | 82 | .IR *argz_len . |
dd3568a1 | 83 | .PP |
63aa9df0 | 84 | .BR argz_add_sep () |
fea681da MK |
85 | is similar, but splits the string |
86 | .I str | |
87 | into substrings separated by the delimiter | |
88 | .IR delim . | |
008f1ecc | 89 | For example, one might use this on a UNIX search path with |
f81fb444 | 90 | delimiter \(aq:\(aq. |
dd3568a1 | 91 | .PP |
63aa9df0 | 92 | .BR argz_append () |
fea681da | 93 | appends the argz vector |
ea01d886 | 94 | .RI ( buf ,\ buf_len ) |
fea681da | 95 | after |
ea01d886 | 96 | .RI ( *argz ,\ *argz_len ) |
fea681da | 97 | and updates |
1ae6b2c7 | 98 | .I *argz |
fea681da | 99 | and |
2bbf2292 | 100 | .IR *argz_len . |
fea681da | 101 | (Thus, |
2bbf2292 | 102 | .I *argz_len |
fea681da MK |
103 | will be increased by |
104 | .IR buf_len .) | |
dd3568a1 | 105 | .PP |
63aa9df0 | 106 | .BR argz_count () |
c13182ef | 107 | counts the number of strings, that is, |
d1a71985 | 108 | the number of null bytes (\(aq\e0\(aq), in |
ea01d886 | 109 | .RI ( argz ,\ argz_len ). |
dd3568a1 | 110 | .PP |
63aa9df0 | 111 | .BR argz_create () |
008f1ecc | 112 | converts a UNIX-style argument vector |
fea681da | 113 | .IR argv , |
2bbf2292 | 114 | terminated by |
5049da5b | 115 | .IR "(char\ *)\ 0" , |
2bbf2292 | 116 | into an argz vector |
ea01d886 | 117 | .RI ( *argz ,\ *argz_len ). |
dd3568a1 | 118 | .PP |
63aa9df0 | 119 | .BR argz_create_sep () |
28d88c17 | 120 | converts the null-terminated string |
fea681da MK |
121 | .I str |
122 | into an argz vector | |
ea01d886 | 123 | .RI ( *argz ,\ *argz_len ) |
fea681da MK |
124 | by breaking it up at every occurrence of the separator |
125 | .IR sep . | |
dd3568a1 | 126 | .PP |
63aa9df0 | 127 | .BR argz_delete () |
fea681da MK |
128 | removes the substring pointed to by |
129 | .I entry | |
130 | from the argz vector | |
ea01d886 | 131 | .RI ( *argz ,\ *argz_len ) |
fea681da | 132 | and updates |
2bbf2292 | 133 | .I *argz |
fea681da | 134 | and |
2bbf2292 | 135 | .IR *argz_len . |
dd3568a1 | 136 | .PP |
63aa9df0 | 137 | .BR argz_extract () |
fea681da | 138 | is the opposite of |
63aa9df0 | 139 | .BR argz_create (). |
fea681da | 140 | It takes the argz vector |
ea01d886 | 141 | .RI ( argz ,\ argz_len ) |
fea681da MK |
142 | and fills the array starting at |
143 | .I argv | |
144 | with pointers to the substrings, and a final NULL, | |
008f1ecc | 145 | making a UNIX-style argv vector. |
fea681da MK |
146 | The array |
147 | .I argv | |
148 | must have room for | |
97e91fec | 149 | .IR argz_count ( argz ", " argz_len ") + 1" |
fea681da | 150 | pointers. |
dd3568a1 | 151 | .PP |
63aa9df0 | 152 | .BR argz_insert () |
fea681da | 153 | is the opposite of |
63aa9df0 | 154 | .BR argz_delete (). |
fea681da MK |
155 | It inserts the argument |
156 | .I entry | |
157 | at position | |
158 | .I before | |
159 | into the argz vector | |
ea01d886 | 160 | .RI ( *argz ,\ *argz_len ) |
fea681da | 161 | and updates |
2bbf2292 | 162 | .I *argz |
fea681da | 163 | and |
2bbf2292 | 164 | .IR *argz_len . |
fea681da MK |
165 | If |
166 | .I before | |
167 | is NULL, then | |
168 | .I entry | |
169 | will inserted at the end. | |
dd3568a1 | 170 | .PP |
63aa9df0 | 171 | .BR argz_next () |
588b77dc | 172 | is a function to step through the argz vector. |
c13182ef | 173 | If |
fea681da | 174 | .I entry |
c13182ef MK |
175 | is NULL, the first entry is returned. |
176 | Otherwise, the entry | |
177 | following is returned. | |
178 | It returns NULL if there is no following entry. | |
dd3568a1 | 179 | .PP |
63aa9df0 | 180 | .BR argz_replace () |
fea681da MK |
181 | replaces each occurrence of |
182 | .I str | |
183 | with | |
184 | .IR with , | |
c13182ef MK |
185 | reallocating argz as necessary. |
186 | If | |
fea681da MK |
187 | .I replace_count |
188 | is non-NULL, | |
2bbf2292 | 189 | .I *replace_count |
fea681da | 190 | will be incremented by the number of replacements. |
dd3568a1 | 191 | .PP |
63aa9df0 | 192 | .BR argz_stringify () |
fea681da | 193 | is the opposite of |
63aa9df0 | 194 | .BR argz_create_sep (). |
fea681da | 195 | It transforms the argz vector into a normal string by replacing |
d1a71985 | 196 | all null bytes (\(aq\e0\(aq) except the last by |
fea681da | 197 | .IR sep . |
47297adb | 198 | .SH RETURN VALUE |
fea681da | 199 | All argz functions that do memory allocation have a return type of |
1ae6b2c7 | 200 | .I error_t |
43891c16 | 201 | (an integer type), |
c6fa0841 MK |
202 | and return 0 for success, and |
203 | .B ENOMEM | |
fea681da | 204 | if an allocation error occurs. |
3cc3c5e6 MS |
205 | .SH ATTRIBUTES |
206 | For an explanation of the terms used in this section, see | |
207 | .BR attributes (7). | |
c466875e MK |
208 | .ad l |
209 | .nh | |
3cc3c5e6 MS |
210 | .TS |
211 | allbox; | |
c466875e | 212 | lbx lb lb |
3cc3c5e6 MS |
213 | l l l. |
214 | Interface Attribute Value | |
215 | T{ | |
216 | .BR argz_add (), | |
217 | .BR argz_add_sep (), | |
3cc3c5e6 MS |
218 | .BR argz_append (), |
219 | .BR argz_count (), | |
3cc3c5e6 MS |
220 | .BR argz_create (), |
221 | .BR argz_create_sep (), | |
3cc3c5e6 MS |
222 | .BR argz_delete (), |
223 | .BR argz_extract (), | |
3cc3c5e6 MS |
224 | .BR argz_insert (), |
225 | .BR argz_next (), | |
3cc3c5e6 MS |
226 | .BR argz_replace (), |
227 | .BR argz_stringify () | |
228 | T} Thread safety MT-Safe | |
229 | .TE | |
c466875e MK |
230 | .hy |
231 | .ad | |
847e0d88 | 232 | .sp 1 |
3113c7f3 | 233 | .SH STANDARDS |
c13182ef | 234 | These functions are a GNU extension. |
2b2581ee MK |
235 | .SH BUGS |
236 | Argz vectors without a terminating null byte may lead to | |
237 | Segmentation Faults. | |
47297adb | 238 | .SH SEE ALSO |
faade342 | 239 | .BR envz_add (3) |