| STRERROR(3) | Руководство программиста Linux | 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():
Функция strerror() возвращает указатель на строку, которая описывает код ошибки, переданный в аргументе errnum, возможно, с помощью части LC_MESSAGES текущей локали для выбора соответствующего языка (например, если errnum равно EINVAL, то возвращается описание «Invalid argument»). Эту строку нельзя изменять в приложении, она может измениться при последующих вызовах strerror() или strerror_l(). Другие библиотечные функции, включая perror(3), не изменяют эту строку.
Функция 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(), но отражает 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 после вызова.
Функция 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)
| 2019-03-06 |