1 .\" Copyright 2002 walter harms (walter.harms@informatik.uni-oldenburg.de)
3 .\" SPDX-License-Identifier: GPL-1.0-or-later
5 .\" based on the description in glibc source and infopages
7 .\" Corrections and additions, aeb
8 .TH ARGZ_ADD 3 2021-03-22 "" "Linux Programmer's Manual"
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
15 .RI ( libc ", " \-lc )
18 .B "#include <argz.h>"
20 .BI "error_t argz_add(char **restrict " argz ", size_t *restrict " argz_len ",
21 .BI " const char *restrict " str );
23 .BI "error_t argz_add_sep(char **restrict " argz \
24 ", size_t *restrict " argz_len ,
25 .BI " const char *restrict " str ", int " delim );
27 .BI "error_t argz_append(char **restrict " argz ", size_t *restrict " argz_len ,
28 .BI " const char *restrict " buf ", size_t " buf_len );
30 .BI "size_t argz_count(const char *" argz ", size_t " argz_len );
32 .BI "error_t argz_create(char *const " argv "[], char **restrict " argz ,
33 .BI " size_t *restrict " argz_len );
35 .BI "error_t argz_create_sep(const char *restrict " str ", int " sep ,
36 .BI " char **restrict " argz ", size_t *restrict " argz_len );
38 .BI "void argz_delete(char **restrict " argz ", size_t *restrict " argz_len ,
39 .BI " char *restrict " entry );
41 .BI "void argz_extract(const char *restrict " argz ", size_t " argz_len ,
42 .BI " char **restrict " argv );
44 .BI "error_t argz_insert(char **restrict " argz ", size_t *restrict " argz_len ,
45 .BI " char *restrict " before ", const char *restrict " entry );
47 .BI "char *argz_next(const char *restrict " argz ", size_t " argz_len ,
48 .BI " const char *restrict " entry );
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 );
55 .BI "void argz_stringify(char *" argz ", size_t " len ", int " sep );
58 These functions are glibc-specific.
60 An argz vector is a pointer to a character buffer together with a length.
61 The intended interpretation of the character buffer is an array
62 of strings, where the strings are separated by null bytes (\(aq\e0\(aq).
63 If the length is nonzero, the last byte of the buffer must be a null byte.
65 These functions are for handling argz vectors.
66 The pair (NULL,0) is an argz vector, and, conversely,
67 argz vectors of length 0 must have null pointer.
68 Allocation of nonempty argz vectors is done using
72 can be used to dispose of them again.
77 at the end of the array
85 is similar, but splits the string
87 into substrings separated by the delimiter
89 For example, one might use this on a UNIX search path with
93 appends the argz vector
94 .RI ( buf ,\ buf_len )
96 .RI ( *argz ,\ *argz_len )
107 counts the number of strings, that is,
108 the number of null bytes (\(aq\e0\(aq), in
109 .RI ( argz ,\ argz_len ).
112 converts a UNIX-style argument vector
117 .RI ( *argz ,\ *argz_len ).
119 .BR argz_create_sep ()
120 converts the null-terminated string
123 .RI ( *argz ,\ *argz_len )
124 by breaking it up at every occurrence of the separator
128 removes the substring pointed to by
131 .RI ( *argz ,\ *argz_len )
140 It takes the argz vector
141 .RI ( argz ,\ argz_len )
142 and fills the array starting at
144 with pointers to the substrings, and a final NULL,
145 making a UNIX-style argv vector.
149 .IR argz_count ( argz ", " argz_len ") + 1"
155 It inserts the argument
160 .RI ( *argz ,\ *argz_len )
169 will inserted at the end.
172 is a function to step through the argz vector.
175 is NULL, the first entry is returned.
177 following is returned.
178 It returns NULL if there is no following entry.
181 replaces each occurrence of
185 reallocating argz as necessary.
190 will be incremented by the number of replacements.
192 .BR argz_stringify ()
194 .BR argz_create_sep ().
195 It transforms the argz vector into a normal string by replacing
196 all null bytes (\(aq\e0\(aq) except the last by
199 All argz functions that do memory allocation have a return type of
202 and return 0 for success, and
204 if an allocation error occurs.
206 For an explanation of the terms used in this section, see
214 Interface Attribute Value
221 .BR argz_create_sep (),
227 .BR argz_stringify ()
228 T} Thread safety MT-Safe
234 These functions are a GNU extension.
236 Argz vectors without a terminating null byte may lead to