WORDEXP

Section: Linux Programmer's Manual (3)
Updated: 2020-11-01
Index JM Home Page
 

名前

wordexp, wordfree - posix シェルのように単語の展開を行う  

書式

#include <wordexp.h>

int wordexp(const char *s, wordexp_t *p, int flags);

void wordfree(wordexp_t *p);

glibc 向けの機能検査マクロの要件 (feature_test_macros(7) 参照):

wordexp(), wordfree(): _XOPEN_SOURCE  

説明

関数 wordexp() はシェルのように文字列 s を展開し、 p で指し示す構造体に結果を返す。 データ型 wordexp_t は少なくともフィールド we_wordc, we_wordv, we_offs を持つ構造体である。 フィールド we_wordcsize_t であり、 s を展開した結果に単語がいくつあるかを表す。 フィールド we_wordvchar ** であり、見つかった単語の配列を指し示す。 size_t 型のフィールド we_offs は、 we_wordv 配列にある初期要素のうちいくつが NULL で埋められるべきかを表すのに使われたりする (flags により決定される。下記を参照。)。

関数 wordfree() は割り当てたメモリーを再度解放する。 より正確にいうと、この関数はその引数を解放するのではなく、 配列 we_wordv とそれが指し示す文字列を解放する。  

文字列引数

この展開はシェルによるコマンドのパラメーターの展開 (sh(1) を参照) と同じであるので、文字列 s はシェルコマンドパラメーターで不正とされる文字を含んではならない。 特にエスケープされていない改行、|, &, ;, <, >, (, ), {, } 文字を コマンド置換やパラメーター置換の場面以外に含めてはならない。

引数 s にクォートしていないコメント文字 # で始まる単語が含まれている場合には、 その単語とそれ以降の単語が無視されるか、 それとも # がコメント文字として扱わないかは、規定されていない。  

展開

実行される展開は、以下の段階で構成される: チルダ展開 (~user を user のホームディレクトリに置き換える)、 変数展開 ($FOO を環境変数 FOO の値に置き換える)、 コマンド展開 ($(command) または `command` を command の出力で置き換える)、 算術展開、フィールド分割、ワイルドカード展開、クォートの除去。

特殊なパラメーター ($@, $*, $#, $?, $-, $$, $!, $0) の 展開結果は規定されていない。

フィールド分割は環境変数 $IFS を用いて行われる。 この環境変数が設定されていない場合、 フィールド区切り文字はスペース・タブ・改行である。  

出力される配列

配列 we_wordv は見つかった単語をを含み、最後に NULL が続く。  

flags 引数

flags 引数は以下の値のビット包含的 OR である:
WRDE_APPEND
見つかった単語を前回の呼び出し結果の配列に追加する。
WRDE_DOOFFS
初期状態である we_offs 個の NULL を配列 we_wordv に挿入する (これらは返される we_wordc にはカウントされない)。
WRDE_NOCMD
コマンド置換を行わない。
WRDE_REUSE
引数 p は前回の wordexp() の呼び出し結果であり、 wordfree() が (まだ) 呼び出されない。 割り当てられた領域を再利用する。
WRDE_SHOWERR
通常はコマンド置換のときに stderr/dev/null にリダイレクトされる。 このフラグは stderr をリダイレクトしないように指定する。
WRDE_UNDEF
未定義のシェル変数を展開しようとした場合に、エラーとして扱う。
 

返り値

成功した場合は 0 が返される。 エラーの場合は以下の 5 つの値のうちの 1 つが返される。
WRDE_BADCHAR
改行または |, &, ;, <, >, (, ), {, } のうちの 1 つが不正に出現した。
WRDE_BADVAL
未定義のシェル変数が参照され、かつ WRDE_UNDEF フラグでこれをエラーとして扱うように指示されている。
WRDE_CMDSUB
コマンド置換が要求されたが、 WRDE_NOCMD フラグでこれをエラーとして扱うように指示されていた。
WRDE_NOSPACE
メモリーが足りない。
WRDE_SYNTAX
対応する括弧がない、クォートが合致しないといった、 シェルの書式エラー。
 

バージョン

wordexp() と wordfree() は、バージョン 2.1 以降の glibc で提供されている。  

属性

この節で使用されている用語の説明については、 attributes(7) を参照。
インターフェース 属性
wordexp() Thread safety MT-Unsafe race:utent const:env
env sig:ALRM timer locale
wordfree() Thread safety MT-Safe

In the above table, utent in race:utent signifies that if any of the functions setutent(3), getutent(3), or endutent(3) are used in parallel in different threads of a program, then data races could occur. wordexp() calls those functions, so we use race:utent to remind users.  

準拠

POSIX.1-2001, POSIX.1-2008.  

以下のサンプルプログラムの出力はだいたい "ls [a-c]*.c" と同じになる。

#include <stdio.h> #include <stdlib.h> #include <wordexp.h>

int main(int argc, char **argv) {
    wordexp_t p;
    char **w;


    wordexp("[a-c]*.c", &p, 0);
    w = p.we_wordv;
    for (int i = 0; i < p.we_wordc; i++)
        printf("%s\n", w[i]);
    wordfree(&p);
    exit(EXIT_SUCCESS); }  

関連項目

fnmatch(3), glob(3)  

この文書について

この man ページは Linux man-pages プロジェクトのリリース 5.10 の一部である。プロジェクトの説明とバグ報告に関する情報は https://www.kernel.org/doc/man-pages/ に書かれている。

関連キーワード

wordexp, we, 展開, WRDE, 配列, 単語, wordfree, wordv, フィールド, WORDEXP

Linux マニュアル 一覧

[man1] [man2] [man3] [man4] [man5] [man6] [man7] [man8]
[a] [b] [c] [d] [e] [f] [g] [h] [i] [j] [k] [l] [m] [n] [o] [p] [q] [r] [s] [t] [u] [v] [w] [x] [y] [z]

 

Index

名前
書式
説明
文字列引数
展開
出力される配列
flags 引数
返り値
バージョン
属性
準拠
関連項目
この文書について

This document was created by man2html, using the manual pages.
Time: 12:08:43 GMT, June 11, 2022