1gd_seek(3) GETDATA gd_seek(3)
10
14 gd_seek — reposition a Dirfile field pointer
15
18 #include <getdata.h>
19 off_t gd_seek(DIRFILE *dirfile, const char *field_code, off_t
21 frame_num, off_t sample_num, int flags);
22
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 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 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 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 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 is equivalent to:
59 gd_putdata(dirfile, field_code, a, b, c, d, type, data);
61 and, similarly,
63 gd_seek(dirfile, field_code, a, b, GD_SEEK_SET);
65 gd_getdata(dirfile, field_code, GD_HERE, 0, c, d, type, data);
66 is equivalent to:
68 gd_getdata(dirfile, field_code, a, b, c, d, type, data);
70 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
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 GD_E_ALLOC
86 The library was unable to allocate memory.
87 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 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 GD_E_BAD_DIRFILE
97 The supplied dirfile was invalid.
98 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 GD_E_DIMENSION
104 The specified field or one of its inputs wasn't of vector type.
105 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 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 GD_E_IO An error occurred while trying to open or read from a file on
116 disk containing a raw field.
117 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 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 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 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 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
145 The gd_seek() function appeared in GetData-0.8.0.
146 In GetData-0.10.0, the error return from this function changed from -1
148 to a negative-valued error code.
149
152 gd_getdata(3), gd_open(3), gd_putdata(3), gd_tell(3)
153Version 0.10.0 25 December 2016 gd_seek(3)