wordexpのヘルプ・マニュアル
日本語 英語
wordexp --help
man wordexp
WORDEXP(3) Linux Programmer’s Manual WORDEXP(3)
名前
wordexp, wordfree - posix シェルのように単語の展開を行う
書式
#include
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_wordc は size_t で
あり、 s を展開した結果に単語がいくつあるかを表す。フィールド we_wordv
は char ** であり、見つかった単語の配列を指し示す。 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 で提供されてい
る。
準拠
POSIX.1-2001.
例
以下のサンプルプログラムの出力はだいたい "ls [a-c]*.c" と同じになる。
#include
#include
#include
int
main(int argc, char **argv)
{
wordexp_t p;
char **w;
int i;
wordexp("[a-c]*.c", &p, 0);
w = p.we_wordv;
for (i = 0; i < p.we_wordc; i++)
printf("%s\n", w[i]);
wordfree(&p);
exit(EXIT_SUCCESS);
}
関連項目
fnmatch(3), glob(3)
2008-07-14 WORDEXP(3)
WORDEXP(3) Linux Programmer’s Manual WORDEXP(3)
NAME
wordexp, wordfree - perform word expansion like a posix-shell
SYNOPSIS
#include
int wordexp(const char *s, wordexp_t *p, int flags);
void wordfree(wordexp_t *p);
Feature Test Macro Requirements for glibc (see feature_test_macros(7)):
wordexp(), wordfree(): _XOPEN_SOURCE
DESCRIPTION
The function wordexp() performs a shell-like expansion of the string s
and returns the result in the structure pointed to by p. The data type
wordexp_t is a structure that at least has the fields we_wordc,
we_wordv, and we_offs. The field we_wordc is a size_t that gives the
number of words in the expansion of s. The field we_wordv is a char **
that points to the array of words found. The field we_offs of type
size_t is sometimes (depending on flags, see below) used to indicate
the number of initial elements in the we_wordv array that should be
filled with NULLs.
The function wordfree() frees the allocated memory again. More pre-
cisely, it does not free its argument, but it frees the array we_wordv
and the strings that points to.
The string argument
Since the expansion is the same as the expansion by the shell (see
sh(1)) of the parameters to a command, the string s must not contain
characters that would be illegal in shell command parameters. In par-
ticular, there must not be any non-escaped newline or |, &, ;, <, >, (,
), {, } characters outside a command substitution or parameter substi-
tution context.
If the argument s contains a word that starts with an unquoted comment
character #, then it is unspecified whether that word and all following
words are ignored, or the # is treated as a non-comment character.
The expansion
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 com-
mand), arithmetic expansion, field splitting, wildcard expansion, quote
removal.
The result of expansion of special parameters ($@, $*, $#, $?, $-, $$,
$!, $0) is unspecified.
Field splitting is done using the environment variable $IFS. If it is
not set, the field separators are space, tab and newline.
The output array
The array we_wordv contains the words found, followed by a NULL.
The flags argument
The flag argument is a bitwise inclusive OR of the following values:
WRDE_APPEND
Append the words found to the array resulting from a previous
call.
WRDE_DOOFFS
Insert we_offs initial NULLs in the array we_wordv. (These are
not counted in the returned we_wordc.)
WRDE_NOCMD
Don’t do command substitution.
WRDE_REUSE
The argument p resulted from a previous call to wordexp(), and
wordfree() was not called. Reuse the allocated storage.
WRDE_SHOWERR
Normally during command substitution stderr is redirected to
/dev/null. This flag specifies that stderr is not to be redi-
rected.
WRDE_UNDEF
Consider it an error if an undefined shell variable is expanded.
RETURN VALUE
In case of success 0 is returned. In case of error one of the follow-
ing five values is returned.
WRDE_BADCHAR
Illegal occurrence of newline or one of |, &, ;, <, >, (, ), {,
}.
WRDE_BADVAL
An undefined shell variable was referenced, and the WRDE_UNDEF
flag told us to consider this an error.
WRDE_CMDSUB
Command substitution occurred, and the WRDE_NOCMD flag told us
to consider this an error.
WRDE_NOSPACE
Out of memory.
WRDE_SYNTAX
Shell syntax error, such as unbalanced parentheses or unmatched
quotes.
VERSIONS
wordexp() and wordfree() are provided in glibc since version 2.1.
CONFORMING TO
POSIX.1-2001.
EXAMPLE
The output of the following example program is approximately that of
"ls [a-c]*.c".
#include
#include
#include
int
main(int argc, char **argv)
{
wordexp_t p;
char **w;
int i;
wordexp("[a-c]*.c", &p, 0);
w = p.we_wordv;
for (i = 0; i < p.we_wordc; i++)
printf("%s\n", w[i]);
wordfree(&p);
exit(EXIT_SUCCESS);
}
SEE ALSO
fnmatch(3), glob(3)
COLOPHON
This page is part of release 3.22 of the Linux man-pages project. A
description of the project, and information about reporting bugs, can
be found at http://www.kernel.org/doc/man-pages/.
2008-07-14 WORDEXP(3)