gd_seek(3) GETDATA gd_seek(3)NAMEgd_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
The gd_seek() function changes the position of the I/O pointer associ‐
ated 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 speci‐
fied in flags, which should contain one of GD_SEEK_SET, GD_SEEK_CUR, or
GD_SEEK_END, indicating, respectively, sample zero, the current posi‐
tion 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 con‐
forming not-a-number otherwise) in the event of seeking past the end-
of-field marker. Note: for some data encodings, the padding may be de‐
ferred until a write occurs. The result of calling gd_seek() with
GD_SEEK_WRITE, but without a subsequent call to gd_putdata(3), is en‐
coding specific, and may not actually advance the end of field. At‐
tempting to seek past the end-of-field marker 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 result in an error.
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);
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 the field position of the
specified field in samples. On error, it returns -1 and set the
dirfile error to a non-zero value. Possible error values 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_BAD_REPR
The representation suffix specified in field_code, or in one of
the field codes it uses for input, was invalid.
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 an input
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_RAW_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. See dirfile-
encoding(5) for details on dirfile encoding schemes.
The dirfile error may be retrieved by calling gd_error(3). A
descriptive error string for the last error encountered can be obtained
from a call to gd_error_string(3).
SEE ALSOgd_open(3), gd_getdata(3), gd_putdata(3), gd_tell(3).
Version 0.8.4 12 March 2013 gd_seek(3)