1gd_include(3) GETDATA gd_include(3)
10
14 gd_include, gd_include_affix, gd_include_ns — add a format specifica‐
15 tion fragment to a Dirfile
16
19 #include <getdata.h>
20 int gd_include(DIRFILE *dirfile, const char *include_file, int
22 parent_fragment, unsigned long flags);
23 int gd_include_affix(DIRFILE *dirfile, const char *include_file, int
25 parent_fragment, const char *prefix, const char *suffix,
26 unsigned long flags);
27 int gd_include_ns(DIRFILE *dirfile, const char *include_file, int
29 parent_fragment, const char *namespace, unsigned long flags);
30
33 The gd_include_affix() function adds the format specification fragment
34 given by the path include_file to the specified dirfile, possibly cre‐
35 ating the fragment, using the affixes specified. This occurs as if, in
36 the existing fragment indexed by parent_fragment, the following direc‐
37 tive were present:
38 /INCLUDE <include_file> <prefix> <suffix>
40 (see dirfile-format(5)). The prefix may include a namespace, separated
42 from the rest of the prefix, which may be the empty string, by a dot
43 (.). If a parser callback function had been specified when the dirfile
44 was opened using gd_cbopen(3), or added later with
45 gd_parser_callback(3), this callback function will be called if a syn‐
46 tax error is encountered while parsing the included fragment.
47 Passing NULL as prefix or suffix is the same as using the empty string
49 (ie. the corresponding affix is empty).
50 The function gd_include() is equivalent to calling gd_include_affix()
52 with both prefix and suffix equal to NULL.
53 The function gd_include_ns() is equivalent to calling
55 gd_include_affix() with suffix equal to NULL and prefix equal to
56 namespace concatenated with a trailing dot.
57 The flags argument should be a bitwise-or'd collection of zero or more
59 of the following flags:
60 GD_ARM_ENDIAN
62 GD_NOT_ARM_ENDIAN
63 Specifies that double precision floating point raw data on disk
64 are, or are not, stored in the middle-endian format used by
65 older ARM processors.
66 These flag only set the default endianness, and will be over‐
68 ridden when an /ENDIAN directive specifies the byte sex of RAW
69 fields, unless GD_FORCE_ENDIAN is also specified.
70 On every platform, one of these flags (GD_NOT_ARM_ENDIAN on all
72 but middle-ended ARM systems) indicates the native behaviour of
73 the platform. That symbol will equal zero, and may be omitted.
74 GD_BIG_ENDIAN
76 GD_LITTLE_ENDIAN
77 Specifies the default byte sex of raw data stored on disk to be
78 either big-endian (most significant byte first) or little-endi‐
79 an (least significant byte first). Omitting both flags indi‐
80 cates the default should be the native endianness of the plat‐
81 form.
82 Unlike the ARM endianness flags above, neither of these symbols
84 is ever zero. Specifying both these flags together will cause
85 the library to assume that the endianness of the data is oppo‐
86 site to that of the native architecture, whatever that might
87 be.
88 These flag only set the default endianness, and will be over‐
90 ridden when an /ENDIAN directive specifies the byte sex of RAW
91 fields, unless GD_FORCE_ENDIAN is also specified.
92 GD_CREAT
94 An empty fragment will be created, if one does not already ex‐
95 ist. The fragment will have mode S_IRUSR | S_IWUSR | S_IRGRP |
96 S_IWGRP | S_IROTH | S_IWOTH (0666), modified by the caller's
97 umask value (see umask(2)).
98 GD_EXCL Ensure that this call creates a new fragment: when specified
100 along with GD_CREAT, the call will fail if the file specified
101 by include_file already exists. If GD_CREAT is not specified,
102 this flag is ignord. This flag suffers from all the limita‐
103 tions of the O_EXCL flag as indicated in open(2).
104 GD_FORCE_ENCODING
106 Specifies that /ENCODING directives (see dirfile-format(5))
107 found in the fragment should be ignored. The encoding scheme
108 specified in flags will be used instead (see below).
109 GD_FORCE_ENDIAN
111 Specifies that /ENDIAN directives (see dirfile-format(5)) found
112 in the fragment should be ignored. When specified with one of
113 GD_BIG_ENDIAN or GD_LITTLE_ENDIAN, the indicated endianness
114 will be assumed. If this flag is specified with neither of
115 those flags, the fragment will be assumed to have the endian‐
116 ness of the native architecture.
117 GD_IGNORE_DUPS
119 If the fragment specifies more than one field with the same
120 name, or a field with the same name as an existing field, all
121 but one of them will be ignored by the parser. Without this
122 flag, parsing would fail with the GD_E_FORMAT error, possibly
123 resulting in invocation of the registered callback function.
124 Which of the duplicate fields is kept is not specified, nor
125 whether an existing field takes precedence over a new one or
126 not. As a result, this flag is typically only useful in the
127 case where identical copies of a field specification line are
128 present.
129 No indication is provided to indicate whether a duplicate field
131 has been discarded. If finer grained control is required, the
132 caller should handle GD_E_FORMAT_DUPLICATE suberrors itself
133 with an appropriate callback function.
134 GD_IGNORE_REFS
136 If the dirfile currently has a reference field (either because
137 one was specified explicitly, or else because the first RAW
138 field was used), /REFERENCE directives in the included fragment
139 will be ignored. Otherwise, a /REFERENCE directive in the in‐
140 cluded fragment will replace the current reference field in the
141 dirfile.
142 GD_PEDANTIC
144 Specifies that unrecognised lines found during the parsing of
145 the fragment should always cause a fatal error. Without this
146 flag, if a VERSION directive (see dirfile-format(5)) indicates
147 that the fragment being opened conforms Standards Version newer
148 than the version understood by the library, unrecognised lines
149 will be silently ignored.
150 GD_TRUNC
152 If include_file already exists, it will be truncated before
153 opening. If the file does not exist, this flag is ignored.
154 The flags argument may also be bitwise or'd with one of the following
157 symbols indicating the default encoding scheme of the fragment. Like
158 the endianness flags, the choice of encoding here is ignored if the en‐
159 coding is specified in the fragment itself, unless GD_FORCE_ENCODED is
160 also specified. If none of these symbols is present, GD_AUTO_ENCODED
161 is assumed, unless this call results in creation or truncation of the
162 fragment. In that case, GD_UNENCODED is assumed. See dirfile-encod‐
163 ing(5) for details on dirfile encoding schemes.
164 GD_AUTO_ENCODED
166 Specifies that the encoding type is not known in advance, but
167 should be detected by the GetData library. Detection is accom‐
168 plished by searching for raw data files with extensions appro‐
169 priate to the encoding scheme. This method will notably fail
170 if the the library is called via gd_putdata(3) to create a pre‐
171 viously non-existent raw field unless a read is first success‐
172 fully performed on the dirfile. Once the library has deter‐
173 mined the encoding scheme for the first time, it remembers it
174 for subsequent calls.
175 GD_BZIP2_ENCODED
177 Specifies that raw data files are compressed using the Burrows-
178 Wheeler block sorting text compression algorithm and Huffman
179 coding, as implemented in the bzip2 format.
180 GD_FLAC_ENCODED
182 Specifies that raw data files are compressed using the Free
183 Lossless Audio Coded (FLAC).
184 GD_GZIP_ENCODED
186 Specifies that raw data files are compressed using Lempel-Ziv
187 coding (LZ77) as implemented in the gzip format.
188 GD_LZMA_ENCODED
190 Specifies that raw data files are compressed using the Lempel-
191 Ziv Markov Chain Algorithm (LZMA) as implemented in the xz con‐
192 tainer format.
193 GD_SIE_ENCODED
195 Specified that raw data files are sample-index encoded, similar
196 to run-length encoding, suitable for data that change rarely.
197 GD_SLIM_ENCODED
199 Specifies that raw data files are compressed using the slimlib
200 library.
201 GD_TEXT_ENCODED
203 Specifies that raw data files are encoded as text files con‐
204 taining one data sample per line.
205 GD_UNENCODED
207 Specifies that raw data files are not encoded, but written ver‐
208 batim to disk.
209 GD_ZZIP_ENCODED
211 Specifies that raw data files are compressed using the DEFLATE
212 algorithm. All raw data files for a given fragment are col‐
213 lected together and stored in a PKZIP archive called raw.zip.
214 GD_ZZSLIM_ENCODED
216 Specifies that raw data files are compressed using a combina‐
217 tions of compression schemes: first files are slim-compressed,
218 as with the GD_SLIM_ENCODED scheme, and then they are collected
219 together and compressed (again) into a PKZIP archive called
220 raw.zip, as in the GD_ZZIP_ENCODED scheme.
221
224 On success, these functions return the format specification index of
225 the newly added fragment. On error, they return a negative-valued er‐
226 ror code. Possible error codes are:
227 GD_E_ACCMODE
229 The supplied dirfile was opened in read-only mode.
230 GD_E_ALLOC
232 The library was unable to allocate memory.
233 GD_E_BAD_DIRFILE
235 The supplied dirfile was invalid.
236 GD_E_BAD_INDEX
238 The supplied parent fragment index was out of range.
239 GD_E_BAD_REFERENCE
241 The reference field specified by a /REFERENCE directive in the
242 fragment (see dirfile-format(5)) was not found, or was not a
243 RAW field. In this case, the included fragment will still be
244 added to the dirfile, but the /REFERENCE directive will be ig‐
245 nored.
246 GD_E_CALLBACK
248 The registered callback function returned an unrecognised re‐
249 sponse.
250 GD_E_FORMAT
252 A syntax error occurred in the fragment.
253 GD_E_LINE_TOO_LONG
255 The parser encountered a line in the format specification
256 longer than it was able to deal with. Lines are limited by the
257 storage size of ssize_t. On 32-bit systems, this limits format
258 specification lines to 2**31 characters. The limit is larger
259 on 64-bit systems.
260 GD_E_IO An I/O error occured while trying to read or create the frag‐
262 ment.
263 GD_E_PROTECTED
265 The metadata of the parent fragment was protected from change.
266 The error code is also stored in the DIRFILE object and may be re‐
268 trieved after this function returns by calling gd_error(3). A descrip‐
269 tive error string for the error may be obtained by calling
270 gd_error_string(3).
271
274 The dirfile_include() function appeared in GetData-0.4.0.
275 In GetData-0.7.0, this function was renamed to gd_include().
277 The gd_include_affix() function appeared in GetData-0.8.0.
279 In GetData-0.10.0, the error return from these functions changed from
281 -1 to a negative-valued error code. The gd_include_ns() function also
282 appeared in this release.
283 See gd_open(3) for history of the flags.
285
288 gd_alter_affixes(3), gd_error(3), gd_error_string(3),
289 gd_fragmentname(3), gd_nfragments(3), gd_open(3),
290 gd_parser_callback(3), gd_reference(3), gd_uninclude(3), dirfile(5),
291 dirfile-encoding(5), dirfile-format(5)
292Version 0.10.0 25 December 2016 gd_include(3)