draft/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 .\"
   7 .\" Japanese Version Copyright (c) 2002 Akihiro MOTOKI, all rights reserved.
   8 .\" Translated Mon Feb  2 2003 by Akihiro MOTOKI <amotoki@dd.iij4u.or.jp>
   9 .\"
  10 .TH ARGZ_ADD 3 2007-05-18  "" "Linux Programmer's Manual"
  11 .\"O .SH NAME
  12 .SH Ì¾Á°
  13 .\"O argz_add, argz_add_sep, argz_append, argz_count, argz_create,
  14 .\"O argz_create_sep, argz_delete, argz_extract, argz_insert,
  15 .\"O argz_next, argz_replace, argz_stringify \- functions to handle an argz list
  16 argz_add, argz_add_sep, argz_append, argz_count, argz_create,
  17 argz_create_sep, argz_delete, argz_extract, argz_insert,
  18 argz_next, argz_replace, argz_stringify \- argz ¥ê¥¹¥È¤òÁàºî¤¹¤ë¤¿¤á¤Î´Ø¿ô·²
  19 .\"O .SH SYNOPSIS
  20 .SH ½ñ¼°
  21 .nf
  22 .B "#include <argz.h>"
  23 .sp
  24 .BI "error_t argz_add(char **" argz ", size_t *" argz_len \
  25 ", const char *" str );
  26 .sp
  27 .BI "error_t argz_add_sep(char **" argz ", size_t *" argz_len ,
  28 .ti 20n
  29 .BI "const char *" str ", int " delim );
  30 .sp
  31 .BI "error_t argz_append(char **" argz ", size_t *" argz_len ,
  32 .ti 20n
  33 .BI "const char *" buf ", size_t " buf_len );
  34 .sp
  35 .BI "size_t argz_count(const char *" argz ", size_t " argz_len );
  36 .sp
  37 .BI "error_t argz_create(char * const " argv "[], char **" argz ,
  38 .ti 20n
  39 .BI "size_t *" argz_len );
  40 .sp
  41 .BI "error_t argz_create_sep(const char *" str ", int " sep ", char **" argz ,
  42 .ti 20n
  43 .BI "size_t *" argz_len );
  44 .sp
  45 .BI "error_t argz_delete(char **" argz ", size_t *" argz_len ", char *" entry );
  46 .sp
  47 .BI "void argz_extract(char *" argz ", size_t " argz_len ", char  **" argv );
  48 .sp
  49 .BI "error_t argz_insert(char **" argz ", size_t *" argz_len ", char *" before ,
  50 .ti 20n
  51 .BI "const char *" entry );
  52 .sp
  53 .BI "char *argz_next(char *" argz ", size_t " argz_len ", const char *" entry );
  54 .sp
  55 .BI "error_t argz_replace(char **" argz ", size_t *" argz_len \
  56 ", const char *" str ,
  57 .ti 20n
  58 .BI "const char *" with ", unsigned int *" replace_count );
  59 .sp
  60 .BI "void argz_stringify(char *" argz ", size_t " len ", int " sep );
  61 .fi
  62 .\"O .SH DESCRIPTION
  63 .SH ÀâÌÀ
  64 .\"O These functions are glibc-specific.
  65 ¤³¤ì¤é¤Î´Ø¿ô¤Ï glibc ¸ÇÍ¤Ç¤¢¤ë¡£
  66 .LP
  67 .\"O An argz vector is a pointer to a character buffer together with a length.
  68 .\"O The intended interpretation of the character buffer is an array
  69 .\"O of strings, where the strings are separated by null bytes (\\(aq\\0\\(aq).
  70 .\"O If the length is nonzero, the last byte of the buffer must be a null byte.
  71 argz vector ¤ÏÄ¹¤µ¾ðÊóÉÕ¤¤ÎÊ¸»ú¥Ð¥Ã¥Õ¥¡¤Ø¤Î¥Ý¥¤¥ó¥¿¤Ç¤¢¤ë¡£
  72 Ê¸»ú¥Ð¥Ã¥Õ¥¡¤Ç¤Ï¡¢Ê£¿ô¤ÎÊ¸»úÎó¤¬ NULL ¥Ð¥¤¥È (\\(aq\\0\\(aq) ¤Ç¶èÀÚ¤é¤ì¤Æ¤ª¤ê¡¢
  73 Ê¸»úÎó¤ÎÇÛÎó¤È¤·¤Æ²ò¼á¤µ¤ì¤ë¤è¤¦¤Ë¤Ê¤Ã¤Æ¤¤¤ë¡£
  74 Ä¹¤µ¤¬ 0 ¤Ç¤Ê¤¤¾ì¹ç¡¢¥Ð¥Ã¥Õ¥¡¤ÎºÇ¸å¤Î¥Ð¥¤¥È¤Ï NULL ¥Ð¥¤¥È¤Ç¤Ê¤±¤ì¤Ð¤Ê¤é¤Ê¤¤¡£
  75 .LP
  76 .\"O These functions are for handling argz vectors.
  77 .\"O The pair (NULL,0) is an argz vector, and, conversely,
  78 .\"O argz vectors of length 0 must have NULL pointer.
  79 .\"O Allocation of nonempty argz vectors is done using
  80 .\"O .BR malloc (3),
  81 .\"O so that
  82 .\"O .BR free (3)
  83 .\"O can be used to dispose of them again.
  84 ¤³¤ì¤é¤Î´Ø¿ô¤Ï argz vector ¤òÁàºî¤¹¤ë¤¿¤á¤Î¤â¤Î¤Ç¤¢¤ë¡£
  85 ¥Ú¥¢ (NULL,0) ¤Ï argz vector ¤Ç¤¢¤ê¡¢µÕ¤Ë¸À¤¨¤Ð
  86 Ä¹¤µ 0 ¤Î argz vector¤Ï NULL ¥Ý¥¤¥ó¥¿¤ò»ý¤¿¤Ê¤±¤ì¤Ð¤Ê¤é¤Ê¤¤¡£
  87 ¶õ¤Ç¤Ê¤¤ argz vector ¤Î³ä¤êÅö¤Æ¤Ï
  88 .BR malloc (3)
  89 ¤ò»È¤Ã¤Æ¹Ô¤ï¤ì¤ë¡£¤·¤¿¤¬¤Ã¤Æ¡¢argz vector ¤ò²òÊü¤¹¤ë¤Î¤Ë
  90 .BR free (3)
  91 ¤ò»È¤¦¤³¤È¤¬¤Ç¤¤ë¡£
  92 .LP
  93 .\"O .BR argz_add ()
  94 .\"O adds the string
  95 .\"O .I str
  96 .\"O at the end of the array
  97 .\"O .IR *argz ,
  98 .\"O and updates
  99 .\"O .IR *argz
 100 .\"O and
 101 .\"O .IR *argz_len .
 102 .BR argz_add ()
 103 ¤Ï¡¢Ê¸»úÎó
 104 .I str
 105 ¤òÇÛÎó
 106 .IR *argz
 107 ¤ÎËöÈø¤ËÄÉ²Ã¤·¡¢
 108 .IR *argz
 109 ¤È
 110 .IR *argz_len
 111 ¤ò¹¹¿·¤¹¤ë¡£
 112 .LP
 113 .\"O .BR argz_add_sep ()
 114 .\"O is similar, but splits the string
 115 .\"O .I str
 116 .\"O into substrings separated by the delimiter
 117 .\"O .IR delim .
 118 .\"O For example, one might use this on a Unix search path with
 119 .\"O delimiter \\(aq:\\(aq.
 120 .BR argz_add_sep ()
 121 ¤âÆ±ÍÍ¤ÎÆ°ºî¤ò¤¹¤ë¤¬¡¢¶èÀÚ¤êÊ¸»ú
 122 .I delim
 123 ¤Ë¤·¤¿¤¬¤Ã¤ÆÊ¸»úÎó
 124 .I str
 125 ¤òÊ£¿ô¤ÎÊ¸»úÎó¤ËÊ¬³ä¤¹¤ëÅÀ¤¬°Û¤Ê¤ë¡£
 126 Îã¤¨¤Ð¡¢¶èÀÚ¤êÊ¸»ú \\(aq:\\(aq ¤ò»ØÄê¤·¤Æ¡¢Unix ¥µ¡¼¥Á¡¦¥Ñ¥¹¤ËÂÐ¤·¤Æ
 127 ¤³¤Î´Ø¿ô¤ò»È¤¦¤³¤È¤¬¤Ç¤¤ë¤À¤í¤¦¡£
 128 .LP
 129 .\"O .BR argz_append ()
 130 .\"O appends the argz vector
 131 .\"O .RI ( buf ,\  buf_len )
 132 .\"O after
 133 .\"O .RI (* argz ,\  *argz_len )
 134 .\"O and updates
 135 .\"O .IR *argz
 136 .\"O and
 137 .\"O .IR *argz_len .
 138 .\"O (Thus,
 139 .\"O .I *argz_len
 140 .\"O will be increased by
 141 .\"O .IR buf_len .)
 142 .BR argz_append ()
 143 ¤Ï argz vector
 144 .RI ( buf ,\  buf_len )
 145 ¤Î¸å¤í¤Ë
 146 .RI (* argz ,\  *argz_len )
 147 ¤òÉÕ¤±²Ã¤¨¡¢
 148 .I *argz
 149 ¤È
 150 .I *argz_len
 151 ¤ò¹¹¿·¤¹¤ë¡£
 152 (¤·¤¿¤¬¤Ã¤Æ¡¢
 153 .I *argz_len
 154 ¤Ï
 155 .I buf_len
 156 ¤À¤±Áý²Ã¤¹¤ë¡£)
 157 .LP
 158 .\"O .BR argz_count ()
 159 .\"O counts the number of strings, that is,
 160 .\"O the number of null bytes (\\(aq\\0\\(aq), in
 161 .\"O .RI ( argz ,\  argz_len ).
 162 .BR argz_count ()
 163 ¤Ï
 164 .RI ( argz ,\  argz_len )
 165 Æâ¤ÎÊ¸»úÎó¤Î¿ô¤ò¿ô¤¨¤ë¡£¼ÂºÝ¤Ë¤Ï NULL ¥Ð¥¤¥È (\\(aq\\0\\(aq) ¤Î¿ô¤ò¿ô¤¨¤Æ¤¤¤ë¡£
 166 .LP
 167 .\"O .BR argz_create ()
 168 .\"O converts a Unix-style argument vector
 169 .\"O .IR argv ,
 170 .\"O terminated by
 171 .\"O .IR "(char *) 0" ,
 172 .\"O into an argz vector
 173 .\"O .RI ( *argz ,\  *argz_len ).
 174 .BR argz_create ()
 175 ¤Ï¡¢Unix Î®¤Î°ú¤¿ô¥Ù¥¯¥È¥ë¤Ç¤¢¤ë
 176 .RI ( "(char *) 0"
 177 ¤Ç½ªÃ¼¤µ¤ì¤ë)
 178 .I argv
 179 ¤ò¡¢argz vector
 180 .RI ( *argz ,\  *argz_len )
 181 ¤ËÊÑ´¹¤¹¤ë¡£
 182 .LP
 183 .\"O .BR argz_create_sep ()
 184 .\"O converts the null-terminated string
 185 .\"O .I str
 186 .\"O into an argz vector
 187 .\"O .RI (* argz ,\  *argz_len )
 188 .\"O by breaking it up at every occurrence of the separator
 189 .\"O .IR sep .
 190 .BR argz_create_sep ()
 191 ¤Ï¡¢NULL ½ªÃ¼¤µ¤ì¤¿Ê¸»úÎó
 192 .I str
 193 ¤ò¶èÀÚ¤êÊ¸»ú
 194 .I sep
 195 ¤¬¸½¤ì¤ëËè¤ËÊ¬³ä¤·¤Ê¤¬¤é¡¢argz vector
 196 .RI (* argz ,\  *argz_len )
 197 ¤ËÊÑ´¹¤¹¤ë¡£
 198 .LP
 199 .\"O .BR argz_delete ()
 200 .\"O removes the substring pointed to by
 201 .\"O .I entry
 202 .\"O from the argz vector
 203 .\"O .RI ( *argz ,\  *argz_len )
 204 .\"O and updates
 205 .\"O .I *argz
 206 .\"O and
 207 .\"O .IR *argz_len .
 208 .BR argz_delete ()
 209 ¤Ï¡¢
 210 .I entry
 211 ¤Ç»Ø¤·¼¨¤µ¤ì¤¿Ê¸»úÎó¤ò argz vector
 212 .RI ( *argz ,\  *argz_len )
 213 ¤«¤éºï½ü¤·¡¢
 214 .I *argz
 215 ¤È
 216 .I *argz_len
 217 ¤ò¹¹¿·¤¹¤ë¡£
 218 .LP
 219 .\"O .BR argz_extract ()
 220 .\"O is the opposite of
 221 .\"O .BR argz_create ().
 222 .\"O It takes the argz vector
 223 .\"O .RI ( argz ,\  argz_len )
 224 .\"O and fills the array starting at
 225 .\"O .I argv
 226 .\"O with pointers to the substrings, and a final NULL,
 227 .\"O making a Unix-style argv vector.
 228 .\"O The array
 229 .\"O .I argv
 230 .\"O must have room for
 231 .\"O .IR argz_count ( argz , argz_len ") + 1"
 232 .\"O pointers.
 233 .BR argz_extract ()
 234 ¤Ï
 235 .BR argz_create ()
 236 ¤ÎÈ¿ÂÐ¤ÎÁàºî¤ò¹Ô¤¦¡£argz vector
 237 .RI ( argz ,\  argz_len )
 238 ¤òÄ´¤Ù¡¢
 239 .I argv
 240 ¤«¤é»Ï¤Þ¤ëÇÛÎó¤ò¥µ¥ÖÊ¸»úÎó¤Ø¤Î¥Ý¥¤¥ó¥¿¤ÇËä¤á¤Æ¤¤¤¡¢
 241 °ìÈÖºÇ¸å¤Ë NULL ¤òÆþ¤ì¤Æ¡¢Unix Î®¤Î argv ¥Ù¥¯¥È¥ë¤òºîÀ®¤¹¤ë¡£
 242 ÇÛÎó
 243 .I argv
 244 ¤Ï
 245 .IR argz_count ( argz , argz_len ") + 1"
 246 ¸Ä¤Î¥Ý¥¤¥ó¥¿¤ò¼ýÍÆ¤Ç¤¤ë¶õ´Ö¤ò»ý¤Ã¤Æ¤¤¤Ê¤±¤ì¤Ð¤Ê¤é¤Ê¤¤¡£
 247 .LP
 248 .\"O .BR argz_insert ()
 249 .\"O is the opposite of
 250 .\"O .BR argz_delete ().
 251 .\"O It inserts the argument
 252 .\"O .I entry
 253 .\"O at position
 254 .\"O .I before
 255 .\"O into the argz vector
 256 .\"O .RI ( *argz ,\  *argz_len )
 257 .\"O and updates
 258 .\"O .I *argz
 259 .\"O and
 260 .\"O .I *argz_len .
 261 .\"O If
 262 .\"O .I before
 263 .\"O is NULL, then
 264 .\"O .I entry
 265 .\"O will inserted at the end.
 266 .BR argz_insert ()
 267 ¤Ï
 268 .BR argz_delete ()
 269 ¤ÎÈ¿ÂÐ¤ÎÁàºî¤ò¹Ô¤¦¡£argz vector
 270 .RI ( *argz ,\  *argz_len )
 271 ¤Î°ÌÃÖ
 272 .I before
 273 ¤Ë°ú¤¿ô
 274 .I entry
 275 ¤òÁÞÆþ¤·¡¢
 276 .I *argz
 277 ¤È
 278 .I *argz_len
 279 ¤ò¹¹¿·¤¹¤ë¡£
 280 .I before
 281 ¤¬ NULL ¤Î¾ì¹ç¡¢
 282 .I entry
 283 ¤ÏËöÈø¤ËÁÞÆþ¤µ¤ì¤ë¡£
 284 .LP
 285 .\"O .BR argz_next ()
 286 .\"O is a function to step trough the argz vector.
 287 .\"O If
 288 .\"O .I entry
 289 .\"O is NULL, the first entry is returned.
 290 .\"O Otherwise, the entry
 291 .\"O following is returned.
 292 .\"O It returns NULL if there is no following entry.
 293 .BR argz_next ()
 294 ¤Ï argz vector ¤ò½çÈÖ¤ËÄ´¤Ù¤ë¤¿¤á¤Î´Ø¿ô¤Ç¤¢¤ë¡£
 295 .I entry
 296 ¤¬ NULL ¤Î¾ì¹ç¡¢ºÇ½é¤Î¥¨¥ó¥È¥ê¤òÊÖ¤¹¡£
 297 ¤½¤¦¤Ç¤Ê¤¤¾ì¹ç¡¢¼¡¤Î¥¨¥ó¥È¥ê¤òÊÖ¤¹¡£
 298 ¼¡¤Î¥¨¥ó¥È¥ê¤¬¤Ê¤¤¾ì¹ç¡¢NULL ¤òÊÖ¤¹¡£
 299 .LP
 300 .\"O .BR argz_replace ()
 301 .\"O replaces each occurrence of
 302 .\"O .I str
 303 .\"O with
 304 .\"O .IR with ,
 305 .\"O reallocating argz as necessary.
 306 .\"O If
 307 .\"O .I replace_count
 308 .\"O is non-NULL,
 309 .\"O .I *replace_count
 310 .\"O will be incremented by the number of replacements.
 311 .BR argz_replace ()
 312 ¤Ï¡¢
 313 .I str
 314 ¤ò¤¹¤Ù¤Æ
 315 .I with
 316 ¤ÇÃÖ¤´¹¤¨¤ë (É¬Í×¤Ë±þ¤¸¤Æ argz ¤ÎºÆ³ä¤êÅö¤Æ¤ò¹Ô¤¦)¡£
 317 .I replace_count
 318 ¤¬ NULL ¤Ç¤Ê¤¤¾ì¹ç¡¢
 319 .I *replace_count
 320 ¤òÃÖ¤´¹¤¨¤ò¹Ô¤Ã¤¿¿ô¤À¤±Áý¤ä¤¹¡£
 321 .LP
 322 .\"O .BR argz_stringify ()
 323 .\"O is the opposite of
 324 .\"O .BR argz_create_sep ().
 325 .\"O It transforms the argz vector into a normal string by replacing
 326 .\"O all null bytes (\\(aq\\0\\(aq) except the last by
 327 .\"O .IR sep .
 328 .BR argz_stringify ()
 329 ¤Ï
 330 .BR argz_create_sep ()
 331 ¤ÎÈ¿ÂÐ¤ÎÁàºî¤ò¹Ô¤¦¡£
 332 ËöÈø¤Î NULL ¥Ð¥¤¥È°Ê³°¤ÎÁ´¤Æ¤Î NULL ¥Ð¥¤¥È (\\(aq\\0\\(aq) ¤ò
 333 .I sep
 334 ¤ÇÃÖ¤´¹¤¨¤Æ¡¢
 335 argz vector ¤òÄÌ¾ï¤ÎÊ¸»úÎó¤ËÊÑ´¹¤¹¤ë¡£
 336 .\"O .SH "RETURN VALUE"
 337 .SH ÊÖ¤êÃÍ
 338 .\"O All argz functions that do memory allocation have a return type of
 339 .\"O \fIerror_t\fP, and return 0 for success, and \fBENOMEM\fP
 340 .\"O if an allocation error occurs.
 341 ¥á¥â¥ê³ä¤êÅö¤Æ¤ò¹Ô¤¦ argz ´Ø¿ô·²¤Ï¤¹¤Ù¤Æ \fIerror_t\fP ·¿¤ÎÊÖ¤êÃÍ¤ò»ý¤Ä¡£
 342 À®¸ù¤·¤¿¾ì¹ç¤Ï 0 ¤òÊÖ¤·¡¢³ä¤êÅö¤Æ¥¨¥é¡¼¤¬È¯À¸¤·¤¿¾ì¹ç¤Ï
 343 \fBENOMEM\fP ¤òÊÖ¤¹¡£
 344 .\"O .SH CONFORMING TO
 345 .SH ½àµò
 346 .\"O These functions are a GNU extension.
 347 .\"O Handle with care.
 348 ¤³¤ì¤é¤Î´Ø¿ô¤Ï GNU ¤Ë¤è¤ë³ÈÄ¥¤Ç¤¢¤ë¡£Ãí°Õ¤·¤Æ»ÈÍÑ¤¹¤ë¤³¤È¡£
 349 .\"O .SH BUGS
 350 .SH ¥Ð¥°
 351 .\"O Argz vectors without a terminating null byte may lead to
 352 .\"O Segmentation Faults.
 353 NULL ¥Ð¥¤¥È¤Ç½ªÃ¼¤µ¤ì¤Æ¤¤¤Ê¤¤ argz vector ¤ò»ÈÍÑ¤·¤¿¾ì¹ç¡¢
 354 segmentation fault ¤òµ¯¤³¤¹¤«¤â¤·¤ì¤Ê¤¤¡£
 355 .\"O .SH "SEE ALSO"
 356 .SH ´ØÏ¢¹àÌÜ
 357 .BR envz_add (3)