fgetwln(3bsd)

💖 fgetwln — get a line of wide characters from a stream 💖

okay bestie, welcome to fgetwln(3bsd), the wide-character line-grabber from the BSD corner of the world. this is the page for it, and we're gonna go through everything, no skipping, no cap. ✨

📚 LIBRARY

Utility functions from BSD systems — that's libbsd, and you link it with -lbsd. 🫶

✨ SYNOPSIS ✨

#include <stdio.h>
#include <wchar.h>
(See libbsd(7) for include usage.)

wchar_t *
fgetwln(FILE * restrict stream, size_t * restrict len);

yeah so those includes are the vibe, and if you're confused about how the includes work in libbsd land, go peek at libbsd(7) — it explains the whole include situation. 🧚

🌸 DESCRIPTION 🌸

so like. fgetwln() hands you back a pointer to the next line from the stream that stream points at. that's the whole job. 💅

BUT. and this is the part that gets people — this line is not a standard wide character string, because it does not end with a terminating null wide character. no null terminator, bestie. it's giving "raw vibes only". 😭

instead, the length of the line — and yes, that includes the final newline — gets stored in the memory location that len points to. so that's how you know where the line ends, since there's no null doing it for you.

🎀 tiny caveat tho: if the line is the last one in a file that does not end in a newline, then the text you get back will not contain a newline. so like, don't go assuming every single return has one, okay?

🔥 RETURN VALUES 🔥

on a successful completion, you get a pointer back. iconic. but that pointer becomes invalid after the next I/O operation on stream — whether that operation was successful or not, doesn't matter — or as soon as the stream is closed. so use it fast, or copy it, your call. 👑

otherwise? NULL. and here's the tea: fgetwln() does not distinguish between end-of-file and error. it just gives you NULL and shrugs. so if you wanna know which one actually happened, you gotta go ask feof(3) and ferror(3). those are the routines that will tell you. 🙈

if an error occurs, the global variable errno is set to indicate the error.

and the end-of-file condition is remembered — even on a terminal — and all subsequent attempts to read will return NULL until that condition is cleared with clearerr(3). so like, it sticks around until you clear it. periodt.

also, the text that the returned pointer points to may be modified, as long as you don't make any changes beyond the returned size. but heads up — those changes are lost as soon as the pointer becomes invalid. so enjoy them while they last. 💀

💜 ERRORS 💜

• [EBADF] — the argument stream is not a stream open for reading. bestie, you gotta open it for reading. that's the rule.

and also: fgetwln() may fail and set errno for any of the errors specified for the routines mbrtowc(3), realloc(3), or read(2). so if you're debugging, those are the other places to look. 🌈

🦋 SEE ALSO 🦋

• ferror(3)
• fgetln(3bsd)
• fgetws(3)
• fopen(3)

Debian 🎀 July 16, 2004 — that's where this page comes from and when it was stamped, and honestly, a 2004 baddie that's still out here serving wide-character lines? iconic behavior, no notes. go read your lines bestie, ily, bye! 💖✨🫶