ИМЯ

strtoul, strtoull, strtouq - преобразование строки в целое с типом unsigned long integer

ОБЗОР

#include <stdlib.h>

unsigned long int strtoul(const char *nptr, char **endptr, int base);

unsigned long long int strtoull(const char *nptr, char **endptr,
                                int base);

Требования макроса тестирования свойств для glibc (см. feature_test_macros(7)):

strtoull():

_ISOC99_SOURCE || || /* в версии glibc <= 2.19: */ _SVID_SOURCE || _BSD_SOURCE

ОПИСАНИЕ

Функция strtoul() преобразует начальную часть строки nptr в число с типом unsigned long int согласно системе счисления base, значение которой может быть от 2 до 36 включительно или равно специальному значению 0.

Строка может начинаться с произвольного количества пробельных символов (определяемых при помощи isspace(3)), затем может быть указан знак «+» или «-». Если base равно 0 или 16, то строка может начинаться с приставки «0x», что означает использование шестнадцатеричной системы исчисления; иначе, если base равно нулю, то используется десятичная система счисления (кроме, когда последующий символ также равен «0»: в этом случае используется восьмеричная система исчисления).

Остаток строки преобразуется в число с типом unsigned long int. Этот процесс останавливается, если в строке встречается некорректный символ для указанной системе счисления. В системах счисления больших 10, символ «A» в верхнем или нижнем регистре означает 10, «B» означает 11 и так далее до «Z», означающего 35.

Если значение endptr не NULL, то strtoul() записывает адрес первого некорректного символа в *endptr. Если в строке вообще нет цифр, то strtoul() сохраняет изначальное значение nptr в *endptr (и возвращает 0). В частности, если *nptr не равно '\0', но **endptr равно '\0' при возврате, то вся строка состоит из корректных символов.

Функция strtoull() работает так же, как и strtoul(), но возвращает число с типом unsigned long long int.

ВОЗВРАЩАЕМОЕ ЗНАЧЕНИЕ

Функция strtoul() возвращает результат преобразования, либо, если был указан знак минуса, возвращается отрицательный результат преобразования, представленный в виде положительного числа, если изначальное (неотрицательное) значение не вызывает переполнения; в этом случае strtoul() возвращает ULONG_MAX, а переменной errno присваивается значение ERANGE. То же самое относится к strtoull(), только вместо ULONG_MAX возвращается ULLONG_MAX.

ОШИБКИ

EINVAL: (нет в C99) Аргумент base содержит неподдерживаемое значение.
ERANGE: Полученное значение вне диапазона.

Реализация может также устанавливать errno в EINVAL в случае, когда преобразование не было выполнено (не было встречено цифр и возвращён 0).

АТРИБУТЫ

Описание терминов данного раздела смотрите в attributes(7).

Интерфейс	Атрибут	Значение
strtoul(), strtoull(), strtouq()	Безвредность в нитях	MT-Safe locale

СООТВЕТСТВИЕ СТАНДАРТАМ

strtoul(): POSIX.1-2001, POSIX.1-2008, C89, C99 SVr4.

strtoull(): POSIX.1-2001, POSIX.1-2008, C99.

ЗАМЕЧАНИЯ

Так как strtoul() может обоснованно вернуть 0 или ULONG_MAX (ULLONG_MAX для strtoull()) при успешном выполнении и ошибке, вызывающая программа до вызова должна присвоить errno значение 0, а после вызова определить возникновение ошибки по ненулевому значению errno.

При помощи локалей могут приниматься строки, отличные от допустимых в локали «C» (например, может поддерживаться разделитель тысяч из текущей локали).

В BSD также есть функция

u_quad_t strtouq(const char *nptr, char **endptr, int base);

с полностью аналогичным определением. В зависимости от длины слова в текущей архитектуре, она может быть аналогом strtoull() или strtoul().

Отрицательные значения допустимы во входных данных и без ошибки преобразуются в эквивалентное значение с типом unsigned long int.

ПРИМЕР

Пример можно найти в справочной странице strtol(3); в ней показано использование похожих функций.

ИМЯ