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) Вычисляет длину не обрезанного сообщения об ошибке, зависящего от локали, которое функция strerror_s записала бы, если бы она была вызвана с errnum. Длина не включает нулевой терминатор. Как и во всех функциях с проверкой границ, strerror_s и strerrorlen_s гарантированно доступны только в том случае, если __STDC_LIB_EXT1__ определено реализацией, и если пользователь задаёт __STDC_WANT_LIB_EXT1__ целочисленной константе 1 перед включением <string.h>.

Параметры

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, "ja_JP.utf8"); // printf needs CTYPE for multibyte output
        size_t errmsglen = strerrorlen_s(errno) + 1;
        char errmsg[errmsglen]; 
        strerror_s(errmsg, errmsglen, errno);
        printf("Now in Japanese: %s\n", errmsg);
#endif
    }
}

Возможный вывод:

File opening error: No such file or directory
Now in German: Datei oder Verzeichnis nicht gefunden
Now in Japanese: そのようなファイル、又はディレクトリはありません

Ссылки

Стандарт C11 (ISO/IEC 9899:2011):

7.24.6.2 Функция strerror (стр. 371)
K.3.7.4.2 Функция strerror_s (стр. 622)
K.3.7.4.3 Функция strerrorlen_s (стр. 623)

Стандарт C99 (ISO/IEC 9899:1999):

7.21.6.2 Функция strerror (стр. 334)

Стандарт C89/C90 (ISO/IEC 9899:1990):

4.11.6.2 Функция strerror

См. также

perror	отображает строку символов, соответствующую текущей ошибке `stderr` (функция)
errno	макрос, который расширяется до совместимой с POSIX потоково-локальной переменной номера ошибки (макрос-переменная)
Документация C++ для `strerror`

© cppreference.com
Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.
https://en.cppreference.com/w/c/string/byte/strerror