strerror

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():
           Совместимая с 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(),  │ Безвредность в нитях │ MT-Safe                 │
       │strerror_l()   │                      │                         │
       └───────────────┴──────────────────────┴─────────────────────────┘
СООТВЕТСТВИЕ СТАНДАРТАМ
       Функция 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.

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



                                   2016-03-15                        STRERROR(3)