String to Int in C: atoi, strtol, and Converting Numbers to Text

Text arrives from users, files, and the command line as characters. "42" is three bytes - '4', '2', '\0' - and nothing in it is the number 42 until you convert it. C offers two generations of conversion functions: the short, old ones that cannot report errors, and the longer ones that can. This page shows both and explains why real programs use the second set.

The Old Family: atoi, atol, atof

They read like their names: ASCII to int, to long, to double. One argument, one result.

#include <stdio.h>
#include <stdlib.h>

int main(void) {
    printf("%d\n", atoi("42"));
    printf("%d\n", atoi("  -17 trailing junk"));
    printf("%f\n", atof("3.14"));
    return 0;
}

Leading whitespace is skipped, an optional sign is read, digits are consumed, and everything after is ignored. That is convenient until the input is wrong:

#include <stdio.h>
#include <stdlib.h>

int main(void) {
    printf("atoi(\"0\")     = %d\n", atoi("0"));
    printf("atoi(\"hello\") = %d\n", atoi("hello"));
    printf("atoi(\"\")      = %d\n", atoi(""));
    return 0;
}

All three print 0. There is no return code, no flag, no way to ask "did that work?" - and a value that overflows int is undefined behavior rather than a reported error. For a hard-coded literal in a toy program that is tolerable. For anything a person or a file can supply, it is a silent bug generator.

The Right Tool: strtol

strtol (string to long) is the same conversion with two channels for reporting what happened.

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

endptr is set to the first character the function did not consume. base is the number base - use 10, or 0 to let the literal's own prefix decide (0x for hex, leading 0 for octal).

#include <stdio.h>
#include <stdlib.h>

int main(void) {
    const char *input = "42 apples";
    char *end;

    long value = strtol(input, &end, 10);

    printf("value = %ld\n", value);
    printf("stopped at: \"%s\"\n", end);
    printf("consumed %td characters\n", end - input);
    return 0;
}

Reading endptr answers the questions atoi cannot:

• end == input means nothing was converted - the text did not start with a number.
• *end != '\0' means there was trailing content. Whether that is an error is your call: it is fine when parsing "42 apples", and a problem when the whole line should have been a number.

Overflow is reported separately through errno. The full, correct idiom is worth writing once and reusing:

#include <stdio.h>
#include <stdlib.h>
#include <errno.h>
#include <limits.h>

/* returns 1 on success, 0 on any kind of failure */
int parse_int(const char *text, int *out) {
    char *end;
    errno = 0;

    long value = strtol(text, &end, 10);

    if (end == text) {
        return 0;                 /* no digits at all */
    }
    if (*end != '\0') {
        return 0;                 /* trailing junk */
    }
    if (errno == ERANGE || value < INT_MIN || value > INT_MAX) {
        return 0;                 /* out of range for an int */
    }

    *out = (int)value;
    return 1;
}

int main(void) {
    const char *tests[] = {"42", "-7", "hello", "", "9999999999", "12abc"};
    int n = (int)(sizeof tests / sizeof tests[0]);

    for (int i = 0; i < n; i++) {
        int value;
        if (parse_int(tests[i], &value)) {
            printf("\"%s\" -> %d\n", tests[i], value);
        } else {
            printf("\"%s\" -> rejected\n", tests[i]);
        }
    }
    return 0;
}

Three details make this correct. errno = 0 before the call matters because the library only ever sets errno; it never clears it, so a stale value from an earlier call would be read as this call's failure. strtol returns long, which may be wider than int, so the range check against INT_MIN/INT_MAX is separate from ERANGE. And returning success as a status while delivering the value through a pointer is how C functions report "either a value or a failure" - the return value cannot do both jobs.

strtoul is the unsigned counterpart, and strtoll/strtoull handle long long.

Other Bases

Base 16 reads hexadecimal; base 0 inspects the prefix and decides for itself.

#include <stdio.h>
#include <stdlib.h>

