FGETLN(3)

💅 FGETLN(3) — ok so this is the fgetln girlies' moment ✨

Welcome to the fgetln page, bestie — it's a libc classic from the Debian crew and I'm obsessed. Let's get into it 🫶

---

🎀 NAME 🎀

fgetln — get a line from a stream. That's it. That's the whole vibe.

---

📚 LIBRARY 📚

Standard C Library (libc, -lc). The og. The blueprint. 💖

---

✨ SYNOPSIS ✨

#include <stdio.h>

char *
fgetln(FILE *stream, size_t *len);

---

🌸 DESCRIPTION 🌸

Okay so fgetln() hands you back a pointer to the next line from the stream that stream points at. Cute, right? But here's the thing, and this is important, so listen up 🔥:

• This line is not a C string — it does not end with a terminating NUL character. Not me having to say this, but the function literally does not do it. 💀
• The length of the line — including the final newline — gets stored in the memory location that len points to.
• Small caveat bestie: if the line is the last line in a file that does not end in a newline, then the text you get back will not contain a newline either. The more you know 🌈

---

👑 RETURN VALUES 👑

On success, you get a pointer back 💖 — but lowkey this pointer is on a timer: it becomes invalid after the next I/O operation on stream (whether that op succeeded or not), or as soon as the stream is closed. So use it while it's fresh, iykyk.

Otherwise, NULL is returned. And here's the tragic part: fgetln() does not distinguish between end-of-file and error 😭. You have to call feof(3) and ferror(3) yourself to figure out which one actually happened. If an error occurs, the global variable errno gets set to indicate the error.

Also — the end-of-file condition is remembered, even on a terminal, and all subsequent attempts to read will return NULL until the condition is cleared with clearerr(3). She holds grudges. Periodt.

Now, the text the returned pointer points to may be modified, as long as you don't make changes beyond the returned size. But those changes are lost as soon as the pointer becomes invalid. So don't get attached 💔

---

💀 ERRORS 💀

• [EBADF] — the argument stream is not a stream open for reading. Girl is closed for business.
• [ENOMEM] — the internal line buffer could not be expanded due to lack of available memory, or because it would need to expand beyond INT_MAX in size. She's ambitious but not that ambitious.

fgetln() may also fail and set errno for any of the errors specified for the routines fflush(3), malloc(3), read(2), stat(2), or realloc(3). Whole friend group of failure modes fr fr.

---

🦋 SEE ALSO 🦋

ferror(3), fgets(3), fgetwln(3), fopen(3), getline(3), putc(3) — go read those too, they're all icons in their own right 🌟

---

🧚 HISTORY 🧚

The fgetln() function first appeared in 4.4BSD. Vintage. Main character energy since day one 👑

---

🙈 CAVEATS 🙈

So since the returned buffer is not a C string (it is not NUL terminated), the common practice is to replace the newline character with '\0'. Slay, that works. BUT — and this is the plot twist — if the last line in a file does not contain a newline, the returned text won't contain a newline either 😭 so there's nothing to replace and you're standing there like 🧍

The following code demonstrates how to deal with this problem by allocating a temporary buffer:

char *buf, *lbuf;
size_t len;

lbuf = NULL;
while ((buf = fgetln(fp, &len)) != NULL) {
        if (buf[len - 1] == '\n')
                buf[len - 1] = '\0';
        else {
                /* EOF without EOL, copy and add the NUL */
                if ((lbuf = malloc(len + 1)) == NULL)
                        err(1, NULL);
                memcpy(lbuf, buf, len);
                lbuf[len] = '\0';
                buf = lbuf;
        }
        printf("%s\n", buf);
}
free(lbuf);
if (ferror(fp))
        err(1, "fgetln");

Don't forget the free(lbuf) at the end, bestie — leaking memory is not the aesthetic 💅

---

And that's the page! This lil beauty comes to you from Debian, dated June 11, 2020 — a whole era. Stay hydrated, close your streams, and always check ferror 💜🦋✨