strtoll(3)

NOMBRE
strtol, strtoll, strtoq - convierten una cadena en un entero de tipo long

BIBLIOTECA
Biblioteca Estándar C (libc, -lc)

SINOPSIS
#include <stdlib.h>

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

    Requisitos de Macros de Prueba de Características para glibc (véase feature_test_macros(7)):

strtoll():
    _ISOC99_SOURCE
        || /* glibc <= 2.19: */ _SVID_SOURCE || _BSD_SOURCE

DESCRIPCIÓN
La función strtol() convierte la parte inicial de la cadena de entrada nptr en un valor entero de tipo long de acuerdo a la base dada, que debe estar entre 2 y 36 ambos incluidos o ser el valor especial 0.

La cadena puede comenzar con una cantidad arbitraria de espacios en blanco (según lo determinado por isspace(3)) seguido de un único signo opcional '+' o '-'. Si base es cero o 16, la cadena puede incluir un prefijo «0x» o «0X», y el número se leerá en base 16; si base es cero o 2, la cadena puede incluir un prefijo «0b» o «0B», y el número se leerá en base 2. De lo contrario, un cero base se toma como 10 (decimal), a menos que el siguiente carácter sea '0', en cuyo caso se toma como 8 (octal).

El resto de la cadena se convierte a un valor long de forma obvia, deteniéndose en el primer carácter que no sea un dígito válido en la base dada. (En bases superiores a 10, la letra 'A', ya sea en mayúscula o minúscula, representa 10, 'B' representa 11, y así sucesivamente, con 'Z' representando 35).

Si endptr no es NULL y se admite base, strtol() almacena la dirección del primer carácter no válido en *endptr. Si no hay dígitos, strtol() almacena el valor original de nptr en *endptr (y devuelve 0). En particular, si *nptr no es '\0' pero **endptr sí es '\0' al devolver, la cadena completa es válida.

La función strtoll() hace el mismo trabajo que la función strtol() pero devuelve un valor entero de tipo long long.

VALOR DEVUELTO
La función strtol() devuelve el resultado de la conversión, a menos que el valor se desbordara por arriba o por abajo. Si ocurriera un desbordamiento inferior, strtol() devuelve LONG_MIN. Si ocurriera un desbordamiento superior, strtol() devuelve LONG_MAX. En ambos casos, errno se establece a ERANGE. Precisamente lo mismo se aplica a strtoll() (con LLONG_MIN y LLONG_MAX en lugar de LONG_MIN y LONG_MAX).

ERRORES
Esta función no modifica errno en caso de éxito.

EINVAL
    (no está en C99) La base dada contiene un valor no soportado.

ERANGE
    El valor resultante está fuera de rango.

La implementación puede poner también errno a EINVAL en caso de que no se realice ninguna conversión (no se encuentren dígitos, y se devuelva 0).

ATRIBUTOS
Para obtener una explicación de los términos usados en esta sección, véase attributes(7).
Interfaz | Atributo | Valor
strtol(), strtoll(), strtoq() | Seguridad del hilo | Configuración regional de multi-hilo seguro

VERSIONES
Según POSIX.1, en configuraciones regionales distintas de «C» y «POSIX», estas funciones pueden aceptar otras cadenas numéricas definidas por la implementación.

BSD tiene también la función

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

con una definición completamente análoga. Dependiendo del tamaño de palabra de la arquitectura actual, ésta puede ser equivalente a strtoll() o a strtol().

ESTÁNDARES
C23, POSIX.1-2024.

HISTORIAL

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

strtoll()
    POSIX.1-2001, C99.

"0b", "0B"
    C23. glibc 2.38. (No en POSIX).

ADVERTENCIAS

  Comprobaciones de intervalo
