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