gd_nframes(3)

💖 gd_nframes — the GETDATA manual, but make it make sense 💖

okay bestie, buckle up, we're reading a GETDATA manpage together and it's actually so good.

✨ NAME ✨

gd_nframes — report the size of a Dirfile 🦋

🌸 SYNOPSIS 🌸

#include <getdata.h>

off_t gd_nframes(DIRFILE *dirfile);

🎀 DESCRIPTION 🎀

So gd_nframes() looks at a dirfile(5) database — the one you point at with dirfile — and hands you back the number of frames in that database. Slay.

But here's the tea: different fields can totally have different numbers of frames, so the Dirfile Standards (peep dirfile(5)) had to pick a winner. The number of frames in the database is defined to be equal to the number of frames in the reference field, which is the one set by the /REFERENCE directive (that's in dirfile-format(5)). And if no reference field is defined? Then it's whatever the first raw field in the format specification says. periodt.

If literally no vector fields are defined in the database, gd_nframes() returns zero and still succeeds. no drama 💅

Also, the dirfile argument has to point to a valid DIRFILE object that you already made by calling gd_open(3). Like, it has to be real. Don't be passing it nonsense 🙈

🔥 RETURN VALUE 🔥

If everything goes off without a hitch, gd_nframes() returns the number of frames in the dirfile — and it is never negative, iconic. On error though? It returns a negative-valued error code. Here's the whole lineup:

• GD_E_ALLOC — the library couldn't allocate memory. it's giving broke 😭
• GD_E_BAD_DIRFILE — the dirfile you supplied was invalid.
• GD_E_IO — an I/O error happened while figuring out the number of samples in the data file tied to the reference field.
• GD_E_UNKNOWN_ENCODING — couldn't determine how many samples the reference field has, because the encoding used to store that reference field's data file was just... not understood. mystery vibe 💀
• GD_E_UNSUPPORTED — GetData straight up does not support determining the number of samples for the encoding of the data file associated with the reference field.

The error code also gets stashed inside the DIRFILE object, so after this function returns you can go grab it with gd_error(3). And if you want a whole descriptive error string? That's gd_error_string(3), bestie 🫶

📜 HISTORY 📜

• The get_nframes() function appeared in GetData-0.3.0.
• In GeData-0.7.0, this function was renamed to gd_nframes(). (yes it says GeData, that's literally how it's printed, we don't ask questions 🙈)

👑 SEE ALSO 👑

dirfile(5), dirfile-encoding(5), gd_open(3), gd_bof(3), gd_eof(3), gd_error(3), gd_error_string(3)

and that's the whole page, babes. this one's from Version 0.10.0, dated 25 December 2016 — a little vintage, a little festive, still serving. go read your dirfiles, mwah 💖✨🎀