STRTOL(3)

ИМЯ
strtol, strtoll, strtoq - преобразует строку в длинное целое число

ОБЗОР
#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():
    _ISOC99_SOURCE
        || /* в версии glibc <= 2.19: */ _SVID_SOURCE || _BSD_SOURCE

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

Строка может начинаться с произвольного количества пробельных символов (определяемых при помощи isspace(3)), затем может быть указан знак «+» или «-». Если base равно 0 или 16, то строка может начинаться с приставки «0x» или «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.

ОШИБКИ

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

ERANGE
    Полученное значение вне диапазона.

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

АТРИБУТЫ
Описание терминов данного раздела смотрите в 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);
    }

СМОТРИТЕ ТАКЖЕ
atof(3), atoi(3), atol(3), strtod(3), strtoul(3)