ИМЯ¶

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():

ОПИСАНИЕ¶

Функция 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(): 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)

ЗАМЕЧАНИЯ¶

Эта страница является частью проекта Linux man-pages версии 4.16. Описание проекта, информацию об ошибках и последнюю версию этой страницы можно найти по адресу https://www.kernel.org/doc/man-pages/.

ПЕРЕВОД¶

Русский перевод этой страницы руководства был сделан Alexander Golubev <fatzer2@gmail.com>, Azamat Hackimov <azamat.hackimov@gmail.com>, Hotellook, Nikita <zxcvbnm3230@mail.ru>, Spiros Georgaras <sng@hellug.gr>, Vladislav <ivladislavefimov@gmail.com>, Yuri Kozlov <yuray@komyakino.ru> и Иван Павлов <pavia00@gmail.com>

Этот перевод является бесплатной документацией; прочитайте Стандартную общественную лицензию GNU версии 3 или более позднюю, чтобы узнать об условиях авторского права. Мы не несем НИКАКОЙ ОТВЕТСТВЕННОСТИ.

Если вы обнаружите ошибки в переводе этой страницы руководства, пожалуйста, отправьте электронное письмо на man-pages-ru-talks@lists.sourceforge.net.