-
Notifications
You must be signed in to change notification settings - Fork 0
Expand file tree
/
Copy pathArgz-Functions.html
More file actions
230 lines (204 loc) · 12.1 KB
/
Argz-Functions.html
File metadata and controls
230 lines (204 loc) · 12.1 KB
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
<html lang="en">
<head>
<title>Argz Functions - The GNU C Library</title>
<meta http-equiv="Content-Type" content="text/html">
<meta name="description" content="The GNU C Library">
<meta name="generator" content="makeinfo 4.9">
<link title="Top" rel="start" href="index.html#Top">
<link rel="up" href="Argz-and-Envz-Vectors.html#Argz-and-Envz-Vectors" title="Argz and Envz Vectors">
<link rel="next" href="Envz-Functions.html#Envz-Functions" title="Envz Functions">
<link href="http://www.gnu.org/software/texinfo/" rel="generator-home" title="Texinfo Homepage">
<!--
This file documents the GNU C library.
This is Edition 0.11, last updated 2007-09-09,
of `The GNU C Library Reference Manual', for version 2.7.
Copyright (C) 1993, 1994, 1995, 1996, 1997, 1998, 1999, 2001, 2002,
2003, 2007 Free Software Foundation, Inc.
Permission is granted to copy, distribute and/or modify this document
under the terms of the GNU Free Documentation License, Version 1.2 or
any later version published by the Free Software Foundation; with the
Invariant Sections being ``Free Software Needs Free Documentation''
and ``GNU Lesser General Public License'', the Front-Cover texts being
``A GNU Manual'', and with the Back-Cover Texts as in (a) below. A
copy of the license is included in the section entitled "GNU Free
Documentation License".
(a) The FSF's Back-Cover Text is: ``You are free to copy and modify
this GNU Manual. Buying copies from GNU Press supports the FSF in
developing GNU and promoting software freedom.''-->
<meta http-equiv="Content-Style-Type" content="text/css">
<style type="text/css"><!--
pre.display { font-family:inherit }
pre.format { font-family:inherit }
pre.smalldisplay { font-family:inherit; font-size:smaller }
pre.smallformat { font-family:inherit; font-size:smaller }
pre.smallexample { font-size:smaller }
pre.smalllisp { font-size:smaller }
span.sc { font-variant:small-caps }
span.roman { font-family:serif; font-weight:normal; }
span.sansserif { font-family:sans-serif; font-weight:normal; }
--></style>
</head>
<body>
<div class="node">
<p>
<a name="Argz-Functions"></a>
Next: <a rel="next" accesskey="n" href="Envz-Functions.html#Envz-Functions">Envz Functions</a>,
Up: <a rel="up" accesskey="u" href="Argz-and-Envz-Vectors.html#Argz-and-Envz-Vectors">Argz and Envz Vectors</a>
<hr>
</div>
<h4 class="subsection">5.12.1 Argz Functions</h4>
<p>Each argz vector is represented by a pointer to the first element, of
type <code>char *</code>, and a size, of type <code>size_t</code>, both of which can
be initialized to <code>0</code> to represent an empty argz vector. All argz
functions accept either a pointer and a size argument, or pointers to
them, if they will be modified.
<p>The argz functions use <code>malloc</code>/<code>realloc</code> to allocate/grow
argz vectors, and so any argz vector creating using these functions may
be freed by using <code>free</code>; conversely, any argz function that may
grow a string expects that string to have been allocated using
<code>malloc</code> (those argz functions that only examine their arguments or
modify them in place will work on any sort of memory).
See <a href="Unconstrained-Allocation.html#Unconstrained-Allocation">Unconstrained Allocation</a>.
<p>All argz functions that do memory allocation have a return type of
<code>error_t</code>, and return <code>0</code> for success, and <code>ENOMEM</code> if an
allocation error occurs.
<p><a name="index-argz_002eh-590"></a>These functions are declared in the standard include file <samp><span class="file">argz.h</span></samp>.
<!-- argz.h -->
<!-- GNU -->
<div class="defun">
— Function: error_t <b>argz_create</b> (<var>char *const argv</var>[]<var>, char **argz, size_t *argz_len</var>)<var><a name="index-argz_005fcreate-591"></a></var><br>
<blockquote><p>The <code>argz_create</code> function converts the Unix-style argument vector
<var>argv</var> (a vector of pointers to normal C strings, terminated by
<code>(char *)0</code>; see <a href="Program-Arguments.html#Program-Arguments">Program Arguments</a>) into an argz vector with
the same elements, which is returned in <var>argz</var> and <var>argz_len</var>.
</p></blockquote></div>
<!-- argz.h -->
<!-- GNU -->
<div class="defun">
— Function: error_t <b>argz_create_sep</b> (<var>const char *string, int sep, char **argz, size_t *argz_len</var>)<var><a name="index-argz_005fcreate_005fsep-592"></a></var><br>
<blockquote><p>The <code>argz_create_sep</code> function converts the null-terminated string
<var>string</var> into an argz vector (returned in <var>argz</var> and
<var>argz_len</var>) by splitting it into elements at every occurrence of the
character <var>sep</var>.
</p></blockquote></div>
<!-- argz.h -->
<!-- GNU -->
<div class="defun">
— Function: size_t <b>argz_count</b> (<var>const char *argz, size_t arg_len</var>)<var><a name="index-argz_005fcount-593"></a></var><br>
<blockquote><p>Returns the number of elements in the argz vector <var>argz</var> and
<var>argz_len</var>.
</p></blockquote></div>
<!-- argz.h -->
<!-- GNU -->
<div class="defun">
— Function: void <b>argz_extract</b> (<var>char *argz, size_t argz_len, char **argv</var>)<var><a name="index-argz_005fextract-594"></a></var><br>
<blockquote><p>The <code>argz_extract</code> function converts the argz vector <var>argz</var> and
<var>argz_len</var> into a Unix-style argument vector stored in <var>argv</var>,
by putting pointers to every element in <var>argz</var> into successive
positions in <var>argv</var>, followed by a terminator of <code>0</code>.
<var>Argv</var> must be pre-allocated with enough space to hold all the
elements in <var>argz</var> plus the terminating <code>(char *)0</code>
(<code>(argz_count (</code><var>argz</var><code>, </code><var>argz_len</var><code>) + 1) * sizeof (char *)</code>
bytes should be enough). Note that the string pointers stored into
<var>argv</var> point into <var>argz</var>—they are not copies—and so
<var>argz</var> must be copied if it will be changed while <var>argv</var> is
still active. This function is useful for passing the elements in
<var>argz</var> to an exec function (see <a href="Executing-a-File.html#Executing-a-File">Executing a File</a>).
</p></blockquote></div>
<!-- argz.h -->
<!-- GNU -->
<div class="defun">
— Function: void <b>argz_stringify</b> (<var>char *argz, size_t len, int sep</var>)<var><a name="index-argz_005fstringify-595"></a></var><br>
<blockquote><p>The <code>argz_stringify</code> converts <var>argz</var> into a normal string with
the elements separated by the character <var>sep</var>, by replacing each
<code>'\0'</code> inside <var>argz</var> (except the last one, which terminates the
string) with <var>sep</var>. This is handy for printing <var>argz</var> in a
readable manner.
</p></blockquote></div>
<!-- argz.h -->
<!-- GNU -->
<div class="defun">
— Function: error_t <b>argz_add</b> (<var>char **argz, size_t *argz_len, const char *str</var>)<var><a name="index-argz_005fadd-596"></a></var><br>
<blockquote><p>The <code>argz_add</code> function adds the string <var>str</var> to the end of the
argz vector <code>*</code><var>argz</var>, and updates <code>*</code><var>argz</var> and
<code>*</code><var>argz_len</var> accordingly.
</p></blockquote></div>
<!-- argz.h -->
<!-- GNU -->
<div class="defun">
— Function: error_t <b>argz_add_sep</b> (<var>char **argz, size_t *argz_len, const char *str, int delim</var>)<var><a name="index-argz_005fadd_005fsep-597"></a></var><br>
<blockquote><p>The <code>argz_add_sep</code> function is similar to <code>argz_add</code>, but
<var>str</var> is split into separate elements in the result at occurrences of
the character <var>delim</var>. This is useful, for instance, for
adding the components of a Unix search path to an argz vector, by using
a value of <code>':'</code> for <var>delim</var>.
</p></blockquote></div>
<!-- argz.h -->
<!-- GNU -->
<div class="defun">
— Function: error_t <b>argz_append</b> (<var>char **argz, size_t *argz_len, const char *buf, size_t buf_len</var>)<var><a name="index-argz_005fappend-598"></a></var><br>
<blockquote><p>The <code>argz_append</code> function appends <var>buf_len</var> bytes starting at
<var>buf</var> to the argz vector <code>*</code><var>argz</var>, reallocating
<code>*</code><var>argz</var> to accommodate it, and adding <var>buf_len</var> to
<code>*</code><var>argz_len</var>.
</p></blockquote></div>
<!-- argz.h -->
<!-- GNU -->
<div class="defun">
— Function: void <b>argz_delete</b> (<var>char **argz, size_t *argz_len, char *entry</var>)<var><a name="index-argz_005fdelete-599"></a></var><br>
<blockquote><p>If <var>entry</var> points to the beginning of one of the elements in the
argz vector <code>*</code><var>argz</var>, the <code>argz_delete</code> function will
remove this entry and reallocate <code>*</code><var>argz</var>, modifying
<code>*</code><var>argz</var> and <code>*</code><var>argz_len</var> accordingly. Note that as
destructive argz functions usually reallocate their argz argument,
pointers into argz vectors such as <var>entry</var> will then become invalid.
</p></blockquote></div>
<!-- argz.h -->
<!-- GNU -->
<div class="defun">
— Function: error_t <b>argz_insert</b> (<var>char **argz, size_t *argz_len, char *before, const char *entry</var>)<var><a name="index-argz_005finsert-600"></a></var><br>
<blockquote><p>The <code>argz_insert</code> function inserts the string <var>entry</var> into the
argz vector <code>*</code><var>argz</var> at a point just before the existing
element pointed to by <var>before</var>, reallocating <code>*</code><var>argz</var> and
updating <code>*</code><var>argz</var> and <code>*</code><var>argz_len</var>. If <var>before</var>
is <code>0</code>, <var>entry</var> is added to the end instead (as if by
<code>argz_add</code>). Since the first element is in fact the same as
<code>*</code><var>argz</var>, passing in <code>*</code><var>argz</var> as the value of
<var>before</var> will result in <var>entry</var> being inserted at the beginning.
</p></blockquote></div>
<!-- argz.h -->
<!-- GNU -->
<div class="defun">
— Function: char * <b>argz_next</b> (<var>char *argz, size_t argz_len, const char *entry</var>)<var><a name="index-argz_005fnext-601"></a></var><br>
<blockquote><p>The <code>argz_next</code> function provides a convenient way of iterating
over the elements in the argz vector <var>argz</var>. It returns a pointer
to the next element in <var>argz</var> after the element <var>entry</var>, or
<code>0</code> if there are no elements following <var>entry</var>. If <var>entry</var>
is <code>0</code>, the first element of <var>argz</var> is returned.
<p>This behavior suggests two styles of iteration:
<pre class="smallexample"> char *entry = 0;
while ((entry = argz_next (<var>argz</var>, <var>argz_len</var>, entry)))
<var>action</var>;
</pre>
<p>(the double parentheses are necessary to make some C compilers shut up
about what they consider a questionable <code>while</code>-test) and:
<pre class="smallexample"> char *entry;
for (entry = <var>argz</var>;
entry;
entry = argz_next (<var>argz</var>, <var>argz_len</var>, entry))
<var>action</var>;
</pre>
<p>Note that the latter depends on <var>argz</var> having a value of <code>0</code> if
it is empty (rather than a pointer to an empty block of memory); this
invariant is maintained for argz vectors created by the functions here.
</p></blockquote></div>
<!-- argz.h -->
<!-- GNU -->
<div class="defun">
— Function: error_t <b>argz_replace</b> (<var>char **argz, size_t *argz_len<!-- /@w -->, const char *str, const char *with<!-- /@w -->, unsigned *replace_count<!-- /@w --></var>)<var><a name="index-argz_005freplace-602"></a></var><br>
<blockquote><p>Replace any occurrences of the string <var>str</var> in <var>argz</var> with
<var>with</var>, reallocating <var>argz</var> as necessary. If
<var>replace_count</var> is non-zero, <code>*</code><var>replace_count</var> will be
incremented by number of replacements performed.
</p></blockquote></div>
</body></html>