ОБЗОР

#include <stdlib.h>

---

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

---

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

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

strtoll():

_XOPEN_SOURCE >= 600 || _BSD_SOURCE || _SVID_SOURCE || _ISOC99_SOURCE || _POSIX_C_SOURCE >= 200112L;
или cc -std=c99

ОПИСАНИЕ

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

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

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

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

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

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

Функция strtol() возвращает результат преобразования, если значение не вызывает переполнения или потерю точности. Если возникает потеря точности, то strtol() возвращает LONG_MIN. Если возникает переполнение, то strtoul() возвращает LONG_MAX. В обоих случаях переменной errno присваивается значение ERANGE. То же самое относится к strtoll(), только вместо LONG_MIN и LONG_MAX возвращается LLONG_MIN и LLONG_MAX.

АТРИБУТЫ

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

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

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

strtol(): POSIX.1-2001, POSIX.1-2008, C89, C99 SVr4, 4.3BSD.

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

ЗАМЕЧАНИЯ

Так как strtol() может обоснованно вернуть 0, LONG_MAX или LONG_MIN (а strtoll() — LLONG_MAX или LLONG_MIN) при успешном выполнении и ошибке, вызывающая программа до вызова должна присвоить errno значение 0, а после вызова определить возникновение ошибки по ненулевому значению errno.

Согласно POSIX.1, в локалях отличных от «C» и «POSIX», эти функции могут преобразовывать другие, определяемые реализацией, строки с числами.

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

quad_t strtoq(const char *nptr, char **endptr, int base);

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

ПРИМЕР

Программа, представленная далее, показывает использование strtol(). В первом аргументе командной строки указывается срока, из которой strtol() должна извлечь число. Во втором (необязательном) аргументе указывается система счисления, используемая для преобразования (этот аргумент преобразуется в число с помощью atoi(3), функции, которая не учитывает ошибки и имеет более простой интерфейс по сравнению с strtol()). Вот несколько результатов работы этой программы:

$ ./a.out 123
strtol() вернула 123
$ ./a.out '    123'
strtol() вернула 123
$ ./a.out 123abc
strtol() вернула 123
Остальные символы после числа: abc
$ ./a.out 123abc 55
strtol: некорректный аргумент
$ ./a.out ''
Цифры отсутствуют
$ ./a.out 4000000000
strtol: Числовой результат выходит за диапазон

Исходный код программы

#include <stdlib.h>
#include <limits.h>
#include <stdio.h>
#include <errno.h>
int
main(int argc, char *argv[])
{
    int base;
    char *endptr, *str;
    long val;
    if (argc < 2) {
        fprintf(stderr, "Использование: %s строка [система_счисления]\n", argv[0]);
        exit(EXIT_FAILURE);
    }
    str = argv[1];
    base = (argc > 2) ? atoi(argv[2]) : 10;
    errno = 0;    /* чтобы выявить ошибку после вызова */
    val = strtol(str, &endptr, base);
    /* проверка возможных ошибок */
    if ((errno == ERANGE && (val == LONG_MAX || val == LONG_MIN))
            || (errno != 0 && val == 0)) {
        perror("strtol");
        exit(EXIT_FAILURE);
    }
    if (endptr == str) {
        fprintf(stderr, "Цифры отсутствуют\n");
        exit(EXIT_FAILURE);
    }
    /* если мы дошли сюда, то strtol() успешно преобразовала число */
    printf("strtol() вернула %ld\n", val);
    if (*endptr != '\0')        /* необязательно ошибка… */
        printf("Остальные символы после числа: %s\n", endptr);
    exit(EXIT_SUCCESS);
}