original/man3/argz_add.3

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