STRERROR - Linux手册页

时间:2019-08-20 18:01:24  来源:igfitidea点击:

Linux程序员手册 第3部分
更新日期: 2019-03-06

名称

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)&&! _GNU_SOURCE 否则,将提供特定于GNU的版本。

说明

strerror()函数返回一个指针,该指针指向描述在参数errnum中传递的错误代码的字符串,可能使用当前语言环境的LC_MESSAGES部分来选择适当的语言。 (例如,如果errnum为EINVAL,则返回的描述将为"无效参数"。)此字符串不得由应用程序修改,但可以通过后续对strerror()或strerror_l()的调用进行修改。包括perror(3)在内的任何其他库函数都不会修改此字符串。

strerror_r()

strerror_r()函数类似于strerror(),但是是线程安全的。此功能有两个版本:POSIX.1-2001中指定的XSI兼容版本(自glibc 2.3.4起可用,但不兼容POSIX,直到glibc 2.13为止)和GNU特定版本(自glibc 2.0起可用)。 。符合XSI的版本提供了功能概述中的功能摘要,该摘要在SYNOPSIS中显示。否则,将提供特定于GNU的版本。如果未明确定义任何功能测试宏,则(自glibc 2.4起)默认情况下将_POSIX_C_SOURCE定义为值200112L,以便默认提供与XSI兼容的strerror_r()版本。

与XSI兼容的strerror_r()是便携式应用程序的首选。它在用户提供的长度为buflen的缓冲区buf中返回错误字符串。

特定于GNU的strerror_r()返回一个指向包含错误消息的字符串的指针。这可以是指向函数存储在buf中的字符串的指针,也可以是指向某些(不可变的)静态字符串的指针(在这种情况下,buf未使用)。如果函数将字符串存储在buf中,则最多将存储buflen字节(如果buflen太小且errnum未知,则字符串可能会被截断)。该字符串始终包含一个终止的空字节(aq \ 0aq)。

strerror_l()

strerror_l()类似于strerror(),但是将errnum映射到语言环境指定的语言环境中与语言环境相关的错误消息。如果locale是特殊的语言环境对象LC_GLOBAL_LOCALE或不是有效的语言环境对象句柄,则strerror_l()的行为是不确定的。

返回值

strerror(),strerror_l()和特定于GNU的strerror_r()函数返回适当的错误描述字符串,如果错误号未知,则返回" Unknown error nnn"消息。

符合XSI的strerror_r()函数成功返回0。发生错误时,将返回(正)错误号(自glibc 2.13起),或者返回-1并将errno设置为指示错误(2.13之前的glibc版本)。

POSIX.1-2001和POSIX.1-2008要求成功调用strerror()或strerror_l()时应使errno保持不变,并请注意,由于没有保留任何函数返回值来指示错误,因此希望使用检查错误应在调用之前将errno初始化为零,然后在调用之后检查errno。

错误说明

EINVAL
errnum的值不是有效的错误号。
ERANGE
提供的存储空间不足,无法包含错误描述字符串。

版本

strerror_l()函数首先出现在glibc 2.6中。

属性

有关本节中使用的术语的说明,请参见attribute(7)。

InterfaceAttributeValue
strerror()Thread safetyMT-Unsafe race:strerror
strerror_r(),
strerror_l()
Thread safetyMT-Safe

遵循规范

strerror()由POSIX.1-2001,POSIX.1-2008,C89和C99指定。 strerror_r()由POSIX.1-2001和POSIX.1-2008指定。

在POSIX.1-2008中指定了strerror_l()。

GNU特定的strerror_r()函数是非标准扩展。

如果调用遇到错误,POSIX.1-2001允许strerror()设置errno,但未指定发生错误时作为函数结果应返回的值。在某些系统上,如果错误号未知,则strerror()返回NULL。在其他系统上,strerror()返回类似"发生错误nnn"的字符串,如果错误号未知,则将errno设置为EINVAL。 C99和POSIX.1-2008要求返回值不能为NULL。

备注

GNU C库对strerror()使用1024个字符的缓冲区。因此,此缓冲区大小应足以避免在调用strerror_r()时发生ERANGE错误。

另外参见

err(3),errno(3),error(3),perror(3),strsignal(3),locale(7)

出版信息

这个页面是Linux手册页项目5.08版的一部分。有关项目的说明、有关报告错误的信息以及此页面的最新版本,请访问https://www.kernel.org/doc/man-pages/