release/man3/wordexp.3

   1 .\" Copyright (c) 2003 Andries Brouwer (aeb@cwi.nl)
   2 .\"
   3 .\" This is free documentation; you can redistribute it and/or
   4 .\" modify it under the terms of the GNU General Public License as
   5 .\" published by the Free Software Foundation; either version 2 of
   6 .\" the License, or (at your option) any later version.
   7 .\"
   8 .\" The GNU General Public License's references to "object code"
   9 .\" and "executables" are to be interpreted as the output of any
  10 .\" document formatting or typesetting system, including
  11 .\" intermediate and printed output.
  12 .\"
  13 .\" This manual is distributed in the hope that it will be useful,
  14 .\" but WITHOUT ANY WARRANTY; without even the implied warranty of
  15 .\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  16 .\" GNU General Public License for more details.
  17 .\"
  18 .\" You should have received a copy of the GNU General Public
  19 .\" License along with this manual; if not, write to the Free
  20 .\" Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111,
  21 .\" USA.
  22 .\"
  23 .\" Japanese Version Copyright (c) 2004 Yuichi SATO
  24 .\"         all rights reserved.
  25 .\" Translated Sun Sep 12 05:05:19 JST 2004
  26 .\"         by Yuichi SATO <ysato444@yahoo.co.jp>
  27 .\"
  28 .TH WORDEXP 3 2008-07-14  "" "Linux Programmer's Manual"
  29 .SH 名前
  30 wordexp, wordfree \- posix シェルのように単語の展開を行う
  31 .SH 書式
  32 .B "#include <wordexp.h>"
  33 .sp
  34 .BI "int wordexp(const char *" s ", wordexp_t *" p ", int " flags );
  35 .sp
  36 .BI "void wordfree(wordexp_t *" p );
  37 .sp
  38 .in -4n
  39 glibc 向けの機能検査マクロの要件
  40 .RB ( feature_test_macros (7)
  41 参照):
  42 .in
  43 .sp
  44 .BR wordexp (),
  45 .BR wordfree ():
  46 _XOPEN_SOURCE
  47 .SH 説明
  48 関数
  49 .BR wordexp ()
  50 はシェルのように文字列
  51 .I s
  52 を展開し、
  53 .I p
  54 で指し示す構造体に結果を返す。
  55 データ型
  56 .I wordexp_t
  57 は少なくともフィールド
  58 .IR we_wordc ,
  59 .IR we_wordv ,
  60 .I we_offs
  61 を持つ構造体である。
  62 フィールド
  63 .I we_wordc
  64 は
  65 .I size_t
  66 であり、
  67 .I s
  68 を展開した結果に単語がいくつあるかを表す。
  69 フィールド
  70 .I we_wordv
  71 は
  72 .I char **
  73 であり、見つかった単語の配列を指し示す。
  74 .I size_t
  75 型のフィールド
  76 .I we_offs
  77 は、
  78 .I we_wordv
  79 配列にある初期要素のうちいくつが
  80 NULL で埋められるべきかを表すのに使われたりする
  81 .RI ( flags
  82 により決定される。下記を参照。)。
  83 .LP
  84 関数
  85 .BR wordfree ()
  86 は割り当てたメモリを再度解放する。
  87 より正確にいうと、この関数はその引き数を解放するのではなく、
  88 配列
  89 .I we_wordv
  90 とそれが指し示す文字列を解放する。
  91 .SS "文字列引き数"
  92 この展開はシェルによるコマンドのパラメータの展開
  93 .RB ( sh (1)
  94 を参照) と同じであるので、文字列
  95 .I s
  96 はシェルコマンドパラメータで不正とされる文字を含んではならない。
  97 特にエスケープされていない改行、|, &, ;, <, >, (, ), {, } 文字を
  98 コマンド置換やパラメータ置換の場面以外に含めてはならない。
  99 .LP
 100 引き数
 101 .I s
 102 にクォートしていないコメント文字 # で始まる単語が含まれている場合には、
 103 その単語とそれ以降の単語が無視されるか、
 104 それとも # がコメント文字として扱わないかは、規定されていない。
 105 .SS "展開"
 106 実行される展開は、以下の段階で構成される:
 107 チルダ展開 (~user を user のホームディレクトリに置き換える)、
 108 変数展開 ($FOO を環境変数 FOO の値に置き換える)、
 109 コマンド展開 ($(command) または \`command\` を command の出力で置き換える)、
 110 算術展開、フィールド分割、ワイルドカード展開、クォートの除去。
 111 .LP
 112 特殊なパラメータ ($@, $*, $#, $?, $\-, $$, $!, $0) の
 113 展開結果は規定されていない。
 114 .LP
 115 フィールド分割は環境変数 $IFS を用いて行われる。
 116 この環境変数が設定されていない場合、
 117 フィールド区切り文字はスペース・タブ・改行である。
 118 .SS "出力される配列"
 119 配列
 120 .I we_wordv
 121 は見つかった単語をを含み、最後に NULL が続く。
 122 .SS "flags 引き数"
 123 .I flags
 124 引き数は以下の値のビット包含的 OR である:
 125 .TP
 126 .B WRDE_APPEND
 127 見つかった単語を前回の呼び出し結果の配列に追加する。
 128 .TP
 129 .B WRDE_DOOFFS
 130 初期状態である
 131 .I we_offs
 132 個の NULL を配列
 133 .I we_wordv
 134 に挿入する (これらは返される
 135 .I we_wordc
 136 にはカウントされない)。
 137 .TP
 138 .B WRDE_NOCMD
 139 コマンド置換を行わない。
 140 .TP
 141 .B WRDE_REUSE
 142 引き数
 143 .I p
 144 は前回の
 145 .BR wordexp ()
 146 の呼び出し結果であり、
 147 .BR wordfree ()
 148 が (まだ) 呼び出されない。
 149 割り当てられた領域を再利用する。
 150 .TP
 151 .B WRDE_SHOWERR
 152 通常はコマンド置換のときに
 153 .I stderr
 154 が
 155 .I /dev/null
 156 にリダイレクトされる。
 157 このフラグは
 158 .I stderr
 159 をリダイレクトしないように指定する。
 160 .TP
 161 .B WRDE_UNDEF
 162 未定義のシェル変数を展開しようとした場合に、エラーとして扱う。
 163 .SH 返り値
 164 成功した場合は 0 が返される。
 165 エラーの場合は以下の 5 つの値のうちの 1 つが返される。
 166 .TP
 167 .B WRDE_BADCHAR
 168 改行または |, &, ;, <, >, (, ), {, } のうちの 1 つが不正に出現した。
 169 .TP
 170 .B WRDE_BADVAL
 171 未定義のシェル変数が参照され、かつ
 172 .B WRDE_UNDEF
 173 フラグでこれをエラーとして扱うように指示されている。
 174 .TP
 175 .B WRDE_CMDSUB
 176 コマンド置換が起こり、かつ
 177 .B WRDE_NOCMD
 178 フラグでこれをエラーとして扱うように指示されている。
 179 .TP
 180 .B WRDE_NOSPACE
 181 メモリが足りない。
 182 .TP
 183 .B WRDE_SYNTAX
 184 対応する括弧がない、クォートが合致しないといった、
 185 シェルの書式エラー。
 186 .SH バージョン
 187 .BR wordexp ()
 188 と
 189 .BR wordfree ()
 190 は、バージョン 2.1 以降の glibc で提供されている。
 191 .SH 準拠
 192 POSIX.1-2001.
 193 .SH 例
 194 以下のサンプルプログラムの出力はだいたい "ls [a-c]*.c" と同じになる。
 195 .LP
 196 .nf
 197 #include <stdio.h>
 198 #include <stdlib.h>
 199 #include <wordexp.h>
 200
 201 int
 202 main(int argc, char **argv)
 203 {
 204     wordexp_t p;
 205     char **w;
 206     int i;
 207
 208     wordexp("[a-c]*.c", &p, 0);
 209     w = p.we_wordv;
 210     for (i = 0; i < p.we_wordc; i++)
 211         printf("%s\en", w[i]);
 212     wordfree(&p);
 213     exit(EXIT_SUCCESS);
 214 }
 215 .fi
 216 .SH 関連項目
 217 .BR fnmatch (3),
 218 .BR glob (3)