FGETS(3)

✨ FGETS(3) ✨

okay bestie so this is the fgets page from the Library Functions Manual, and lowkey it's a whole mood: it's about grabbing a line from a stream, and it also has to break the news that gets() is gone-gone. 💅

---

🎀 NAME 🎀

fgets, gets_s — get a line from a stream

like, one singular line. from a stream. that's the whole vibe check. 🦋

---

📚 LIBRARY 📚

Standard C Library (libc, -lc)

---

✨ SYNOPSIS ✨

#include <stdio.h>

char *
fgets(char * restrict str, int size, FILE * restrict stream);

#define __STDC_WANT_LIB_EXT1__ 1

char *
gets_s(char *str, rsize_t size);

note the #define __STDC_WANT_LIB_EXT1__ 1 up there — you literally cannot summon gets_s without it, iykyk. 🫶

---

💖 DESCRIPTION 💖

okay so fgets() reads at most one less than the number of characters you specified with size from the stream you gave it, and stashes them in the string str. the way that "one less" detail matters — that's your room for the null terminator, bestie. it stops reading when it hits a newline character, at end-of-file, or on error. and the newline? if there is one, it's retained. she stays. 🎀

if any characters were read and there's no error, a '\0' character gets appended to end the string. classic.

gets_s() is equivalent to fgets() with a stream of stdin, except the newline character (if any) is not stored in the string. so like, similar energy but the newline does NOT get an invite to the party. 🙈

and then there's gets(). bestie. the gets() function was unsafe and is no longer available. she's not coming back. we don't talk about her. 💀

---

🔥 RETURN VALUES 🔥

upon successful completion, fgets() and gets_s() return a pointer to the string. slay. 👑

but listen:

• if end-of-file occurs before any characters are read, they return NULL and the buffer contents remain unchanged.
• if an error occurs, they return NULL and the buffer contents are indeterminate (😭 do not trust them).

and here's the main-character plot twist: fgets() and gets_s() do not distinguish between end-of-file and error, so you as the caller literally have to use feof(3) and ferror(3) to figure out which one actually happened. no cap. 🧚

---

🌸 ERRORS 🌸

• [EBADF] — the given stream is not a readable stream. like, she cannot be read from. that's the error. 💅

The function fgets() may also fail and set errno for any of the errors specified for the routines fflush(3), fstat(2), read(2), or malloc(3).

The function gets_s() may also fail and set errno for any of the errors specified for the routine getchar(3).

---

🦋 SEE ALSO 🦋

• feof(3)
• ferror(3)
• fgetln(3)
• fgetws(3)
• getline(3)

go read those too, they're fr fr important — especially feof(3) and ferror(3), since you need them to tell eof apart from an actual error. 💜

---

🌈 STANDARDS 🌈

The fgets() function conforms to ISO/IEC 9899:1999 ("ISO C99").

gets_s() conforms to ISO/IEC 9899:2011 ("ISO C11") K.3.7.4.1.

gets() has been removed from ISO/IEC 9899:2011 ("ISO C11"). yeah. removed removed. ⭐

---

👑 HISTORY 👑

The functions fgets() and gets() first appeared in Version 7 AT&T UNIX. vintage icons, honestly. 🎀

---

and that's the whole page, bestie — this one shipped with Debian, dated December 6, 2024, and it's FGETS(3) forever and always. mwah. 💋✨