gd_bof(3)

💖 gd_bof — find the start of data in a Dirfile field 💖

okay bestie, welcome to the gd_bof(3) page from the GETDATA manual ✨ this one's short and sweet and it's literally just "where does my data start", let's go 🫶

✨ NAME ✨

gd_bof — find the start of data in a Dirfile field 🌸

✨ SYNOPSIS ✨

#include <getdata.h>

off_t gd_bof(DIRFILE *dirfile, const char *field_code);

✨ DESCRIPTION ✨

so the gd_bof() function goes poking around a dirfile(5) database (the one you hand it as dirfile) and hunts down the beginning-of-field marker for the vector field you named in field_code. that's it, that's the whole job 💅

⚠️ heads up bestie: do not assume the beginning-of-field marker lands on a frame boundary. it just doesn't, okay? and also — it is never negative. periodt. 🎀

now the deets, field by field, no cap:

• for a RAW field, the beginning-of-field lines up with that field's frame offset (go peek at gd_frameoffset(3) for that one) 🦋
• for the special field INDEX, the beginning-of-field marker is just zero. iconic, honestly ✨
• for a PHASE field, it's the beginning-of-field of its input, shifted by that PHASE field's shift — or zero, if the shift would drag it into the negative 😭 (we don't do negative here)
• for every other vector field? it's the latest beginning-of-field of any of its input fields. the vibes are "whichever input starts last, that's our start" 💜

if a field's beginning-of-field marker is greater than or equal to its end-of-field marker (hi, that's gd_eof(3)), then that field has no data in it. empty. nothing. 💀 and for a RAW field specifically, the difference between the beginning- and end-of-field marker locations tells you how many samples of data are actually sitting on disk. fr fr 📀

one more thing: the dirfile argument has to point to a valid DIRFILE object that you already made by calling gd_open(3). no random pointers, we're not doing that 🙈

✨ RETURN VALUE ✨

when everything slays, gd_bof() hands you back a non-negative integer — that's the sample number of the beginning-of-field marker for your field 👑

and when it doesn't slay? it returns a negative-valued error code. here's the whole roster of possible ones:

• GD_E_BAD_CODE — the field you named in field_code, or one of the fields it uses as input, was simply not found in the database. it's not there bestie 😭
• GD_E_BAD_DIRFILE — the dirfile you gave it was invalid. not it. 🚫
• GD_E_DIMENSION — a scalar field showed up where a vector field was expected, either in the definition of field_code or in one of its inputs — or else field_code itself was specifying a scalar field. wrong shape, wrong energy 💀
• GD_E_INTERNAL_ERROR — something internal went sideways in the library while it was trying to do the thing. this one means there's a bug in the library, so please report the incident to the GetData developers! 🙏
• GD_E_RECURSE_LEVEL — too many levels of recursion got hit while trying to resolve field_code. this usually means there's a circular dependency in your field specification in the dirfile. you looped yourself 🌀

oh and also — the error code gets stashed in the DIRFILE object too 💾, so after this function returns you can grab it by calling gd_error(3). and if you want an actual human-readable description of what went wrong, call gd_error_string(3) and it'll tell you 🌈

✨ HISTORY ✨

• gd_bof() first showed up in GetData-0.7.0 🎉
• before GetData-0.10.0, this function could also fail with the error code GD_E_ALLOC. (rip to that era, we don't do that anymore 🪦)
• in GetData-0.10.0, the error return from this function changed from -1 to a negative-valued error code. glow-up behavior 💅

✨ SEE ALSO ✨

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

and that's the page bestie!! Version 0.10.0, dated 25 December 2016 — go find the start of your data, you've got this 💖✨🎀🫶