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);

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).

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

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

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

ERRORES

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

#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;    /* To distinguish success/failure after call */
    strtol("0", NULL, base);
    if (errno == EINVAL) {
        perror("strtol");
        exit(EXIT_FAILURE);
    }
    errno = 0;    /* To distinguish success/failure after call */
    val = strtol(str, &endptr, base);
    /* Check for various possible errors. */
    if (errno == ERANGE) {
        perror("strtol");
        exit(EXIT_FAILURE);
    }
    if (endptr == str) {
        fprintf(stderr, "No digits were found\n");
        exit(EXIT_FAILURE);
    }
    /* If we got here, strtol() successfully parsed a number. */
    printf("strtol() returned %ld\n", val);
    if (*endptr != '\0')        /* Not necessarily an 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 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.