strtoul(3)

💖 strtoul(3) — the "string to unsigned long int" glow-up 💖

okay bestie, so this page lives in the Library Functions Manual, and honestly? it's giving "I convert your text into numbers and I do NOT miss." let's get into it 🫶

---

✨ NAME ✨

strtoul, strtoull, strtouq — string to unsigned long int, aka the trio that turns your cute little character strings into big unsigned numbers 💅

---

📚 LIBRARY 📚

Standard C library... which is libc, and you link it with -lc. iconic, we love a foundational queen 👑

---

🌸 SYNOPSIS 🌸

#include <stdlib.h>

unsigned long strtoul(const char *restrict nptr,
                      char **_Nullable restrict endptr, int base);
unsigned long long strtoull(const char *restrict nptr,
                      char **_Nullable restrict endptr, int base);

🧚 Feature Test Macro Requirements for glibc (see feature_test_macros(7)):

strtoull():

_ISOC99_SOURCE
    || /* glibc <= 2.19: */ _SVID_SOURCE || _BSD_SOURCE

ngl the whole "define a macro before you get the function" thing is so glibc-coded. _ISOC99_SOURCE is your main character here, and if you're on glibc <= 2.19 you can also slide in with _SVID_SOURCE or _BSD_SOURCE. periodt.

---

💫 DESCRIPTION 💫

So strtoul() takes the initial part of the string sitting in nptr and converts it into an unsigned long value, according to the base you hand it. that base has to be between 2 and 36 inclusive, OR it can be the special value 0. no in-between "3.5" nonsense, bestie 🙈

Here's the vibe of what the string is allowed to look like: it may start with an arbitrary amount of white space (as determined by isspace(3)), and then a single optional '+' or '-' sign. very demure. very mindful.

Now for the base detective work, and this part is important so pay attention 😭:

• if base is zero or 16, the string may then include a "0x" or "0X" prefix, and the number will be read in base 16 🔥
• if base is zero or 2, the string may then include a "0b" or "0B" prefix, and the number will be read in base 2 🦋
• otherwise, a zero base is taken as 10 (decimal) unless the next character is '0', in which case it is taken as 8 (octal) 🌈

The rest of the string gets converted to an unsigned long value "in the obvious manner" (their words, and honestly? fair), and it stops at the first character which is not a valid digit in the given base. for bases above 10, the letter 'A' in either uppercase or lowercase represents 10, 'B' represents 11, and so on and so forth, with 'Z' representing 35. that's the whole alphabet being drafted into number duty, we love range 💜

Now, the endptr tea ☕ — if endptr is not NULL, and the base is supported, strtoul() stores the address of the first invalid character in *endptr. but if there were no digits at all, strtoul() stores the original value of nptr in *endptr (and returns 0). and here's the little gotcha to remember: in particular, if *nptr is not '\0' but **endptr is '\0' on return, then the entire string is valid. chef's kiss 👑

And strtoull()? it works just like strtoul() but returns an unsigned long long value. same energy, bigger number. 💅

---

🔥 RETURN VALUE 🔥

strtoul() returns either the result of the conversion, OR — if there was a leading minus sign — the negation of the result of the conversion represented as an unsigned value. the exception (and there's always an exception, sigh): unless the original (nonnegated) value would overflow, and in that case strtoul() returns ULONG_MAX and sets errno to ERANGE. 😭

Precisely the same holds for strtoull() — just with ULLONG_MAX instead of ULONG_MAX. 💖

---

🎀 ERRORS 🎀

• This function does not modify errno on success. so if you see a change in there, something else did it, bestie, don't blame us ✨
• EINVAL (not in C99) — the given base contains an unsupported value.
• ERANGE — the resulting value was out of range.
• The implementation may also set errno to EINVAL in case no conversion was performed (no digits seen, and 0 returned). 🙈

---

👑 ATTRIBUTES 👑

For an explanation of the terms used in this section, see attributes(7). (the original lays this out as a whole table, but here it is in bullet form so it's easier on your eyes, bestie 🫶)

• strtoul(), strtoull(), strtouq() — Thread safety: MT-Safe locale 🌈

---

🦋 VERSIONS 🦋

In locales other than the "C" locale, other strings may be accepted. for example, the thousands separator of the current locale may be supported. so yes, your locale can lowkey change what counts as a valid number. wild, I know 💀

BSD also has:

u_quad_t strtouq(const char *nptr, char **endptr, int base);

with a completely analogous definition. depending on the wordsize of the current architecture, this may be equivalent to strtoull() or to strtoul(). so it's giving "who am I today? depends on the architecture" 🧚

---

⭐ STANDARDS ⭐

C23, POSIX.1-2024. certified, stamped, approved 💅

---

💜 HISTORY 💜

• strtoul() — POSIX.1-2001, C89, SVr4.
• strtoull() — POSIX.1-2001, C99.
• "0b", "0B" — C23. glibc 2.38. (Not in POSIX.)

---

🌸 CAVEATS 🌸

okay this one's the classic trap and I need you to hear me 😭 since strtoul() can legitimately return 0 or ULONG_MAX (ULLONG_MAX for strtoull()) on both success and failure, the calling program should set errno to 0 before the call, and then determine if an error occurred by checking whether errno has a nonzero value after the call. don't skip the pre-call reset, bestie, it's literally the whole plot 🫶

---

⚠️ BUGS ⚠️

💀 Signed numbers

Some negative values are considered valid input and are silently converted to unsigned long. silently! no warning, no drama, just vibes 😭

💀 White space

These functions silently accept leading whitespace. yep. more silent behavior. 🙈

💀 isalnum(3)

To reject white space and/or a sign, call isalnum(3) before strtoul(). that's the move 🌟

---

🌈 EXAMPLES 🌈

See the example on the strtol(3) manual page — the use of the functions described in this manual page is similar. go peek, bestie, it's the same energy 💖

---

🎀 SEE ALSO 🎀

a64l(3), atof(3), atoi(3), atol(3), strtod(3), strtol(3), strtoumax(3)

---

and that's the whole page, no cap 💅 this absolute icon of a man page comes to you from Linux man-pages 6.20, dated 2026-07-26 — stan a consistent release schedule, periodt ✨🫶