table of contents
other versions
- wheezy 0.7.3-6
- jessie 0.7.3-6+b2
- testing 0.9.4-1
- unstable 0.9.4-1
- experimental 0.10.0-1
gd_include(3) | GETDATA | gd_include(3) |
NAME¶
gd_include — add a format specification fragment to a dirfileSYNOPSIS¶
#include <getdata.h>int
gd_include(DIRFILE *dirfile, const char
*include_file, int parent_fragment,
unsigned long flags);
DESCRIPTION¶
The gd_include() adds the format specification fragment given by the path include_file to the specified dirfile, possibly creating the fragment. This occurs as if, in the existing fragment indexed by parent_fragment, the following directive were present:- /INCLUDE <include_file>
- GD_BIG_ENDIAN
- Specifies that raw data on disk is stored as big-endian
data (most significant byte first). Specifying this flag along with the
contradictory GD_LITTLE_ENDIAN will cause the library to assume
that the endianness of the data is opposite to that of the native
architecture.
- GD_CREAT
- An empty fragment will be created, if one does not already exist. The fragment will have mode S_IRUSR | S_IWUSR | S_IRGRP | S_IWGRP | S_IROTH | S_IWOTH (0666), modified by the caller's umask value (see umask(2)).
- GD_EXCL
- Ensure that this call creates a new fragment: when specified along with GD_CREAT, the call will fail if the file specified by include_file already exists. Behaviour of this flag is undefined if GD_CREAT is not specified. This flag suffers from all the limitations of the O_EXCL flag as indicated in open(2).
- GD_FORCE_ENCODING
- Specifies that ENCODING directives (see dirfile-format(5)) found in the fragment should be ignored. The encoding scheme specified in flags will be used instead (see below).
- GD_FORCE_ENDIAN
- Specifies that ENDIAN directives (see dirfile-format(5)) found in the fragment should be ignored. When specified with one of GD_BIG_ENDIAN or GD_LITTLE_ENDIAN, the indicated endianness will be assumed. If this flag is specified with neither of those flags, the fragment will be assumed to have the endianness of the native architecture.
- GD_IGNORE_DUPS
- If the fragment specifies more than one field with the same
name, or a field with the same name as an existing field, all but one of
them will be ignored by the parser. Without this flag, parsing would fail
with the GD_E_FORMAT error, possibly resulting in invocation of the
registered callback function. Which of the duplicate fields is kept is not
specified, nor whether an existing field takes precedence over a new one
or not. As a result, this flag is typically only useful in the case where
identical copies of a field specification line are present.
- GD_IGNORE_REFS
- If the dirfile currently has a reference field (either because one was specified explicitly, or else because the first RAW field was used), /REFERENCE directives in the included fragment will be ignored. Otherwise, a /REFERENCE directive in the included fragment will replace the current reference field in the dirfile.
- GD_LITTLE_ENDIAN
- Specifies that raw data on disk is stored as little-endian
data (least significant byte first). Specifying this flag along with the
contradictory GD_BIG_ENDIAN will cause the library to assume that
the endianness of the data is opposite to that of the native architecture.
- GD_PEDANTIC
- Specifies that unrecognised lines found during the parsing of the fragment should always cause a fatal error. Without this flag, if a VERSION directive (see dirfile-format(5)) indicates that the fragment being opened conforms Standards Version newer than the version understood by the library, unrecognised lines will be silently ignored.
- GD_TRUNC
- If include_file already exists, it will be truncated
before opening. If the file does not exist, this flag is ignored.
- GD_AUTO_ENCODED
- Specifies that the encoding type is not known in advance, but should be detected by the GetData library. Detection is accomplished by searching for raw data files with extensions appropriate to the encoding scheme. This method will notably fail if the the library is called via putdata(3) to create a previously non-existent raw field unless a read is first successfully performed on the dirfile. Once the library has determined the encoding scheme for the first time, it remembers it for subsequent calls.
- GD_BZIP2_ENDODED
- Specifies that raw data files are compressed using the Burrows-Wheeler block sorting text compression algorithm and Huffman coding, as implemented in the bzip2 format.
- GD_GZIP_ENDODED
- Specifies that raw data files are compressed using Lempel-Ziv coding (LZ77) as implemented in the gzip format.
- GD_LZMA_ENDODED
- Specifies that raw data files are compressed using the Lempel-Ziv Markov Chain Algorithm (LZMA) as implemented in the xz container format.
- GD_SLIM_ENCODED
- Specifies that raw data files are compressed using the slimlib library.
- GD_TEXT_ENCODED
- Specifies that raw data files are encoded as text files containing one data sample per line.
- GD_UNENCODED
- Specifies that raw data files are not encoded, but written
verbatim to disk.
RETURN VALUE¶
On success, gd_include() returns the format specification index of the newly added fragment. On error, -1 is returned and the dirfile error is set to a non-zero error value. Possible error values are:- GD_E_ACCMODE
- The supplied dirfile was opened in read-only mode.
- GD_E_ALLOC
- The library was unable to allocate memory.
- GD_E_BAD_DIRFILE
- The supplied dirfile was invalid.
- GD_E_BAD_INDEX
- The supplied parent fragment index was out of range.
- GD_E_BAD_REFERENCE
- The reference field specified by a /REFERENCE directive in the fragment (see dirfile-format(5)) was not found, or was not a RAW field.
- GD_E_CALLBACK
- The registered callback function returned an unrecognised response.
- GD_E_FORMAT
- A syntax error occurred in the fragment.
- GD_E_INTERNAL_ERROR
- An internal error occurred in the library while trying to perform the task. This indicates a bug in the library. Please report the incident to the maintainer.
- GD_E_LINE_TOO_LONG
- The parser encountered a line in the format specification longer than it was able to deal with. Lines are limited by the storage size of ssize_t. On 32-bit systems, this limits format specification lines to 2**31 characters. The limit is larger on 64-bit systems.
- GD_E_OPEN_FRAGMENT
- The fragment could not be opened or created.
- GD_E_PROTECTED
- The metadata of the parent fragment was protected from change.
- GD_E_REFERENCE
- The included fragment contained a /REFERENCE directive which referred to a non-existent field, or a field that was not of type RAW. In this case, the included fragment will still be added to the dirfile, but the /REFERENCE directive will be ignored. See also the BUGS section below.
BUGS¶
If this function fails with the error GD_E_REFERENCE, it typically results in no reference field being defined for the dirfile, even if the dirfile contains RAW fields. As a result, functions which rely on the reference field, such as gd_nframes(3), will operate incorrectly. Callers should explicitly set the reference field with gd_reference(3) in this case.SEE ALSO¶
gd_open(3), gd_parser_callback(3), gd_reference(3), gd_uninclude(3), gd_error(3), gd_error_string(3), gd_fragmentname(3), gd_nfragments(3), dirfile(5), dirfile-encoding(5), dirfile-format(5)3 November 2010 | Version 0.7.0 |