STRERROR(3) |
Linux Programmer's Manual |
STRERROR(3) |
名前
strerror, strerror_r -エラー番号を説明する文字列を返す。
書式
#include <string.h>
char *strerror(int
errnum
);
int strerror_r(int
errnum
, char *
buf
, size_t
buflen
);
/* XSI-compliant */
char *strerror_r(int
errnum
, char *
buf
, size_t
buflen
);
/* GNU-specific */
glibc 向けの機能検査マクロの要件 (
feature_test_macros(7) 参照):
次の場合には XSI 準拠のバージョンの
strerror_r() が提供される:
(_POSIX_C_SOURCE >= 200112L || _XOPEN_SOURCE >= 600) && ! _GNU_SOURCE
それ以外の場合、GNU バージョンが提供される。
説明
strerror() 関数は、引き数
errnum で渡されたエラーコードについての説明が入った文字列へのポインタを返す。可能であるならば、適切な言語を選択するために、現在のロケールの
LC_MESSAGES を使う。(例えば、
errnum が
EINVAL の場合、説明として"Invalid argument"が返される。) この文字列は、アプリケーションで変更してはならないが、これ以降に行われる
strerror() の呼び出しで変更されても構わない。この文字列を変更するライブラリ関数はない (
perror(3) も含まれる)。
strerror_r() 関数は
strerror() と似ているが、スレッドセーフである。この関数には二種類のバージョンが存在し、 POSIX.1-2001 で規定された XSI 準拠のバージョン (glibc 2.3.4 以降で利用可能だが、glibc 2.13 までは POSIX 準拠ではない) と、 GNU 仕様のバージョン (glibc 2.0 以降で利用可能) である。「書式」の節に記載された機能検査マクロの場合には、 XSI 準拠のバージョンが提供される。それ以外の場合には GNU 仕様のバージョンが提供される。機能検査マクロが一つも明示的に定義されない場合、 (glibc 2.4 以降では) デフォルトで
_POSIX_SOURCE は値 200112l で定義され、その結果 XSI 準拠のバージョンの
strerror_r() がデフォルトで提供される。
移植性が必要なアプリケーションでは、 XSI 準拠の
strerror_r() を使う方がよい。この関数は、ユーザーから提供される長さ
buflen のバッファ
buf にエラー文字列を返す。
GNU 仕様の
strerror_r() は、エラーメッセージを格納した文字列へのポインタを返す。返り値は、この関数が
buf に格納した文字列へのポインタか、何らかの (不変な) 静的な文字列へのポインタ、のいずれかとなる (後者の場合は
buf は使用されない)。
buf に文字列が格納される場合は、最大で
buflen バイトが格納される (
buflen が小さ過ぎたときには文字列は切り詰められ、
errnum は不定である)。文字列には必ず終端ヌル文字が含まれる。
返り値
strerror() と
strerror_r() はエラー内容を説明する文字列を返す。エラー番号が未知の場合は "Unknown error nnn"というメッセージを返す。
POSIX.1-2001 と POSIX.1-2008 では、
strerror() が成功した場合は
errno を変更せずに元のままにしなければならないとされている。関数のどの返り値もエラーを示すために予約されていないので、エラーをチェックしたいアプリケーションは呼び出しを行う前に
errno を 0 に初期化し、呼び出しの後で
errno をチェックすべき点に注意すること。
XSI 準拠の
strerror_r() 関数は成功すると 0 を返す。エラーの場合には、 (glibc 2.13 以降では) (正の) エラー番号が返され、(バージョン 2.13 より前の glibc では) -1 が返され、
errno にエラーを示す値がセットされる。
エラー
-
EINVAL
-
errnum の値が有効なエラー番号ではない。
-
ERANGE
-
エラーコードを説明する文字列のために、充分な領域が確保できなかった。
準拠
strerror() は POSIX.1-2001, C89, C99 で規定されている。
strerror_r() は POSIX.1-2001 で規定されている。
GNU 仕様の
strerror_r() 関数は非標準の拡張である。
POSIX.1-2001 は、
strerror() がエラーに遭遇した場合に
errno をセットすることを認めているが、エラー発生時に関数の結果としてどんな値を返すべきかを規定してない。あるシステムでは、エラー番号が未知の場合、
strerror() は NULL を返す。他のシステムでは、エラー番号が未知の場合、
strerror() は "Error nnn occurred"といった文字列を返し、
errno に
EINVAL をセットする。 C99 と POSIX.1-2008 では、返り値が NULL 以外になることが求められている。
関連項目
err(3),
errno(3),
error(3),
perror(3),
strsignal(3)
この文書について
この man ページは Linux
man-pages プロジェクトのリリース 3.51 の一部である。プロジェクトの説明とバグ報告に関する情報は http://www.kernel.org/doc/man-pages/ に書かれている。