fparseln(3bsd)

💖 fparseln — like, the manual page for fparseln(3bsd) 💖

okay bestie, sit down, hydrate, because today we're learning about fparseln — the little function that goes "hey, gimme the next logical line from this stream" and then actually does it. no cap. it's from section 3bsd, and it is serving.

✨ LIBRARY ✨

it lives in the Utility functions from BSD systems, which is libbsd, and you link it with -lbsd. iconic. 🔥

🌸 SYNOPSIS 🌸

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

char *
fparseln(FILE *stream, size_t *len, size_t *lineno, const char delim[3],
    int flags);

🫶 heads up: the #include <stdio.h> line comes with a lil footnote — check libbsd(7) for include usage. it's giving "read the fine print, babe".

💅 DESCRIPTION 💅

so. fparseln() returns a pointer to the next logical line from the stream you passed it. the string is NUL terminated, and it gets dynamically allocated on every single invocation — like a fresh fit every time. and because it's your new toy, it is 100% your responsibility to free() that pointer. bestie, free your pointers. i'm begging. 😭

by default, if a character is escaped, both it and the preceding escape character will show up in the returned string. like, both of them. just hanging out. but!! there are flags that alter this behaviour, so if you want that escape character gone, keep reading. 💖

now the arguments, one by one, no skipping:

• stream — the stream to read from. that's it, that's the vibe. the source of the tea. ☕
• len — if it's not NULL, the length of the string gets stored in the memory location it points to. so pass a pointer and it'll tell you how long your line is. 🎀
• lineno — if it's not NULL, the value at the memory location it points to gets incremented by the number of lines actually read from the file. yes, actually read — so no, it's not just "+1 per call", it counts the real lines it chomped through. 💀
• delim — this one contains the escape, continuation, and comment characters. important rules:
  • if a character is NUL, then processing for that character is disabled. gone. off. not invited.
  • if delim is NULL, all the characters default to the values listed below. easy.

the contents of delim go like this:

• delim[0] — the escape character, which defaults to \, is used to remove any special meaning from the next character.
• delim[1] — the continuation character, which defaults to \, is used to indicate that the next line should be concatenated with the current one — but only if this character is the last character on the current line and it is not escaped. two conditions, both required, no exceptions. ✨
• delim[2] — the comment character, which defaults to #, and if it's not escaped, it indicates the beginning of a comment that extends until the end of the current line. bye to everything after it. 👋

• flags — if non-zero, it alters the operation of fparseln(). you can or them together, and here's the full menu, no substitutions:
  • FPARSELN_UNESCCOMM — remove escape preceding an escaped comment.
  • FPARSELN_UNESCCONT — remove escape preceding an escaped continuation.
  • FPARSELN_UNESCESC — remove escape preceding an escaped escape.
  • FPARSELN_UNESCREST — remove escape preceding any other character.
  • FPARSELN_UNESCALL — all of the above. the whole set. the full bundle. slay. 👑

🌈 RETURN VALUES 🌈

• if everything goes well, you get a pointer to the parsed line. 💖
• otherwise, you get NULL. 😭

and here's the lore: fparseln() uses getline(3) internally, so every single error condition that applies to getline(3) also applies to fparseln(). plus, in addition, fparseln() may set errno to [ENOMEM] and return NULL if it runs out of memory. so if your memory said "no <3", you get ENOMEM and a NULL. 🫠

🦋 SEE ALSO 🦋

• getline(3)

⭐ HISTORY ⭐

the fparseln() function first appeared in NetBSD 1.4 and FreeBSD 4.0. vintage, honestly. a classic. 🎀

and that's the whole page, bestie!! this lil rewrite came to you from Debian, dated November 30, 2002 — so if you're reading this, mwah, thanks for coming to my ted talk, now go free() your pointers 💅✨🫶