gd_seek(3)

🦋 gd_seek — reposition a Dirfile field pointer 🦋

okay bestie, welcome to the GETDATA manual, page gd_seek(3). this is the one where we move a field's I/O pointer around like it's a lil cursor in a group chat. it's giving "where exactly are we reading from" energy and honestly? iconic. 💅

---

✨ NAME ✨

gd_seek — reposition a Dirfile field pointer 🎯

---

🌸 SYNOPSIS 🌸

#include <getdata.h>

off_t gd_seek(DIRFILE *dirfile, const char *field_code, off_t frame_num,
       off_t sample_num, int flags);

---

💜 DESCRIPTION 💜

so the gd_seek() function moves the position of the I/O pointer that's hanging out with the field field_code inside the dirfile(5) database you passed as dirfile. no cap, that's the whole job. 🫶

in normal operation, gd_seek() advances that field I/O pointer frame_num frames plus sample_num samples away from the origin point you picked in flags. and flags should contain exactly one of GD_SEEK_SET, GD_SEEK_CUR, or GD_SEEK_END, which mean, respectively:

• GD_SEEK_SET — sample zero, the very beginning, the origin story ✨
• GD_SEEK_CUR — wherever the field pointer is currently vibing
• GD_SEEK_END — the location of the end-of-field marker (peep gd_eof(3) for that one) 🏁

and on top of one of those symbols, flags can also, optionally, be bitwise or'd with GD_SEEK_WRITE. what does that do? it makes the field get padded if you seek past the end-of-field marker — padded with zero for integer types, or with an IEEE-754 conforming not-a-number otherwise. yes, NaN padding, she's dramatic but she's valid. 😌

---

🎀 the "past the end" tea 🎀

the effect of trying to seek past the end-of-field is encoding specific, and we do not make the rules here. some encodings don't actually add the padding you asked for with GD_SEEK_WRITE unless a subsequent gd_putdata(3) call comes along and adds more data to the field at the new end-of-field. other encodings add the padding right away, advancing the end-of-field, regardless of any subsequent writes. both are valid, both are real. 🙈

similarly, trying to seek past the end-of-field marker in read mode (so, without specifying GD_SEEK_WRITE) is also encoding specific: in some encodings the field pointer gets moved past the end-of-field marker, while in others it gets repositioned to the end of field. so like... check the return value to figure out which one you got, okay? fr fr.

---

🧚 the general rule (iykyk) 🧚

in general, GD_SEEK_WRITE should be used on gd_seek() calls before a write via gd_putdata(3), while calls before a read via gd_getdata(3) should omit the GD_SEEK_WRITE flag. so the following:

gd_seek(dirfile, field_code, a, b, GD_SEEK_SET | GD_SEEK_WRITE);
gd_putdata(dirfile, field_code, GD_HERE, 0, c, d, type, data);

is equivalent to:

gd_putdata(dirfile, field_code, a, b, c, d, type, data);

and, similarly,

gd_seek(dirfile, field_code, a, b, GD_SEEK_SET);
gd_getdata(dirfile, field_code, GD_HERE, 0, c, d, type, data);

is equivalent to:

gd_getdata(dirfile, field_code, a, b, c, d, type, data);

like. the math is mathing. 📐✨

---

💀 who actually has a field I/O pointer 💀

plot twist: only RAW fields (and the implicit INDEX field) have field I/O pointers associated with them. that's it. that's the list.

so if you call gd_seek() on a derived field, it'll move the field pointers of all of the field's inputs. cute, right?

but — and hear me out — it's possible to create derived fields which simultaneously read from different places of the same input field. calling gd_seek() on such a field will result in an error. no pointer-moving for you. 🚫

---

🌈 RETURN VALUE 🌈

upon successful completion, gd_seek() returns a non-negative integer indicating the I/O position, in samples, of the specified field after performing the seek. yay! 🎉

on error, it returns a negative-valued error code. possible error codes are:

😭 GD_E_ALLOC

the library was unable to allocate memory.

😭 GD_E_ARGUMENT

the flags parameter didn't contain exactly one of GD_SEEK_SET, GD_SEEK_CUR, or GD_SEEK_END.

😭 GD_E_BAD_CODE

the field specified by field_code, or one of the fields it uses for input, was not found in the database.

😭 GD_E_BAD_DIRFILE

the supplied dirfile was invalid.

😭 GD_E_BAD_FIELD_TYPE

an attempt was made to seek relative to GD_SEEK_END on the INDEX field, which has no end-of-field marker.

😭 GD_E_DIMENSION

the specified field or one of its inputs wasn't of vector type.

😭 GD_E_DOMAIN

the field position couldn't be set due to a derived field reading simultaneously from more than one place in a RAW field.

😭 GD_E_INTERNAL_ERROR

an internal error occurred in the library while trying to perform the task. this indicates a bug in the library. please report the incident to the maintainer. 🙏

😭 GD_E_IO

an error occurred while trying to open or read from a file on disk containing a raw field.

😭 GD_E_RANGE

the request resulted an attempt to move the I/O pointer of the specified field or one of its inputs to a negative sample number.

😭 GD_E_RECURSE_LEVEL

too many levels of recursion were encountered while trying to resolve field_code. this usually indicates a circular dependency in field specification in the dirfile. 🔁

😭 GD_E_UNKNOWN_ENCODING

the encoding scheme of a RAW field could not be determined. this may also indicate that the binary file associated with the RAW field could not 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 details on dirfile encoding schemes.

---

the error code is also stored in the DIRFILE object and may be retrieved after this function returns by calling gd_error(3). a descriptive error string for the error may be obtained by calling gd_error_string(3). so you're never left on read about what went wrong. 💖

---

📜 HISTORY 📜

the gd_seek() function appeared in GetData-0.8.0.

in GetData-0.10.0, the error return from this function changed from -1 to a negative-valued error code. glow-up behavior, honestly. 💅

---

👀 SEE ALSO 👀

• gd_getdata(3)
• gd_open(3)
• gd_putdata(3)
• gd_tell(3)

---

Version 0.10.0 · 25 December 2016 — and that's the whole page bestie, gd_seek(3) out. go forth and reposition your pointers responsibly. 🫶✨🎀