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)