scanf(3)

💖 scanf(3) — bestie edition 💖

okay so you're looking at the scanf(3) page from the Library Functions Manual, and tbh this is the iconic messy queen of stdio. she scans formatted input. she's also, and I cannot stress this enough, kind of a nightmare. let's get into it 🫶

---

✨ NAME ✨

scanf, fscanf, vscanf, vfscanf — input FILE format conversion 💅

📚 LIBRARY 📚

Standard C library (libc, -lc) — she's built in, no extra drama required ✨

🌸 SYNOPSIS 🌸

#include <stdio.h>

int scanf(const char *restrict format, ...);
int fscanf(FILE *restrict stream,
           const char *restrict format, ...);

#include <stdarg.h>

int vscanf(const char *restrict format, va_list ap);
int vfscanf(FILE *restrict stream,
           const char *restrict format, va_list ap);

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

for vscanf(), vfscanf():

_ISOC99_SOURCE || _POSIX_C_SOURCE >= 200112L

---

💜 DESCRIPTION 💜

so the scanf() family scans formatted input, kinda like sscanf(3) does, except it reads from a FILE. and bestie. ngl. these functions are very difficult to use correctly 😭 the manpage itself says it's preferable to read whole lines with fgets(3) or getline(3) and then parse them later with sscanf(3), or with something more specialized like strtol(3). like, that's the author telling you to take a different route. periodt.

scanf() reads its input from the standard input stream, aka stdin, and fscanf() reads input from the stream pointer, aka stream. two sisters, one vibe 🌈

vfscanf() is the analog of vfprintf(3) — it reads input from the stream pointer stream using a variable argument list of pointers (peep stdarg(3)). and vscanf() is the analog of vprintf(3), and it reads from the standard input. so it's giving "same energy, but the args come in via va_list" 💅

---

🎀 RETURN VALUE 🎀

on success, these functions return the number of input items successfully matched and assigned. lowkey that can be fewer than you provided for, or even zero, if there's an early matching failure. zero items. nothing. we got nothing. 🙈

the value EOF comes back if the end of input is reached before either the first successful conversion or a matching failure happens. EOF is also returned if a read error occurs — in that case the error indicator for the stream gets set (see ferror(3)), and errno is set to indicate the error. so basically EOF is doing double duty and you have to check errno to know which one it is 💀

---

🔥 ERRORS 🔥

• EAGAIN — the file descriptor underlying stream is marked nonblocking, and the read operation would block. she's not waiting around, bestie.
• EBADF — the file descriptor underlying stream is invalid, or it's not open for reading. wrong door, no entry 🚫
• EILSEQ — the input byte sequence does not form a valid character.
• EINTR — the read operation was interrupted by a signal; see signal(7).
• EINVAL — not enough arguments; or format is NULL. (she counted your args and she's disappointed.)
• ENOMEM — out of memory.

---

👑 ATTRIBUTES 👑

for an explanation of the terms used in this section, see attributes(7).

• Interface: scanf(), fscanf(), vscanf(), vfscanf() — Attribute: Thread safety — Value: MT-Safe locale

---

⭐ STANDARDS ⭐

C11, POSIX.1-2008. certified ✨

🦋 HISTORY 🦋

C99, POSIX.1-2001. she's been around, she's seen things.

---

💀 CAVEATS 💀

these functions make it genuinely difficult to tell newlines apart from other white space. and that's especially problematic with line-buffered input, like the standard input stream. no cap, this will bite you.

also, these functions can't report errors after the last non-suppressed conversion specification. so errors happening at the very end? completely invisible. 🫥

---

🌸 BUGS 🌸

it is impossible to accurately know how many characters these functions have consumed from the input stream, because they only report the number of successful conversions. like. literally impossible. let that sink in 😭

for example, if the input is "123\n a", then

scanf("%d %d", &a, &b)

will consume the digits, the newline, and the space — but not the letter a.

and that is exactly why it's so difficult to recover from invalid input. the stream is somewhere, you don't know where, and she's not telling you. 🙈

---

🌈 SEE ALSO 🌈

fgets(3), getline(3), sscanf(3)

---

okay that's the whole page, bestie 💖 this was Linux man-pages 6.20, dated 2025-09-21, and remember: read the whole line first, parse it after, and keep your errno close 🎀✨🫶

scanf(3)