gd_seek—reposition a Dirfile field pointer
off_t gd_seek(DIRFILE *dirfile, const char *field_code, off_t frame_num, off_t sample_num, int flags);
The gd_seek() function changes the position of the I/O pointer associated with the field field_code in the dirfile(5) database specified by dirfile. In normal operation, gd_seek() advances the field I/O pointer frame_num frames plus sample_num samples from the origin point specified in flags, which should contain one of GD_SEEK_SET, GD_SEEK_CUR, or GD_SEEK_END, indicating, respectively, sample zero, the current position of the field pointer, and the location of the end-of-field marker (see gd_eof(3)).
In addition to one of the symbols above, the flags parameter may also, optionally, be bitwise or'd with GD_SEEK_WRITE, which will result in the field being padded (with zero for integer types, or a IEEE-754 conforming not-a-number otherwise) in the event of seeking past the end-of-field marker.
The effect of attempting to seek past the end-of-field is encoding specific. Some encodings don't actually add the padding requested by GD_SEEK_WRITE unless a subsequent gd_putdata(3) call is used to add more data to the field at the new end-of-field. Other encodings add the padding, advancing the end-of-field, regardless of subsequent writes. Similarly, attempting to seek past the end-of-field marker in read mode (without specifying GD_SEEK_WRITE) is also encoding specific: in some encodings the field pointer will be moved past the end-of-field marker, while in others, it will be repositioned to the end of field. Check the return value to determine the result.
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);
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);
Only RAW fields (and the implicit INDEX field) have field I/O pointers associated with them. Calling gd_seek() on a derived field will move the field pointers of all of the field's inputs. It is 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.
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. On error, it returns a negative-valued error code. Possible error codes are:
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).
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.
gd_getdata(3), gd_open(3), gd_putdata(3), gd_tell(3)