1
2
3
4
5
6
7
8
9gd_seek(3)                          GETDATA                         gd_seek(3)
10
11
12

NAME

14       gd_seek — reposition a Dirfile field pointer
15
16

SYNOPSIS

18       #include <getdata.h>
19
20       off_t gd_seek(DIRFILE *dirfile, const char *field_code, off_t
21              frame_num, off_t sample_num, int flags);
22
23

DESCRIPTION

25       The gd_seek() function changes the position of the I/O pointer  associ‐
26       ated  with the field field_code in the dirfile(5) database specified by
27       dirfile.  In normal operation, gd_seek() advances the field I/O pointer
28       frame_num  frames  plus sample_num samples from the origin point speci‐
29       fied in flags, which should contain one of GD_SEEK_SET, GD_SEEK_CUR, or
30       GD_SEEK_END,  indicating,  respectively, sample zero, the current posi‐
31       tion of the field pointer, and the location of the end-of-field  marker
32       (see gd_eof(3)).
33
34       In  addition to one of the symbols above, the flags parameter may also,
35       optionally, be bitwise or'd with GD_SEEK_WRITE, which  will  result  in
36       the field being padded (with zero for integer types, or a IEEE-754 con‐
37       forming not-a-number otherwise) in the event of seeking past  the  end-
38       of-field marker.
39
40       The effect of attempting to seek past the end-of-field is encoding spe‐
41       cific.  Some encodings don't actually  add  the  padding  requested  by
42       GD_SEEK_WRITE  unless  a  subsequent  gd_putdata(3) call is used to add
43       more data to the field at the new end-of-field.   Other  encodings  add
44       the  padding,  advancing  the  end-of-field,  regardless  of subsequent
45       writes.  Similarly, attempting to seek past the end-of-field marker  in
46       read mode (without specifying GD_SEEK_WRITE) is also encoding specific:
47       in some encodings the field pointer will be moved past the end-of-field
48       marker,  while  in others, it will be repositioned to the end of field.
49       Check the return value to determine the result.
50
51       In general, GD_SEEK_WRITE should be used on gd_seek()  calls  before  a
52       write  via  gd_putdata(3),  while calls before a read via gd_getdata(3)
53       should omit the GD_SEEK_WRITE flag.  So the following:
54
55              gd_seek(dirfile, field_code, a, b, GD_SEEK_SET | GD_SEEK_WRITE);
56              gd_putdata(dirfile, field_code, GD_HERE, 0, c, d, type, data);
57
58       is equivalent to:
59
60              gd_putdata(dirfile, field_code, a, b, c, d, type, data);
61
62       and, similarly,
63
64              gd_seek(dirfile, field_code, a, b, GD_SEEK_SET);
65              gd_getdata(dirfile, field_code, GD_HERE, 0, c, d, type, data);
66
67       is equivalent to:
68
69              gd_getdata(dirfile, field_code, a, b, c, d, type, data);
70
71       Only RAW fields (and the implicit INDEX field) have field I/O  pointers
72       associated  with  them.  Calling gd_seek() on a derived field will move
73       the field pointers of all of the field's inputs.   It  is  possible  to
74       create  derived  fields which simultaneously read from different places
75       of the same input field.  Calling gd_seek() on such a field will result
76       in an error.
77
78

RETURN VALUE

80       Upon  successful  completion,  gd_seek() returns a non-negative integer
81       indicating the I/O position, in samples, of the specified  field  after
82       performing  the  seek.   On  error,  it returns a negative-valued error
83       code.  Possible error codes are:
84
85       GD_E_ALLOC
86               The library was unable to allocate memory.
87
88       GD_E_ARGUMENT
89               The flags parameter didn't contain exactly one of  GD_SEEK_SET,
90               GD_SEEK_CUR, or GD_SEEK_END.
91
92       GD_E_BAD_CODE
93               The field specified by field_code, or one of the fields it uses
94               for input, was not found in the database.
95
96       GD_E_BAD_DIRFILE
97               The supplied dirfile was invalid.
98
99       GD_E_BAD_FIELD_TYPE
100               An attempt was made to seek relative to GD_SEEK_END on the  IN‐
101               DEX field, which has no end-of-field marker.
102
103       GD_E_DIMENSION
104               The specified field or one of its inputs wasn't of vector type.
105
106       GD_E_DOMAIN
107               The field position couldn't be set due to a derived field read‐
108               ing simultaneously from more than one place in a RAW field.
109
110       GD_E_INTERNAL_ERROR
111               An internal error occurred in the library while trying to  per‐
112               form  the  task.   This indicates a bug in the library.  Please
113               report the incident to the maintainer.
114
115       GD_E_IO An error occurred while trying to open or read from a  file  on
116               disk containing a raw field.
117
118       GD_E_RANGE
119               The  request resulted an attempt to move the I/O pointer of the
120               specified field or one of its inputs to a negative sample  num‐
121               ber.
122
123       GD_E_RECURSE_LEVEL
124               Too  many  levels of recursion were encountered while trying to
125               resolve field_code.  This usually indicates a  circular  depen‐
126               dency in field specification in the dirfile.
127
128       GD_E_UNKNOWN_ENCODING
129               The  encoding  scheme  of  a RAW field could not be determined.
130               This may also indicate that the binary file associated with the
131               RAW field could not be found.
132
133       GD_E_UNSUPPORTED
134               Reading from dirfiles with the encoding scheme of the specified
135               dirfile is not supported by the  library.   See  dirfile-encod‐
136               ing(5) for details on dirfile encoding schemes.
137
138       The  error  code  is  also  stored in the DIRFILE object and may be re‐
139       trieved after this function returns by calling gd_error(3).  A descrip‐
140       tive   error   string   for  the  error  may  be  obtained  by  calling
141       gd_error_string(3).
142
143

HISTORY

145       The gd_seek() function appeared in GetData-0.8.0.
146
147       In GetData-0.10.0, the error return from this function changed from  -1
148       to a negative-valued error code.
149
150

SEE ALSO

152       gd_getdata(3), gd_open(3), gd_putdata(3), gd_tell(3)
153
154
155
156Version 0.10.0                 25 December 2016                     gd_seek(3)
Impressum