gd_tell(3)

💖 gd_tell — GETDATA manual, but make it cute 💖

okay bestie, so gd_tell(3) — it's a whole GetData thing. Let's get into it. 🎀

✨ NAME ✨

gd_tell — reports where the I/O pointer of a Dirfile field is currently vibing 🫶

✨ SYNOPSIS ✨

#include <getdata.h>

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

✨ DESCRIPTION ✨

So like, gd_tell() tells you the current position of the I/O pointer of the field field_code, inside the dirfile(5) database that you passed in as dirfile. That's it, that's the whole job. 💅

Now here's the tea, and it's important: only RAW fields (and the implicit INDEX field) have field pointers attached to them. That's it. That's the list.

So what happens if you call gd_tell() on a derived field? Okay so it'll only report the derived field's I/O pointer position if all of its inputs are positioned the same. Like, all of them. In agreement. No drama. Otherwise? error. Straight up. 😭

✨ RETURN VALUE ✨

Slay, so on a good day, gd_tell() returns a non-negative integer — that's the I/O position of your specified field, measured in samples. ✨

On a bad day, it returns a negative-valued error code. And here's the full roster of possible error codes, no cap:

• GD_E_ALLOC — the library couldn't allocate memory. it's giving out-of-ram energy 💀
• GD_E_BAD_CODE — the field you named in field_code, or one of the fields it pulls in as input, was not found in the database. 🕵️‍♀️
• GD_E_BAD_DIRFILE — the dirfile you handed over was invalid. 🙈
• GD_E_DIMENSION — the field you specified, or one of its inputs, wasn't of vector type.
• GD_E_DOMAIN — the I/O position of a derived field wasn't well defined, because its input fields were simultaneously reading from different places in the same RAW field. messy. 😵‍💫
• GD_E_INTERNAL_ERROR — an internal error popped off in the library while trying to do the task. This one indicates a bug in the library. Please report the incident to the maintainer, fr fr. 🐛
• GD_E_IO — an error occurred while trying to open or read from a file on disk containing a raw field.
• 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. 🔄 (iykyk)
• GD_E_UNKNOWN_ENCODING — the encoding scheme of a RAW field could not be determined. This may also mean the binary file associated with that RAW field couldn't be found. 🫠
• GD_E_UNSUPPORTED — reading from dirfiles with the encoding scheme of the specified dirfile is not supported by the library. Peep dirfile-encoding(5) for the details on dirfile encoding schemes. 👑

Also, bestie, heads up: the error code is also stored in the DIRFILE object, so you can grab it after this function returns by calling gd_error(3). And if you want a whole descriptive error string, call gd_error_string(3). 💖

✨ HISTORY ✨

• gd_tell() first appeared in GetData-0.8.0. iconic debut, honestly. ✨
• In GetData-0.10.0, the error return from this function changed from -1 to a negative-valued error code. glow-up moment. 💅

✨ SEE ALSO ✨

gd_getdata(3), gd_open(3), gd_putdata(3), gd_seek(3). go read those too, they're all part of the same friend group 🫶

k bye bestie, that's the whole page — this was Version 0.10.0, dated 25 December 2016, and it's the gd_tell(3) GetData manual. mwah 💋🌸