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 2021-03-22  "" "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 .PP
  19 .BI "error_t argz_add(char **restrict " argz ", size_t *restrict " argz_len ",
  20 .BI "                const char *restrict " str );
  21 .PP
  22 .BI "error_t argz_add_sep(char **restrict " argz \
  23 ", size_t *restrict " argz_len ,
  24 .BI "                const char *restrict " str ", int " delim );
  25 .PP
  26 .BI "error_t argz_append(char **restrict " argz ", size_t *restrict " argz_len ,
  27 .BI "                const char *restrict " buf ", size_t " buf_len );
  28 .PP
  29 .BI "size_t argz_count(const char *" argz ", size_t " argz_len );
  30 .PP
  31 .BI "error_t argz_create(char *const " argv "[], char **restrict " argz ,
  32 .BI "                size_t *restrict " argz_len );
  33 .PP
  34 .BI "error_t argz_create_sep(const char *restrict " str ", int " sep ,
  35 .BI "                char **restrict " argz ", size_t *restrict " argz_len );
  36 .PP
  37 .BI "void argz_delete(char **restrict " argz ", size_t *restrict " argz_len ,
  38 .BI "                char *restrict " entry );
  39 .PP
  40 .BI "void argz_extract(const char *restrict " argz ", size_t " argz_len ,
  41 .BI "                char **restrict " argv );
  42 .PP
  43 .BI "error_t argz_insert(char **restrict " argz ", size_t *restrict " argz_len ,
  44 .BI "                char *restrict " before ", const char *restrict " entry );
  45 .PP
  46 .BI "char *argz_next(const char *restrict " argz ", size_t " argz_len ,
  47 .BI "                const char *restrict " entry );
  48 .PP
  49 .BI "error_t argz_replace(char **restrict " argz \
  50 ", size_t *restrict " argz_len ,
  51 .BI "                const char *restrict " str ", const char *restrict " with ,
  52 .BI "                unsigned int *restrict " replace_count );
  53 .PP
  54 .BI "void argz_stringify(char *" argz ", size_t " len ", int " sep );
  55 .fi
  56 .SH DESCRIPTION
  57 These functions are glibc-specific.
  58 .PP
  59 An argz vector is a pointer to a character buffer together with a length.
  60 The intended interpretation of the character buffer is an array
  61 of strings, where the strings are separated by null bytes (\(aq\e0\(aq).
  62 If the length is nonzero, the last byte of the buffer must be a null byte.
  63 .PP
  64 These functions are for handling argz vectors.
  65 The pair (NULL,0) is an argz vector, and, conversely,
  66 argz vectors of length 0 must have null pointer.
  67 Allocation of nonempty argz vectors is done using
  68 .BR malloc (3),
  69 so that
  70 .BR free (3)
  71 can be used to dispose of them again.
  72 .PP
  73 .BR argz_add ()
  74 adds the string
  75 .I str
  76 at the end of the array
  77 .IR *argz ,
  78 and updates
  79 .I *argz
  80 and
  81 .IR *argz_len .
  82 .PP
  83 .BR argz_add_sep ()
  84 is similar, but splits the string
  85 .I str
  86 into substrings separated by the delimiter
  87 .IR delim .
  88 For example, one might use this on a UNIX search path with
  89 delimiter \(aq:\(aq.
  90 .PP
  91 .BR argz_append ()
  92 appends the argz vector
  93 .RI ( buf ,\  buf_len )
  94 after
  95 .RI ( *argz ,\  *argz_len )
  96 and updates
  97 .IR *argz
  98 and
  99 .IR *argz_len .
 100 (Thus,
 101 .I *argz_len
 102 will be increased by
 103 .IR buf_len .)
 104 .PP
 105 .BR argz_count ()
 106 counts the number of strings, that is,
 107 the number of null bytes (\(aq\e0\(aq), in
 108 .RI ( argz ,\  argz_len ).
 109 .PP
 110 .BR argz_create ()
 111 converts a UNIX-style argument vector
 112 .IR argv ,
 113 terminated by
 114 .IR "(char\ *)\ 0" ,
 115 into an argz vector
 116 .RI ( *argz ,\  *argz_len ).
 117 .PP
 118 .BR argz_create_sep ()
 119 converts the null-terminated string
 120 .I str
 121 into an argz vector
 122 .RI ( *argz ,\  *argz_len )
 123 by breaking it up at every occurrence of the separator
 124 .IR sep .
 125 .PP
 126 .BR argz_delete ()
 127 removes the substring pointed to by
 128 .I entry
 129 from the argz vector
 130 .RI ( *argz ,\  *argz_len )
 131 and updates
 132 .I *argz
 133 and
 134 .IR *argz_len .
 135 .PP
 136 .BR argz_extract ()
 137 is the opposite of
 138 .BR argz_create ().
 139 It takes the argz vector
 140 .RI ( argz ,\  argz_len )
 141 and fills the array starting at
 142 .I argv
 143 with pointers to the substrings, and a final NULL,
 144 making a UNIX-style argv vector.
 145 The array
 146 .I argv
 147 must have room for
 148 .IR argz_count ( argz ", " argz_len ") + 1"
 149 pointers.
 150 .PP
 151 .BR argz_insert ()
 152 is the opposite of
 153 .BR argz_delete ().
 154 It inserts the argument
 155 .I entry
 156 at position
 157 .I before
 158 into the argz vector
 159 .RI ( *argz ,\  *argz_len )
 160 and updates
 161 .I *argz
 162 and
 163 .IR *argz_len .
 164 If
 165 .I before
 166 is NULL, then
 167 .I entry
 168 will inserted at the end.
 169 .PP
 170 .BR argz_next ()
 171 is a function to step through the argz vector.
 172 If
 173 .I entry
 174 is NULL, the first entry is returned.
 175 Otherwise, the entry
 176 following is returned.
 177 It returns NULL if there is no following entry.
 178 .PP
 179 .BR argz_replace ()
 180 replaces each occurrence of
 181 .I str
 182 with
 183 .IR with ,
 184 reallocating argz as necessary.
 185 If
 186 .I replace_count
 187 is non-NULL,
 188 .I *replace_count
 189 will be incremented by the number of replacements.
 190 .PP
 191 .BR argz_stringify ()
 192 is the opposite of
 193 .BR argz_create_sep ().
 194 It transforms the argz vector into a normal string by replacing
 195 all null bytes (\(aq\e0\(aq) except the last by
 196 .IR sep .
 197 .SH RETURN VALUE
 198 All argz functions that do memory allocation have a return type of
 199 .IR error_t
 200 (an integer type),
 201 and return 0 for success, and
 202 .B ENOMEM
 203 if an allocation error occurs.
 204 .SH ATTRIBUTES
 205 For an explanation of the terms used in this section, see
 206 .BR attributes (7).
 207 .ad l
 208 .nh
 209 .TS
 210 allbox;
 211 lbx lb lb
 212 l l l.
 213 Interface       Attribute       Value
 214 T{
 215 .BR argz_add (),
 216 .BR argz_add_sep (),
 217 .BR argz_append (),
 218 .BR argz_count (),
 219 .BR argz_create (),
 220 .BR argz_create_sep (),
 221 .BR argz_delete (),
 222 .BR argz_extract (),
 223 .BR argz_insert (),
 224 .BR argz_next (),
 225 .BR argz_replace (),
 226 .BR argz_stringify ()
 227 T}      Thread safety   MT-Safe
 228 .TE
 229 .hy
 230 .ad
 231 .sp 1
 232 .SH CONFORMING TO
 233 These functions are a GNU extension.
 234 .SH BUGS
 235 Argz vectors without a terminating null byte may lead to
 236 Segmentation Faults.
 237 .SH SEE ALSO
 238 .BR envz_add (3)