strerror

STRERROR(3)                 Linux Programmer's Manual                STRERROR(3)



名前
       strerror, strerror_r, strerror_l - エラー番号を説明する文字列を返す。

書式
       #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 */

       char *strerror_l(int errnum, locale_t locale);

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

       strerror_r():
           次の場合には XSI 準拠のバージョンが提供される:
           (_POSIX_C_SOURCE >= 200112L || _XOPEN_SOURCE >= 600) && ! _GNU_SOURCE
           それ以外の場合、GNU バージョンが提供される。

説明
       strerror() 関数は、引き数 errnum で渡されたエラーコードについての説明が入った文字列へのポインターを返す。
       可能であるならば、適切な言語を選択するために、 現在のロケールの LC_MESSAGES を使う。(例えば、 errnum EINVAL
       の場合、説明として "Invalid argument" が返される。) この文字列は、アプリケーションで変更してはならないが、
       これ以降に行われる strerror() や strerror_l() の呼び出しで変更されても構わない。 perror(3)
       などの、これ以外のライブラリ関数ではこの文字列は変更されない。

   strerror_r()
       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 は不定である)。 文字列には必ず終端ヌル文字 ('\0') が含まれる。

   strerror_l()
       strerror_l() は strerror() と同様だが、 errnum locale
       で指定されたロケールのロケール依存のエラーメッセージにマッピングする。 locale が特別なロケールオブジェクト
       LC_GLOBAL_LOCALE の場合、もしくは locale が有効なロケールオブジェクトハンドルでない場合は、 strerror_l()
       の動作は未定義である。

返り値
       関数 strerror(), strerror_l() と GNU 固有の関数 strerror_r() はエラー内容を説明する文字列を返す。
       エラー番号が未知の場合は "Unknown error nnn" という メッセージを返す。

       XSI 準拠の strerror_r() 関数は成功すると 0 を返す。エラーの場合には、 (glibc 2.13 以降では) (正の)
       エラー番号が返され、(バージョン 2.13 より前 の glibc では) -1 が返され、 errno にエラーを示す値がセットされる。

       POSIX.1-2001 と POSIX.1-2008 では、 strerror() や strerror_l() が成功した場合は errno
       を変更せずに元のままにしなければならないとされている。関数のどの返り値もエラーを示すために予約されていないので、エラーをチェックしたいアプリケーションは呼び出しを行う前に
       errno を 0 に初期化し、呼び出しの後で errno をチェックすべき点に注意すること。

エラー
       EINVAL errnum の値が有効なエラー番号ではない。

       ERANGE エラーコードを説明する文字列のために、充分な領域が確保できなかった。

属性
   マルチスレッディング (pthreads(7) 参照)
       strerror() 関数はスレッドセーフではない。

       strerror_r() 関数はスレッドセーフである。

バージョン
       strerror_l() 関数は glibc 2.6 で初めて登場した。

準拠
       strerror()  は POSIX.1-2001, POSIX.1-2008, C89, C99 で規定されている。 strerror_r()
       は POSIX.1-2001 と POSIX.1-2008 で規定されている。

       strerror_l() は POSIX.1-2008 で規定されている。

       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), locale(7)

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



                                   2014-03-18                        STRERROR(3)