wordexp(3C)

構文

#include <wordexp.h>

int wordexp(const char *words, wordexp_t *pwordexp, int flags);

void wordfree(wordexp_t *pwordexp);

説明

wordexp() は、単語を展開し、展開した単語のリストを pwordexp が指す構造体に格納します。

引き数 words は、展開する １ つまたは複数の単語の入った文字列へのポインターです。 展開結果は、シェル sh-posix(1) を参照) のコマンドラインに、何かのユーティリティへの引き数としてこの文字列を与えた場合と同じです。 よって、 words は、引用符で囲わない限り、ニューライン文字やシェルの特殊文字 |, &, ;, < または > を含んでいてはいけません。 ただし、シェルコマンド置換の場合は例外です。 words が、引用符に囲われていないコメント文字 # を含んでいる場合、 wordexp() はこれをコメントを表すトークンの開始文字として扱い、この文字以降を無視します。

構造体型 wordexp_t は、ヘッダーファイル <wordexp.h> で定義してあり、以下の要素を持ちます。

wordexp() は、展開した単語の数を pwordexp->we_wordc に格納します。 フィールド分離やパス名展開で分けられた各々のフィールドが、それぞれ pwordexp->we_wordv リストの １ 単語となります。 単語の順序は、シェルの単語展開の項で説明されているとおりです。 最後の単語を指すポインターの次のポインターは null ポインターです。 パラメータ (たとえば $$ や $* など) の展開については特に指定はありません。

pwordexp が指す記憶領域は、関数を呼び出す側で割り当ててください。 それ以外については、 pwordexp->we_wordv が指すメモリーも含め、 wordexp() が必要に応じて割り当てます。

wordfree() は、直前の wordexp() で割り当てた pwordexp に対応するメモリーをすべて解放します。

引き数 flags は wordexp() の動作を制御します。 flags の値は、以下の定数を ０ 個またはそれ以上、ビット毎の 論理的 OR をとったものです。 これらの定数は、 <wordexp.h> に定義してあります。

WRDE_APPEND フラグを使って、以前に wordexp() で展開した単語の後ろに新しい単語の組を追加することができます。 同じ pwordexp を使って、 wordexp() を ２ 回またはそれ以上続けて呼び出し、間に wordfree() を呼び出さなかった場合の規則は次のとおりです。

words 中に、ニューライン, |, &, ;, <, >, 小かっこ、 中かっこの各文字が、引用符に囲われない不適切な構文で現れた場合、 wordexp() は失敗し、展開した単語数は ０ となります。

WRDE_SHOWERR flags を立てない場合、 wordexp() は、 words の展開でコマンド置換を行う場合に起動するユーティリティの stderr を /dev/null にリダイレクトします。 立てた場合は、 words の展開作業中に構文エラーを見つけると stderr メッセージを出力します。

WRDE_DOOFFS を立てる場合、同じ wordexp を使って呼び出す wordexp() と wordfree() について、 pwordexp->we_offs を常に同じ値にします。

戻り値

展開が正常に終了した場合 wordexp() は、０ を戻り値とします。それ以外の場合は <wordexp.h> で定義してある ０ 以外の値でエラーを表します。

戻り値がエラー WRDE_NOSPACE の場合、 wordexp() は、 pwordexp->we_wordc および pwordexp->we_wordv を、正常に展開した単語について設定します。 それ以外のエラーの場合は、何も変更しません。

著者

wordexp() および wordfree() は、OSF と HP で開発されました。

参照

sh-posix(1), fnmatch(3C), glob(3C), regexp(5), thread_safety(5)

標準準拠

wordexp(): XPG4, POSIX.2

wordfree(): XPG4, POSIX.2