gd_eof(3)

💖 gd_eof — bestie, let's find the end of a Dirfile field 💖

okay so this is gd_eof(3), living in the GETDATA manual section, and it's literally the "where does this field end??" function. come sit with me 🫶

✨ SYNOPSIS ✨

#include <getdata.h>

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

🌸 DESCRIPTION 🌸

so gd_eof() goes and interrogates a dirfile(5) database — the one you hand it as dirfile — and figures out the sample number of the end-of-field marker for the vector field named by field_code. and like, that's basically the total number of samples available for that field, frame offset included. iconic.

but bestie, hear me: do not assume that this equals the number of frames in the database from gd_nframes(3) — even after you account for the samples-per-frame of the field in question. and do not assume the end-of-field marker lands on a frame boundary either. it's giving ✨free spirit✨.

here's the tea on how each field type behaves:

• for a RAW field, the end-of-field marker happens immediately after the last datum in the data file associated with the field.
• the special field INDEX has no end-of-field marker. none. zero. nada. 💀
• for a PHASE field, its end-of-field is the end-of-field of its input, adjusted by the PHASE field's shift.
• for all the other vector field types, the end-of-field marker is the smallest end-of-field marker among any of its inputs.

now — if a field's end-of-field marker is less than or equal to its beginning-of-field marker (peep gd_bof(3) for that one), then that field has no data. for a RAW field specifically, the difference between the beginning- and end-of-field markers tells you how many samples of data are actually stored on disk. math ate, honestly.

and the dirfile argument? it must point to a valid DIRFILE object that was previously created by a call to gd_open(3). no imposters. 🙈

💅 RETURN VALUE 💅

on a successful run, gd_eof() returns the sample number of the end-of-field marker for the indicated field, and ngl it is never negative. on error, it returns a negative-valued error code. possible error codes, let's go:

• GD_E_ALLOC — the library couldn't allocate memory. 😭
• GD_E_BAD_CODE — the field specified by field_code, or one of the fields it uses as input, was not found in the database.
• GD_E_BAD_DIRFILE — the supplied dirfile was invalid.
• GD_E_BAD_FIELD_TYPE — someone requested the location of the non-existent end-of-field marker for the special field INDEX — possibly because the field specified by field_code uses INDEX as one of its inputs. it's not there bestie, it never was.
• GD_E_DIMENSION — a scalar field showed up where a vector field was expected, in the definition of field_code or one of its inputs — or else field_code itself specified a scalar field.
• GD_E_INTERNAL_ERROR — an internal error happened in the library while trying to perform the task. this indicates a bug in the library. please report the incident to the GetData developers! 🐛
• GD_E_IO — an I/O error occurred while determining the size of the raw data file associated with the field, or one of its input fields.
• GD_E_RECURSE_LEVEL — too many levels of recursion were encountered while trying to resolve field_code. this usually means there's a circular dependency in the field specification in the dirfile. 🌀
• GD_E_UNKNOWN_ENCODING — the size of the decoded data file associated with the specified field or one of its inputs could not be determined, because its encoding scheme was not understood.
• GD_E_UNSUPPORTED — the size of the decoded data file associated with the specified field or one of its inputs could not be determined, because its encoding scheme was not supported.

the error code is also stashed in the DIRFILE object, and you can grab it after this function returns by calling gd_error(3). want a descriptive error string? that's gd_error_string(3). 💖

🦋 HISTORY 🦋

• gd_eof() appeared in GetData-0.7.0. a legend was born.
• in GetData-0.10.0, the error return from this function changed from -1 to a negative-valued error code. glow-up fr fr.

🌈 SEE ALSO 🌈

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

and that's the whole page, bestie!! this was Version 0.10.0, dated 25 December 2016, and you can find it in the gd_eof(3) entry of the GETDATA manual. go forth and find your end-of-field markers, you absolute main character 👑✨🎀