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