strerror, strerror_s, strerrorlen_s

C 参考手册

位置：首页 > C 参考手册 >字符串库 >空终止字节字符串 > strerror, strerror_s, strerrorlen_s

定义于头文件 `<string.h>`
char* strerror( int errnum );	(1)
errno_t strerror_s( char *buf, rsize_t bufsz, errno_t errnum );	(2)	(C11 起)
size_t strerrorlen_s( errno_t errnum );	(3)	(C11 起)

1) 返回指向系统错误码 errnum 的文本表示的指针，它等同于 perror() 会打印的描述。

errnum 通常获得自 errno 对象，不过函数接受任何 int 类型值。字符串的内容是本地环境限定的。

程序必须不修改返回的字符串，但对 strerror 函数的后继调用可能重写该字符串。不要求 strerror 为线程安全。实现可以返回指向静态只读字符串字面量的不同指针，或反复返回指向静态缓冲区的同一指针， strerror 放置字符串于该缓冲区中。

2) 同 (1) ，除了将消息复制到用户提供的存储 buf 中。不写入多于 bufsz-1 个字符，缓冲区始终为空终止的。若消息必须被截断，且 bufsz 大于 3 ，则只写入 bufsz-4 个字符，并在空终止符前前附字符 "..." 。另外，在运行时检测下列错误，并调用当前安装的制约处理函数：

buf 为空指针
bufsz 为零或大于 RSIZE_MAX

若到 buf 的写入出现在数组末尾后则行为未定义，这在 buf 所指向的缓冲区大小写小于错误消息的字符数，且小于 bufsz 时发生。

3) 计算若以 errnum 调用则 strerror_s 本会写入的，本地环境限定错误消息的不截断长度。长度不包含空终止符。

同所有边界检查函数， strerror_s, strerrorlen_s 仅若实现定义了 __STDC_LIB_EXT1__ ，且用户在包含 string.h 前定义 __STDC_WANT_LIB_EXT1__ 为整数常量 1 才保证可用。

参数

errnum	-	指代错误码的整数值
buf	-	指向用户提供的缓冲区的指针
bufsz	-	用户提供的缓冲区的大小

返回值

1) 指向对应 errno 错误码 errnum 的空终止字节串的指针。

2) 若整个消息完整存储于 buf 则为零，否则为非零。

3) strerror_s 会返回的消息长度（不包含空终止符）

注意

POSIX 允许对 strerror 的后继调用非法化先前调用所返回的指针值。它亦指定控制这些消息的 LC_MESSAGES 本地环境平面。

strerror_s 是仅有的允许截断的带边界检查函数，因为提供尽可能多的关于失败的信息被视为更加令人满意。 POSIX 亦为类似目的定义 strerror_r 。

示例

运行此代码

#define __STDC_WANT_LIB_EXT1__ 1
#include <stdio.h>
#include <errno.h>
#include <string.h>
#include <locale.h>
 
int main(void)
{
    FILE *fp = fopen(tmpnam((char[L_tmpnam]){0}), "r");
    if(fp==NULL) {
        printf("File opening error: %s\n", strerror(errno));
        setlocale(LC_MESSAGES, "de_DE.utf8");
        printf("Now in German: %s\n", strerror(errno));
#ifdef __STDC_LIB_EXT1__
        setlocale(LC_ALL, "zh_CN.utf8"); // printf 需要多字节输出的 CTYPE
        size_t errmsglen = strerrorlen_s(errno) + 1;
        char errmsg[errmsglen]; 
        strerror_s(errmsg, errmsglen, errno);
        printf("Now in Chinese: %s\n", errmsg);
#endif
    }
}

可能的输出：

File opening error: No such file or directory
Now in German: Datei oder Verzeichnis nicht gefunden
Now in Chinese: 没有那个文件或目录

引用

C11 standard (ISO/IEC 9899:2011):

7.24.6.2 The strerror function (p: 371)

K.3.7.4.2 The strerror_s function (p: 622)

K.3.7.4.3 The strerrorlen_s function (p: 623)

C99 standard (ISO/IEC 9899:1999):

7.21.6.2 The strerror function (p: 334)

C89/C90 standard (ISO/IEC 9899:1990):

4.11.6.2 The strerror function

参阅

perror	显示对应当前错误的字符串到 stderr (函数)
errno	展开成 POSIX 兼容的线程局域错误编号变量 (宏变量)