wordexp
Section: C Library Functions (3)
Updated: 2026-02-08
Index
JM Home Page
roff page
名前
wordexp, wordfree - posix シェルのように単語の展開を行う
ライブラリ
標準 C ライブラリ (libc,~-lc)
書式
#include <wordexp.h>
int wordexp(const char *restrict s, wordexp_t *restrict 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_wordc は size_t であり、 s を展開した結果に単語がいくつあるかを表す。 フィールド
we_wordv は char ** であり、見つかった単語の配列を指し示す。 size_t 型のフィールド we_offs
は、 we_wordv 配列にある初期要素のうちいくつが NULL で埋められるべきかを表すのに使われたりする (flags
により決定される。下記を参照。)。
関数 wordfree() は割り当てたメモリーを再度解放する。 より正確にいうと、この関数はその引数を解放するのではなく、 配列
we_wordv とそれが指し示す文字列を解放する。
文字列引数
この展開はシェルによるコマンドのパラメーターの展開 (sh(1) を参照) と同じであるので、文字列 s
はシェルコマンドパラメーターで不正とされる文字を含んではならない。 特にエスケープされていない改行、|, &, ;, <, >, (,
), {, } 文字を コマンド置換やパラメーター置換の場面以外に含めてはならない。
引数 s にクォートしていないコメント文字 # で始まる単語が含まれている場合には、 その単語とそれ以降の単語が無視されるか、 それとも #
がコメント文字として扱わないかは、規定されていない。
展開
The expansion done consists of the following stages: tilde expansion
(replacing ~user by user's home directory), variable substitution
(replacing $FOO by the value of the environment variable FOO), command
substitution (replacing $(command) or `command` by the output of command),
arithmetic expansion, field splitting, wildcard expansion, quote removal.
特殊なパラメーター ($@, $*, $#, $?, $-, $$, $!, $0) の 展開結果は規定されていない。
Field splitting is done using the environment variable $IFS. If it is not
set, the field separators are space, tab, and newline.
出力される配列
配列 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
-
未定義のシェル変数を展開しようとした場合に、エラーとして扱う。
返り値
On success, wordexp() returns 0. On failure, wordexp() returns one
of the following nonzero values:
- WRDE_BADCHAR
-
改行または |, &, ;, <, >, (, ), {, } のうちの 1 つが不正に出現した。
- WRDE_BADVAL
-
未定義のシェル変数が参照され、かつ WRDE_UNDEF フラグでこれをエラーとして扱うように指示されている。
- WRDE_CMDSUB
-
コマンド置換が要求されたが、 WRDE_NOCMD フラグでこれをエラーとして扱うように指示されていた。
- WRDE_NOSPACE
-
メモリーが足りない。
- WRDE_SYNTAX
-
対応する括弧がない、クォートが合致しないといった、 シェルの書式エラー。
属性
この節で使用されている用語の説明については、 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-2008.
歴史
POSIX.1-2001. glibc 2.1.
例
以下のサンプルプログラムの出力はだいたい "ls [a-c]*.c" と同じになる。
#include <stdio.h>
#include <stdlib.h>
#include <wordexp.h>
int
main(void)
{
wordexp_t p;
char **w;
wordexp("[a-c]*.c", &p, 0);
w = p.we_wordv;
for (size_t i = 0; i < p.we_wordc; i++)
printf("%s\n", w[i]);
wordfree(&p);
exit(EXIT_SUCCESS);
}
関連項目
fnmatch(3), glob(3)
Index
- 名前
-
- ライブラリ
-
- 書式
-
- 説明
-
- 文字列引数
-
- 展開
-
- 出力される配列
-
- flags 引数
-
- 返り値
-
- 属性
-
- 標準規格
-
- 歴史
-
- 例
-
- 関連項目
-
This document was created by
man2html,
using the manual pages.