plucky (3) gd_seek.3.gz

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)