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

NAME

14       gd_include,  gd_include_affix,  gd_include_ns — add a format specifica‐
15       tion fragment to a Dirfile
16
17

SYNOPSIS

19       #include <getdata.h>
20
21       int gd_include(DIRFILE *dirfile, const char *include_file, int
22              parent_fragment, unsigned long flags);
23
24       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
28       int gd_include_ns(DIRFILE *dirfile, const char *include_file, int
29              parent_fragment, const char *namespace, unsigned long flags);
30
31

DESCRIPTION

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
39              /INCLUDE <include_file> <prefix> <suffix>
40
41       (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
48       Passing  NULL as prefix or suffix is the same as using the empty string
49       (ie. the corresponding affix is empty).
50
51       The function gd_include() is equivalent to  calling  gd_include_affix()
52       with both prefix and suffix equal to NULL.
53
54       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
58       The  flags argument should be a bitwise-or'd collection of zero or more
59       of the following flags:
60
61       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
67               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
71               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
75       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
83               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
89               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
93       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
99       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
105       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
110       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
118       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
130               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
135       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
143       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
151       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
155
156       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
165       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
176       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
181       GD_FLAC_ENCODED
182               Specifies that raw data files are  compressed  using  the  Free
183               Lossless Audio Coded (FLAC).
184
185       GD_GZIP_ENCODED
186               Specifies  that  raw data files are compressed using Lempel-Ziv
187               coding (LZ77) as implemented in the gzip format.
188
189       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
194       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
198       GD_SLIM_ENCODED
199               Specifies  that raw data files are compressed using the slimlib
200               library.
201
202       GD_TEXT_ENCODED
203               Specifies that raw data files are encoded as  text  files  con‐
204               taining one data sample per line.
205
206       GD_UNENCODED
207               Specifies that raw data files are not encoded, but written ver‐
208               batim to disk.
209
210       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
215       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
222

RETURN VALUE

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
228       GD_E_ACCMODE
229               The supplied dirfile was opened in read-only mode.
230
231       GD_E_ALLOC
232               The library was unable to allocate memory.
233
234       GD_E_BAD_DIRFILE
235               The supplied dirfile was invalid.
236
237       GD_E_BAD_INDEX
238               The supplied parent fragment index was out of range.
239
240       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
247       GD_E_CALLBACK
248               The registered callback function returned an  unrecognised  re‐
249               sponse.
250
251       GD_E_FORMAT
252               A syntax error occurred in the fragment.
253
254       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
261       GD_E_IO An  I/O  error occured while trying to read or create the frag‐
262               ment.
263
264       GD_E_PROTECTED
265               The metadata of the parent fragment was protected from change.
266
267       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
272

HISTORY

274       The dirfile_include() function appeared in GetData-0.4.0.
275
276       In GetData-0.7.0, this function was renamed to gd_include().
277
278       The gd_include_affix() function appeared in GetData-0.8.0.
279
280       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
284       See gd_open(3) for history of the flags.
285
286

SEE ALSO

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)
292
293
294
295Version 0.10.0                 25 December 2016                  gd_include(3)
Impressum