int main(void) {
    char *end;

    printf("%ld\n", strtol("ff", &end, 16));      /* 255 */
    printf("%ld\n", strtol("0x1A", &end, 0));     /* 26, prefix detected */
    printf("%ld\n", strtol("1011", &end, 2));     /* 11, binary */
    printf("%ld\n", strtol("755", &end, 8));      /* 493, octal */
    return 0;
}

Base 0 is a trap in one specific case: a zero-padded decimal like "012" is read as octal and comes out as 10. If your input is decimal, say 10 explicitly.

Floating Point: strtod

strtod is the same shape for double, and atof has the same flaw as atoi.

#include <stdio.h>
#include <stdlib.h>
#include <errno.h>

int main(void) {
    const char *text = "3.14159 rest";
    char *end;
    errno = 0;

    double value = strtod(text, &end);

    if (end == text) {
        printf("not a number\n");
    } else if (errno == ERANGE) {
        printf("out of range\n");
    } else {
        printf("value = %f, stopped at \"%s\"\n", value, end);
    }
    return 0;
}

strtod also accepts scientific notation ("1.5e3"), hex floats, and the words "inf" and "nan". Locale affects the decimal separator, which surprises people parsing files written elsewhere - in the default "C" locale the separator is always a dot.

Numbers to Text: snprintf

Going the other way, snprintf is the standard answer. It writes at most the size you give it, always terminates, and returns the length the full result would have needed.

#include <stdio.h>

int main(void) {
    char buf[32];
    int n = 4095;

    int written = snprintf(buf, sizeof buf, "%d", n);
    printf("text: \"%s\" (needed %d chars)\n", buf, written);

    snprintf(buf, sizeof buf, "%05d", n);
    printf("padded: %s\n", buf);

    snprintf(buf, sizeof buf, "%x / %o / %.2f", n, n, n / 1000.0);
    printf("mixed:  %s\n", buf);
    return 0;
}

The return value is the truncation check. If it is greater than or equal to the buffer size, the text did not fit:

#include <stdio.h>

int main(void) {
    char small[8];

    int needed = snprintf(small, sizeof small, "value=%d", 1234567);

    if (needed < 0) {
        printf("encoding error\n");
    } else if ((size_t)needed >= sizeof small) {
        printf("truncated: \"%s\" (needed %d bytes)\n", small, needed + 1);
    } else {
        printf("ok: %s\n", small);
    }
    return 0;
}

Two things not to reach for: itoa is not part of standard C, so code using it will not compile everywhere; and sprintf is snprintf without the size limit, which means it will write past the end of your buffer without complaint.

Single Characters and '0'

The digit characters '0' through '9' are guaranteed to be consecutive, so plain subtraction converts between a digit character and its value.

#include <stdio.h>
#include <ctype.h>

int main(void) {
    char c = '7';
    int digit = c - '0';
    printf("char '%c' -> int %d\n", c, digit);

    int value = 3;
    char back = (char)(value + '0');
    printf("int %d -> char '%c'\n", value, back);
    return 0;
}

Only digits behave this way - letters are not required to be consecutive, so c - 'a' is not portable for alphabet arithmetic. Guard the subtraction with isdigit before trusting it:

#include <stdio.h>
#include <ctype.h>

int main(void) {
    char text[] = "a1b2c3";
    int sum = 0;

    for (int i = 0; text[i] != '\0'; i++) {
        if (isdigit((unsigned char)text[i])) {
            sum += text[i] - '0';
        }
    }

    printf("digits sum to %d\n", sum);
    return 0;
}

The cast to unsigned char is required for the same reason as in strings: the <ctype.h> functions are undefined for negative arguments, and plain char can be signed.

Which Function to Use

• Text from a user, a file, or argv → strtol / strtod with the full check.
• A literal you wrote yourself and control → atoi is acceptable, if unremarkable.
• Number into a buffer → snprintf, and check the return value.
• One digit character → subtract '0', after isdigit.
• Never → gets, sprintf, itoa.