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

       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);

       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:

       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.  See 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).

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_open(3), gd_putdata(3), gd_tell(3)