| <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.13"> |
| <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.12, last updated 2007-10-27, |
| of `The GNU C Library Reference Manual', for version |
| 2.8 (Sourcery G++ Lite 2011.03-41). |
| |
| Copyright (C) 1993, 1994, 1995, 1996, 1997, 1998, 1999, 2001, 2002, |
| 2003, 2007, 2008, 2010 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.3 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 have the freedom to |
| copy and modify this GNU manual. Buying copies from the FSF |
| supports it 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> |
| <link rel="stylesheet" type="text/css" href="../cs.css"> |
| </head> |
| <body> |
| <div class="node"> |
| <a name="Argz-Functions"></a> |
| <p> |
| 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-591"></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-592"></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-593"></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-594"></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-595"></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-596"></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-597"></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-598"></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-599"></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-600"></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-601"></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-602"></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-603"></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> |
| |
