1dirfile_include(3) GETDATA dirfile_include(3)
2
6 dirfile_include — add a format file fragment to a dirfile
7
9 #include <getdata.h>
10 int dirfile_include(DIRFILE *dirfile, const char *include_file, int
12 parent_fragment, unsigned long flags);
13
15 The dirfile_include() adds the format file fragment specified by the
16 path include_file to the specified dirfile, possibly creating the frag‐
17 ment. This occurs as if, in the existing fragment indexed by par‐
18 ent_fragment, the following directive were present:
19 /INCLUDE <include_file>
21 (see dirfile-format(5)). If a parser callback function had been speci‐
23 fied when the dirfile was opened using dirfile_cbopen(3), or added lat‐
24 er with dirfile_parser_callback(3), this callback function will be
25 called if a syntax error is encountered while parsing the included
26 fragment.
27 The flags argument should be a bitwise-or'd collection of the following
29 flags, or zero if no flags are desired:
30 GD_BIG_ENDIAN
32 Specifies that raw data on disk is stored as big-endian data
33 (most significant byte first). Specifying this flag along with
34 the contradictory GD_LITTLE_ENDIAN will cause the library to as‐
35 sume that the endianness of the data is opposite to that of the
36 native architecture.
37 This flag is ignored completely if an ENDIAN directive occurs in
39 the fragment, unless GD_FORCE_ENDIAN is also specified.
40 GD_CREAT
42 An empty fragment will be created, if one does not already ex‐
43 ist. The fragment will have mode S_IRUSR | S_IWUSR | S_IRGRP |
44 S_IWGRP | S_IROTH | S_IWOTH (0666), modified by the caller's
45 umask value (see umask(2)).
46 GD_EXCL
48 Ensure that this call creates a new fragment: when specified
49 along with GD_CREAT, the call will fail if the file specified by
50 include_file already exists. Behaviour of this flag is unde‐
51 fined if GD_CREAT is not specified. This flag suffers from all
52 the limitations of the O_EXCL flag as indicated in open(2).
53 GD_FORCE_ENCODING
55 Specifies that ENCODING directives (see dirfile-format(5)) found
56 in the fragment should be ignored. The encoding scheme speci‐
57 fied in flags will be used instead (see below).
58 GD_FORCE_ENDIAN
60 Specifies that ENDIAN directives (see dirfile-format(5)) found
61 in the fragment should be ignored. When specified with one of
62 GD_BIG_ENDIAN or GD_LITTLE_ENDIAN, the endianness specified will
63 be assumed. If this flag is specified with neither of those
64 flags, the fragment will be assumed to have the endianness of
65 the native architecture.
66 GD_IGNORE_DUPS
68 If the fragment specifies more than one field with the same
69 name, or a field with the same name as an existing field, all
70 but one of them will be ignored by the parser. Without this
71 flag, parsing would fail with the GD_E_FORMAT error, possibly
72 resulting in invocation of the registered callback function.
73 Which of the duplicate fields is kept is not specified, nor
74 whether an existing field takes precedence over a new one or
75 not. As a result, this flag is typically only useful in the
76 case where identical copies of a field specification line are
77 present.
78 No indication is provided to indicate whether a duplicate field
80 has been discarded. If finer grained control is required, the
81 caller should handle GD_E_FORMAT_DUPLICATE suberrors itself with
82 an appropriate callback function.
83 GD_IGNORE_REFS
85 If the dirfile currently has a reference field (either because
86 one was specified explicitly, or else because the first RAW
87 field was used), /REFERENCE directives in the included fragment
88 will be ignored. Otherwise, a /REFERENCE directive in the in‐
89 cluded fragment will replace the current reference field in the
90 dirfile.
91 GD_LITTLE_ENDIAN
93 Specifies that raw data on disk is stored as little-endian data
94 (least significant byte first). Specifying this flag along with
95 the contradictory GD_BIG_ENDIAN will cause the library to assume
96 that the endianness of the data is opposite to that of the na‐
97 tive architecture.
98 This flag is ignored completely if an ENDIAN directive occurs in
100 the fragment, unless GD_FORCE_ENDIAN is also specified.
101 GD_PEDANTIC
103 Specifies that unrecognised lines found during the parsing of
104 the fragment should always cause a fatal error. Without this
105 flag, if a VERSION directive (see dirfile-format(5)) indicates
106 that the fragment being opened conforms Standards Version newer
107 than the version understood by the library, unrecognised lines
108 will be silently ignored.
109 GD_TRUNC
111 If include_file already exists, it will be truncated before
112 opening. If the file does not exist, this flag is ignored.
113 The flags argument may also be bitwise or'd with one of the following
116 symbols indicating the default encoding scheme of the fragment. Like
117 the endianness flags, the choice of encoding here is ignored if the en‐
118 coding is specified in the fragment itself, unless GD_FORCE_ENCODED is
119 also specified. If none of these symbols is present, GD_AUTO_ENCODED
120 is assumed, unless the dirfile_include() call results in creation or
121 truncation of the fragment. In that case, GD_UNENCODED is assumed.
122 See dirfile-encoding(5) for details on dirfile encoding schemes.
123 GD_AUTO_ENCODED
125 Specifies that the encoding type is not known in advance, but
126 should be detected by the GetData library. Detection is accom‐
127 plished by searching for raw data files with extensions appro‐
128 priate to the encoding scheme. This method will notably fail if
129 the the library is called via putdata(3) to create a previously
130 non-existent raw field unless a read is first successfully per‐
131 formed on the dirfile. Once the library has determined the en‐
132 coding scheme for the first time, it remembers it for subsequent
133 calls.
134 GD_BZIP2_ENDODED
136 Specifies that raw data files are compressed using the Burrows-
137 Wheeler block sorting text compression algorithm and Huffman
138 coding, as implemented in the bzip2 format.
139 GD_GZIP_ENDODED
141 Specifies that raw data files are compressed using Lempel-Ziv
142 coding (LZ77) as implemented in the gzip format.
143 GD_LZMA_ENDODED
145 Specifies that raw data files are compressed using the Lempel-
146 Ziv Markov Chain Algorithm (LZMA) as implemented in the xz con‐
147 tainer format.
148 GD_SLIM_ENCODED
150 Specifies that raw data files are compressed using the slimlib
151 library.
152 GD_TEXT_ENCODED
154 Specifies that raw data files are encoded as text files contain‐
155 ing one data sample per line.
156 GD_UNENCODED
158 Specifies that raw data files are not encoded, but written ver‐
159 batim to disk.
160
163 On success, dirfile_include() returns the format file index of the new‐
164 ly added fragment. On error, -1 is returned and the dirfile error is
165 set to a non-zero error value. Possible error values are:
166 GD_E_ACCMODE
168 The supplied dirfile was opened in read-only mode.
169 GD_E_ALLOC
171 The library was unable to allocate memory.
172 GD_E_BAD_DIRFILE
174 The supplied dirfile was invalid.
175 GD_E_BAD_INDEX
177 The supplied parent fragment index was out of range.
178 GD_E_BAD_REFERENCE
180 The reference field specified by a /REFERENCE directive in the
181 fragment (see dirfile-format(5)) was not found, or was not a
182 RAW field.
183 GD_E_CALLBACK
185 The registered callback function returned an unrecognised re‐
186 sponse.
187 GD_E_FORMAT
189 A syntax error occurred in the fragment.
190 GD_E_INTERNAL_ERROR
192 An internal error occurred in the library while trying to per‐
193 form the task. This indicates a bug in the library. Please
194 report the incident to the maintainer.
195 GD_E_OPEN_INCLUDE
197 The fragment could not be opened or created.
198 GD_E_PROTECTED
200 The metadata of the parent fragment was protected from change.
201 GD_E_REFERENCE
203 The included fragment contained a /REFERENCE directive which
204 referred to a non-existent field, or a field that was not of
205 type RAW. In this case, the included fragment will still be
206 added to the dirfile, but the /REFERENCE directive will be ig‐
207 nored. See also the BUGS section below.
208 The dirfile error may be retrieved by calling get_error(3). A descrip‐
210 tive error string for the last error encountered can be obtained from a
211 call to get_error_string(3). When finished with it, the DIRFILE object
212 may be deallocated with a call to dirfile_close(3), even if the open
213 failed.
214
216 If this function fails with the error GD_E_REFERENCE, it typically re‐
217 sults in no reference field being defined for the dirfile, even if the
218 dirfile contains RAW fields. As a result, functions which rely on the
219 reference field, such as get_nframes(3), will operate incorrectly.
220 Callers should explicitly set the reference field with dirfile_refer‐
221 ence(3) in this case.
222
224 dirfile_open(3), dirfile_parser_callback(3), dirfile_reference(3),
225 dirfile_uninclude(3), get_error(3), get_error_string(3), get_fragment‐
226 name(3), get_nfragments(3), dirfile(5), dirfile-encoding(5), dirfile-
227 format(5)
228Version 0.6.0 16 October 2009 dirfile_include(3)