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-совместимо */

char *strerror_r(int errnum, char *buf, size_t buflen);
            /* есть только в GNU */

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, то возвращается описание «Invalid argument»). Эту строку нельзя изменять в приложении, она может измениться при последующих вызовах strerror() или strerror_l(). Другие библиотечные функции, включая perror(3), не изменяют эту строку.

  strerror_r()
Функция strerror_r() подобна strerror(), но её можно безопасно использовать в нитях. Она доступна в двух версиях: версия, совместимая с XSI, определена в POSIX.1-2001 (доступна в glibc начиная с 2.3.4, но не совместима с POSIX до glibc 2.13) и версия, совместимая с GNU (доступна, начиная с glibc 2.0). Версия, совместимая с XSI, предоставляется при наличии набора макросов тестирования свойств, показанных в ОБЗОРЕ; в противном случае предоставляется версия GNU. Если макросы тестирования свойств не указаны явным образом, то (начиная с glibc 2.4) по умолчанию определяется _POSIX_C_SOURCE со значением 200112L, то есть версия strerror_r() XSI предоставляется по умолчанию.

Совместимая с XSI версия strerror_r() более предпочтительна для переносимых приложений. Она возвращает строку ошибки в предоставляемом пользователем буфере buf длиной buflen.

Специальная GNU-версия strerror_r() возвращает строку, содержащую сообщение об ошибке. Это может быть или указатель на строку, которую функция записывает в buf, или указатель на некую (неизменную) статическую строку (в этом случае buf не используется). Если функция сохраняет строку в buf, то сохраняется не более buflen байт (строка может быть обрезана, если значение buflen слишком мало и errnum неизвестно). В строке всегда содержится конечный байт null ('\0').

  strerror_l()
Функция strerror_l() подобна strerror(), но отражает errnum в локале-зависимое сообщение об ошибке, в зависимости от локали, заданной в locale. Поведение strerror_l() не определено, если значение locale равно специальному объекту локали LC_GLOBAL_LOCALE или некорректному описателю объекта локали.

ВОЗВРАЩАЕМОЕ ЗНАЧЕНИЕ
Функции strerror(), strerror_l() и GNU-версия strerror_r() возвращают соответствующую строку описания ошибки или сообщение «Unknown error nnn», если номер ошибки неизвестен.

При успешном выполнении совместимая с XSI функция 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_l() впервые появилась в glibc 2.6.

АТРИБУТЫ
Описание терминов данного раздела смотрите в attributes(7).
Интерфейс | Атрибут | Значение
strerror() | Безвредность в нитях | MT-Unsafe race:strerror
strerror_r(), strerror_l() | Безвредность в нитях | MT-Safe

СООТВЕТСТВИЕ СТАНДАРТАМ
Функция 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.

ЗАМЕЧАНИЯ
В библиотеке GNU C для strerror() используется буфер в 1024 символов. Размер буфера должен быть достаточным для исключения возникновения ошибки ERANGE при вызове strerror_r().

СМОТРИТЕ ТАКЖЕ
err(3), errno(3), error(3), perror(3), strsignal(3), locale(7)