--- name: "gd_seek" section: "3" platform: "linux" package: "libgetdata-doc" version: "0.11.0-15" release: "Debian 13 (Trixie)" platforms: ["linux"] url: "https://new.carta.tech/gd_seek" --- # gd\_seek(3) reposition a Dirfile field pointer ## NAME gd\_seek — reposition a Dirfile field pointer ## SYNOPSIS **#include \** **off\_t gd\_seek(DIRFILE \****dirfile***, const char \****field\_code***, off\_t** *frame\_num***, off\_t** *sample\_num***, int** *flags***);** ## DESCRIPTION The **gd\_seek**() function changes the position of the I/O pointer associated with the field *field\_code* in the [dirfile(5)](/dirfile/5.md) 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)](/gd_eof/3.md)). 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)](/gd_putdata/3.md) 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)](/gd_putdata/3.md), while calls before a read via [**gd\_getdata**(3)](/gd_getdata/3.md) 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***);** 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. ## 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. On error, it returns a negative-valued error code. Possible error codes are:\ .TP 8 **GD\_E\_ALLOC** The library was unable to allocate memory.\ .TP 8 **GD\_E\_ARGUMENT** The *flags* parameter didn't contain exactly one of **GD\_SEEK\_SET**, **GD\_SEEK\_CUR**, or **GD\_SEEK\_END**.\ .TP 8 **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.\ .TP 8 **GD\_E\_BAD\_DIRFILE** The supplied dirfile was invalid.\ .TP 8 **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.\ .TP 8 **GD\_E\_DIMENSION** The specified field or one of its inputs wasn't of vector type.\ .TP 8 **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.\ .TP 8 **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.\ .TP 8 **GD\_E\_IO** An error occurred while trying to open or read from a file on disk containing a raw field.\ .TP 8 **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.\ .TP 8 **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.\ .TP 8 **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.\ .TP 8 **GD\_E\_UNSUPPORTED** Reading from dirfiles with the encoding scheme of the specified dirfile is not supported by the library. See [dirfile-encoding(5)](/dirfile-encoding/5.md) 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)](/gd_error/3.md). A descriptive error string for the error may be obtained by calling [**gd\_error\_string**(3)](/gd_error_string/3.md). ## 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. ## SEE ALSO [**gd\_getdata**(3)](/gd_getdata/3.md), [**gd\_open**(3)](/gd_open/3.md), [**gd\_putdata**(3)](/gd_putdata/3.md), [**gd\_tell**(3)](/gd_tell/3.md)