Dado que strtol() puede devolver legítimamente 0, LONG_MAX o LONG_MIN (LLONG_MAX o LLONG_MIN para strtoll()) tanto en caso de éxito como de fracaso, el programa que realiza la llamada debe establecer errno en 0 antes de la llamada y, a continuación, determinar si se ha producido un error comprobando si errno == ERANGE después de la llamada.

    errno = 0;
    n = strtol(s, &end, base);
    if (end == s)
    	goto no_number;
    if ((errno == ERANGE && n == _Minof(long)) || n < min)
    	goto too_low;
    if ((errno == ERANGE && n == _Maxof(long)) || n > max)
    	goto too_high;

  base
Si es necesario probar base, debe hacerse en una llamada donde se sepa que la cadena se ejecuta correctamente. De lo contrario, es imposible diferenciar los errores de forma portable.

    errno = 0;
    strtol("0", NULL, base);
    if (errno == EINVAL)
        goto unsupported_base;

ERRORES

  Espacio en blanco
Estas funciones aceptan espacios en blanco iniciales sin indicar nada. Para rechazarlos, llame a isspace(3) antes de strtol().

EJEMPLOS
El programa que se muestra a continuación muestra el uso de strtol(). El primer argumento de la línea de órdenes especifica una cadena desde la cual strtol() debe analizar un número. El segundo argumento (opcional) especifica la base que se utilizará para la conversión. (Este argumento se convierte a formato numérico mediante atoi(3), una función que no realiza comprobación de errores y tiene una interfaz más sencilla que strtol()). Algunos ejemplos de los resultados generados por este programa son los siguientes:

    $ ./a.out 123
    strtol() returned 123
    $ ./a.out '    123'
    strtol() returned 123
    $ ./a.out 123abc
    strtol() returned 123
    Further characters after number: "abc"
    $ ./a.out 123abc 55
    strtol: Invalid argument
    $ ./a.out ''
    No digits were found
    $ ./a.out 4000000000
    strtol: Numerical result out of range

  Código fuente
    #include <errno.h>
    #include <stdio.h>
    #include <stdlib.h>

    int
    main(int argc, char *argv[])
    {
        int base;
        char *endptr, *str;
        long val;

        if (argc < 2) {
            fprintf(stderr, "Usage: %s str [base]\n", argv[0]);
            exit(EXIT_FAILURE);
        }

        str = argv[1];
        base = (argc > 2) ? atoi(argv[2]) : 0;

        errno = 0;    /* Para diferenciar el éxito/error después de la llamada */
        strtol("0", NULL, base);
        if (errno == EINVAL) {
            perror("strtol");
            exit(EXIT_FAILURE);
        }

        errno = 0;    /* Para distinguir el éxito/error después de la llamada */
        val = strtol(str, &endptr, base);

        /* Comprueba varios posibles errores  */

        if (errno == ERANGE) {
            perror("strtol");
            exit(EXIT_FAILURE);
        }

        if (endptr == str) {
            fprintf(stderr, "No digits were found\n");
            exit(EXIT_FAILURE);
        }

        /* Si llegamos hasta aqui, seguro que strtol() ha encontrado un número.  */

        printf("strtol() returned %ld\n", val);

        if (*endptr != '\0')        /* No necesariamente un error.  */
            printf("Further characters after number: \"%s\"\n", endptr);

        exit(EXIT_SUCCESS);
    }

VÉASE TAMBIÉN
atof(3), atoi(3), atol(3), strtod(3), strtoimax(3), strtoul(3)

TRADUCCIÓN
La traducción al español de esta página del manual fue creada por Carlos Gomez Romero <cgomez@databasedm.es>, Miguel Pérez Ibars <mpi79470@alu.um.es> y Marcos Fouces <marcos@debian.org>

Esta traducción es documentación libre; lea la GNU General Public License Version 3 (https://www.gnu.org/licenses/gpl-3.0.html) o posterior con respecto a las condiciones de copyright. No existe NINGUNA RESPONSABILIDAD.

Si encuentra algún error en la traducción de esta página del manual, envíe un correo electrónico a debian-l10n-spanish@lists.debian.org.