release/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 .SH 名前
  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 \- argz リストを操作するための関数群
  15 .SH 書式
  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 説明
  58 これらの関数は glibc 固有である。
  59 .LP
  60 argz vector は長さ情報付きの文字バッファへのポインタである。
  61 文字バッファでは、複数の文字列が NULL バイト (\\(aq\\0\\(aq) で区切られており、
  62 文字列の配列として解釈されるようになっている。
  63 長さが 0 でない場合、バッファの最後のバイトは NULL バイトでなければならない。
  64 .LP
  65 これらの関数は argz vector を操作するためのものである。
  66 ペア (NULL,0) は argz vector であり、逆に言えば
  67 長さ 0 の argz vectorは NULL ポインタを持たなければならない。
  68 空でない argz vector の割り当ては
  69 .BR malloc (3)
  70 を使って行われる。したがって、argz vector を解放するのに
  71 .BR free (3)
  72 を使うことができる。
  73 .LP
  74 .BR argz_add ()
  75 は、文字列
  76 .I str
  77 を配列
  78 .IR *argz
  79 の末尾に追加し、
  80 .IR *argz
  81 と
  82 .IR *argz_len
  83 を更新する。
  84 .LP
  85 .BR argz_add_sep ()
  86 も同様の動作をするが、区切り文字
  87 .I delim
  88 にしたがって文字列
  89 .I str
  90 を複数の文字列に分割する点が異なる。
  91 例えば、区切り文字 \\(aq:\\(aq を指定して、UNIX サーチ・パスに対して
  92 この関数を使うことができるだろう。
  93 .LP
  94 .BR argz_append ()
  95 は argz vector
  96 .RI ( buf ,\  buf_len )
  97 の後ろに
  98 .RI (* argz ,\  *argz_len )
  99 を付け加え、
 100 .I *argz
 101 と
 102 .I *argz_len
 103 を更新する。
 104 (したがって、
 105 .I *argz_len
 106 は
 107 .I buf_len
 108 だけ増加する。)
 109 .LP
 110 .BR argz_count ()
 111 は
 112 .RI ( argz ,\  argz_len )
 113 内の文字列の数を数える。実際には NULL バイト (\\(aq\\0\\(aq) の数を数えている。
 114 .LP
 115 .BR argz_create ()
 116 は、UNIX 流の引き数ベクトルである
 117 .RI ( "(char *) 0"
 118 で終端される)
 119 .I argv
 120 を、argz vector
 121 .RI ( *argz ,\  *argz_len )
 122 に変換する。
 123 .LP
 124 .BR argz_create_sep ()
 125 は、NULL 終端された文字列
 126 .I str
 127 を区切り文字
 128 .I sep
 129 が現れる毎に分割しながら、argz vector
 130 .RI (* argz ,\  *argz_len )
 131 に変換する。
 132 .LP
 133 .BR argz_delete ()
 134 は、
 135 .I entry
 136 で指し示された文字列を argz vector
 137 .RI ( *argz ,\  *argz_len )
 138 から削除し、
 139 .I *argz
 140 と
 141 .I *argz_len
 142 を更新する。
 143 .LP
 144 .BR argz_extract ()
 145 は
 146 .BR argz_create ()
 147 の反対の操作を行う。argz vector
 148 .RI ( argz ,\  argz_len )
 149 を調べ、
 150 .I argv
 151 から始まる配列をサブ文字列へのポインタで埋めていき、
 152 一番最後に NULL を入れて、UNIX 流の argv ベクトルを作成する。
 153 配列
 154 .I argv
 155 は
 156 .IR argz_count ( argz , argz_len ") + 1"
 157 個のポインタを収容できる空間を持っていなければならない。
 158 .LP
 159 .BR argz_insert ()
 160 は
 161 .BR argz_delete ()
 162 の反対の操作を行う。argz vector
 163 .RI ( *argz ,\  *argz_len )
 164 の位置
 165 .I before
 166 に引き数
 167 .I entry
 168 を挿入し、
 169 .I *argz
 170 と
 171 .I *argz_len
 172 を更新する。
 173 .I before
 174 が NULL の場合、
 175 .I entry
 176 は末尾に挿入される。
 177 .LP
 178 .BR argz_next ()
 179 は argz vector を順番に調べるための関数である。
 180 .I entry
 181 が NULL の場合、最初のエントリを返す。
 182 そうでない場合、次のエントリを返す。
 183 次のエントリがない場合、NULL を返す。
 184 .LP
 185 .BR argz_replace ()
 186 は、
 187 .I str
 188 をすべて
 189 .I with
 190 で置き換える (必要に応じて argz の再割り当てを行う)。
 191 .I replace_count
 192 が NULL でない場合、
 193 .I *replace_count
 194 を置き換えを行った数だけ増やす。
 195 .LP
 196 .BR argz_stringify ()
 197 は
 198 .BR argz_create_sep ()
 199 の反対の操作を行う。
 200 末尾の NULL バイト以外の全ての NULL バイト (\\(aq\\0\\(aq) を
 201 .I sep
 202 で置き換えて、
 203 argz vector を通常の文字列に変換する。
 204 .SH 返り値
 205 メモリ割り当てを行う argz 関数群はすべて \fIerror_t\fP 型の返り値を持つ。
 206 成功した場合は 0 を返し、割り当てエラーが発生した場合は
 207 \fBENOMEM\fP を返す。
 208 .SH 準拠
 209 これらの関数は GNU による拡張である。注意して使用すること。
 210 .SH バグ
 211 NULL バイトで終端されていない argz vector を使用した場合、
 212 segmentation fault を起こすかもしれない。
 213 .SH 関連項目
 214 .BR envz_add (3)