original/man3/argz_add.3

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