ossp-pkg/lmtp2nntp/argz.html
<HTML>
<HEAD>
<!-- Created by texi2html 1.56k from argz.texi on 25 July 2001 -->
<TITLE>Untitled Document</TITLE>
</HEAD>
<BODY>
<H1>Untitled Document</H1>
<P>
<P><HR><P>
<H2><A NAME="SEC1" HREF="argz_toc.html#TOC1">Argz Vectors</A></H2>
<P>
<A NAME="IDX1"></A>
<A NAME="IDX2"></A>
<A NAME="IDX3"></A>
<EM>argz vectors</EM> are vectors of strings in a contiguous block of
memory, each element separated from its neighbors by null-characters
(<CODE>'\0'</CODE>).
<H3><A NAME="SEC2" HREF="argz_toc.html#TOC2">Argz Functions</A></H3>
<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).
<P>
All argz functions that do memory allocation have a return type of
<CODE>int</CODE>, and return <CODE>0</CODE> for success, and <CODE>ENOMEM</CODE> if an
allocation error occurs.
<P>
<A NAME="IDX4"></A>
These functions are declared in the standard include file <TT>`argz.h'</TT>.
<P>
<DL>
<DT><U>Function:</U> int <B>argz_create</B> <I>(char *const <VAR>argv</VAR>[], char **<VAR>argz</VAR>, size_t *<VAR>argz_len</VAR>)</I>
<DD><A NAME="IDX5"></A>
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>;) into an argz vector with
the same elements, which is returned in <VAR>argz</VAR> and <VAR>argz_len</VAR>.
</DL>
<P>
<DL>
<DT><U>Function:</U> int <B>argz_create_sep</B> <I>(const char *<VAR>string</VAR>, int <VAR>sep</VAR>, char **<VAR>argz</VAR>, size_t *<VAR>argz_len</VAR>)</I>
<DD><A NAME="IDX6"></A>
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>.
</DL>
<P>
<DL>
<DT><U>Function:</U> size_t <B>argz_count</B> <I>(const char *<VAR>argz</VAR>, size_t <VAR>arg_len</VAR>)</I>
<DD><A NAME="IDX7"></A>
Returns the number of elements in the argz vector <VAR>argz</VAR> and
<VAR>argz_len</VAR>.
</DL>
<P>
<DL>
<DT><U>Function:</U> void <B>argz_extract</B> <I>(char *<VAR>argz</VAR>, size_t <VAR>argz_len</VAR>, char **<VAR>argv</VAR>)</I>
<DD><A NAME="IDX8"></A>
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 (<VAR>argz</VAR>, <VAR>argz_len</VAR>) + 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.
</DL>
<P>
<DL>
<DT><U>Function:</U> void <B>argz_stringify</B> <I>(char *<VAR>argz</VAR>, size_t <VAR>len</VAR>, int <VAR>sep</VAR>)</I>
<DD><A NAME="IDX9"></A>
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.
</DL>
<P>
<DL>
<DT><U>Function:</U> int <B>argz_add</B> <I>(char **<VAR>argz</VAR>, size_t *<VAR>argz_len</VAR>, const char *<VAR>str</VAR>)</I>
<DD><A NAME="IDX10"></A>
The <CODE>argz_add</CODE> function adds the string <VAR>str</VAR> to the end of the
argz vector <CODE>*<VAR>argz</VAR></CODE>, and updates <CODE>*<VAR>argz</VAR></CODE> and
<CODE>*<VAR>argz_len</VAR></CODE> accordingly.
</DL>
<P>
<DL>
<DT><U>Function:</U> int <B>argz_add_sep</B> <I>(char **<VAR>argz</VAR>, size_t *<VAR>argz_len</VAR>, const char *<VAR>str</VAR>, int <VAR>delim</VAR>)</I>
<DD><A NAME="IDX11"></A>
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>.
</DL>
<P>
<DL>
<DT><U>Function:</U> int <B>argz_append</B> <I>(char **<VAR>argz</VAR>, size_t *<VAR>argz_len</VAR>, const char *<VAR>buf</VAR>, size_t <VAR>buf_len</VAR>)</I>
<DD><A NAME="IDX12"></A>
The <CODE>argz_append</CODE> function appends <VAR>buf_len</VAR> bytes starting at
<VAR>buf</VAR> to the argz vector <CODE>*<VAR>argz</VAR></CODE>, reallocating
<CODE>*<VAR>argz</VAR></CODE> to accommodate it, and adding <VAR>buf_len</VAR> to
<CODE>*<VAR>argz_len</VAR></CODE>.
</DL>
<P>
<DL>
<DT><U>Function:</U> int <B>argz_delete</B> <I>(char **<VAR>argz</VAR>, size_t *<VAR>argz_len</VAR>, char *<VAR>entry</VAR>)</I>
<DD><A NAME="IDX13"></A>
If <VAR>entry</VAR> points to the beginning of one of the elements in the
argz vector <CODE>*<VAR>argz</VAR></CODE>, the <CODE>argz_delete</CODE> function will
remove this entry and reallocate <CODE>*<VAR>argz</VAR></CODE>, modifying
<CODE>*<VAR>argz</VAR></CODE> and <CODE>*<VAR>argz_len</VAR></CODE> 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.
</DL>
<P>
<DL>
<DT><U>Function:</U> int <B>argz_insert</B> <I>(char **<VAR>argz</VAR>, size_t *<VAR>argz_len</VAR>, char *<VAR>before</VAR>, const char *<VAR>entry</VAR>)</I>
<DD><A NAME="IDX14"></A>
The <CODE>argz_insert</CODE> function inserts the string <VAR>entry</VAR> into the
argz vector <CODE>*<VAR>argz</VAR></CODE> at a point just before the existing
element pointed to by <VAR>before</VAR>, reallocating <CODE>*<VAR>argz</VAR></CODE> and
updating <CODE>*<VAR>argz</VAR></CODE> and <CODE>*<VAR>argz_len</VAR></CODE>. 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>*<VAR>argz</VAR></CODE>, passing in <CODE>*<VAR>argz</VAR></CODE> as the value of
<VAR>before</VAR> will result in <VAR>entry</VAR> being inserted at the beginning.
</DL>
<P>
<DL>
<DT><U>Function:</U> char * <B>argz_next</B> <I>(char *<VAR>argz</VAR>, size_t <VAR>argz_len</VAR>, const char *<VAR>entry</VAR>)</I>
<DD><A NAME="IDX15"></A>
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>
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>
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.
</DL>
<P>
<DL>
<DT><U>Function:</U> int <B>argz_replace</B> <I>(char **<VAR>argz</VAR>, size_t *<VAR>argz_len</VAR>, const char *<VAR>str</VAR>, const char *<VAR>with</VAR>, unsigned *<VAR>replace_count</VAR>)</I>
<DD><A NAME="IDX16"></A>
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>*<VAR>replace_count</VAR></CODE> will be
incremented by number of replacements performed.
</DL>
<P><HR><P>
This document was generated on 25 July 2001 using
<A HREF="http://wwwinfo.cern.ch/dis/texi2html/">texi2html</A> 1.56k.
</BODY>
</HTML>
