man strerror strerror_r strerror_l

名称

        strerror, strerror_r, strerror_l - 返回描述错误值的字符串

概要

        #include <string.h>

        char *strerror(int errnum);

        int strerror_r(int errnum, char *buf, size_t buflen);

                /* 兼容XSI */

        char *strerror_r(int errnum, char *buf, size_t buflen);

                /* GNU版本 */

        char *strerror_l(int errnum, locale_t locale);

    对于glibc来说要有功能测试宏才能使用（参考feature_test_macros）：

        strerror_r():

            如果下面的条件成立则使用兼容XSI的版本:

            (_POSIX_C_SOURCE >= 200112L || _XOPEN_SOURCE >= 600) && ! _GNU_SOURCE

            否则，使用GNU版本。

说明

        strerror返回一个指向字符串的指针，该字符串描述了由参数errnum表示的错误代

        码，可能使用当前语言环境的LC_MESSAGES部分来选择适当的语言。（例如，如

        果errnum为 EINVAL，则返回的描述将为“无效参数”。）该字符串不应由应用程

        序修改，但可能会被后续的strerror或strerror_l调用修改。除此之外，没有其他的

        库函数修改该字符串，包括perror。

    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兼容的版本。

        XSI兼容的版本是可移植应用程序的首选，它把错误描述串存放到用户指定的缓冲

        区参数buf中，缓冲区的长度为buflen。

        GNU版本的strerror_r返回一个指向字符串的指针，该字符串的内容包含了错误消

        息，指针要么指向函数内部定义的参数buf，要么指向某个（不可变的）静态字符

        串（在这种情况下参数buf未被使用）。如果字符串存储在参数buf，那么最多存

        放buflen个字节（如果buflen太小且errnum未知，则字符串可能会被截断）。字

        符串总是包含一个结束符（‘\0’）。

    strerror_l()

        strerror_l跟strerror类似，但将errnum映射到locale指定的语言环境中与语言环

        境相关的错误消息。如果locale是特殊语言环境对象LC_GLOBAL_LOCALE或不是有

        效的语言环境对象句柄，则strerror_l的行为未定义。

返回值

        strerror，strerror_l和strerror_r返回适当的错误描述串，或者当errnum未知时返

        回"未知的错误nnn"。

        strerror_r成功时返回0。出错时返回一个（正数）错误码（自glibc 2.13起），或

        者返回-1并设置errno为对应的错误码（glibc 2.13之前的版本）。

        POSIX.1-2001和POSIX.1-2008要求成功调用strerror或strerror_l时应保持errno不

        变，并注意，由于没有保留函数的返回值来指示错误，如果应用程序希望检查错误，

        那么应该在调用相关函数之前将errno初始化为零，在调用函数之后检查errno。

错误码

        EINVAL  errnum不是一个合法的错误码。

        ERANGE 提供的存储空间不足，无法存放错误描述串。

线程安全特征

接口	特征	值
strerror()	线程安全	多线程不安全 竞争：strerror
strerror_r(), strerror_l()	线程安全	多线程安全

版本

        strerror_l在glibc 2.6中首次出现。

标准

        strerror遵循POSIX.1-2001, POSIX.1-2008, C89和C99。strerror_r遵循POSIX.1-2001

        and POSIX.1-2008。

        strerror_l遵循POSIX.1-2008。

        GNU版本的strerror_r是一个是非标准的扩展。

        POSIX.1-2001允许在调用strerror遇到错误时设置errno，但没有指定在发生错误时

        应该返回什么值作为函数结果。在某些系统上，如果错误码未知，则strerror返回

        NULL，而在其他系统上，strerror返回类似于“发生错误nnn”的字符串并将errno

        设置为EINVAL。C99和POSIX.1-2008要求返回值为非NULL。

推荐阅读

        err，errno，error，perror，strsignal，locale

版本记录

        这个页面是Linux man-pages项目4.04版本的一部分。关于该项目的信息和bug报

        道可以在该网站找到：http://www.kernel.org/doc/man-pages/。

                                2015-08-08