gd_include, gd_include_affix, gd_include_ns — add a format
specification fragment to a Dirfile
#include <getdata.h>
int gd_include(DIRFILE *dirfile, const char
*include_file, int parent_fragment,
unsigned long flags);
int gd_include_affix(DIRFILE *dirfile, const
char *include_file, int parent_fragment,
const char *prefix, const char *suffix,
unsigned long flags);
int gd_include_ns(DIRFILE *dirfile, const char
*include_file, int parent_fragment, const
char *namespace, unsigned long
flags);
The gd_include_affix() function adds the format
specification fragment given by the path include_file to the
specified dirfile, possibly creating the fragment, using the affixes
specified. This occurs as if, in the existing fragment indexed by
parent_fragment, the following directive were present:
- /INCLUDE <include_file> <prefix>
<suffix>
(see dirfile-format(5)). The prefix may include a
namespace, separated from the rest of the prefix, which may be the empty
string, by a dot (.). If a parser callback function had been
specified when the dirfile was opened using gd_cbopen(3), or added
later with gd_parser_callback(3), this callback function will be
called if a syntax error is encountered while parsing the included
fragment.
Passing NULL as prefix or suffix is the same as
using the empty string (ie. the corresponding affix is empty).
The function gd_include() is equivalent to calling
gd_include_affix() with both prefix and suffix equal to
NULL.
The function gd_include_ns() is equivalent to calling
gd_include_affix() with suffix equal to NULL and prefix
equal to namespace concatenated with a trailing dot.
The flags argument should be a bitwise-or'd collection of
zero or more of the following flags:
GD_ARM_ENDIAN
- GD_NOT_ARM_ENDIAN
- Specifies that double precision floating point raw data on disk are, or
are not, stored in the middle-endian format used by older ARM processors.
These flag only set the default endianness, and will be
overridden when an /ENDIAN directive specifies the byte sex of
RAW fields, unless GD_FORCE_ENDIAN is also specified.
On every platform, one of these flags
(GD_NOT_ARM_ENDIAN on all but middle-ended ARM systems) indicates
the native behaviour of the platform. That symbol will equal zero, and
may be omitted.
GD_BIG_ENDIAN
- GD_LITTLE_ENDIAN
- Specifies the default byte sex of raw data stored on disk to be either
big-endian (most significant byte first) or little-endian (least
significant byte first). Omitting both flags indicates the default should
be the native endianness of the platform.
Unlike the ARM endianness flags above, neither of these
symbols is ever zero. Specifying both these flags together will cause
the library to assume that the endianness of the data is opposite to
that of the native architecture, whatever that might be.
These flag only set the default endianness, and will be
overridden when an /ENDIAN directive specifies the byte sex of
RAW fields, unless GD_FORCE_ENDIAN is also specified.
- 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. If GD_CREAT is not specified,
this flag is ignord. 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.
No indication is provided to indicate whether a duplicate
field has been discarded. If finer grained control is required, the
caller should handle GD_E_FORMAT_DUPLICATE suberrors itself with
an appropriate callback function.
- 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_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.
The flags argument may also be bitwise or'd with one of the
following symbols indicating the default encoding scheme of the fragment.
Like the endianness flags, the choice of encoding here is ignored if the
encoding is specified in the fragment itself, unless GD_FORCE_ENCODED
is also specified. If none of these symbols is present,
GD_AUTO_ENCODED is assumed, unless this call results in creation or
truncation of the fragment. In that case, GD_UNENCODED is assumed.
See dirfile-encoding(5) for details on dirfile encoding schemes.
- 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
gd_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_ENCODED
- 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_FLAC_ENCODED
- Specifies that raw data files are compressed using the Free Lossless Audio
Coded (FLAC).
- GD_GZIP_ENCODED
- Specifies that raw data files are compressed using Lempel-Ziv coding
(LZ77) as implemented in the gzip format.
- GD_LZMA_ENCODED
- Specifies that raw data files are compressed using the Lempel-Ziv Markov
Chain Algorithm (LZMA) as implemented in the xz container format.
- GD_SIE_ENCODED
- Specified that raw data files are sample-index encoded, similar to
run-length encoding, suitable for data that change rarely.
- 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.
- GD_ZZIP_ENCODED
- Specifies that raw data files are compressed using the DEFLATE algorithm.
All raw data files for a given fragment are collected together and stored
in a PKZIP archive called raw.zip.
- GD_ZZSLIM_ENCODED
- Specifies that raw data files are compressed using a combinations of
compression schemes: first files are slim-compressed, as with the
GD_SLIM_ENCODED scheme, and then they are collected together and
compressed (again) into a PKZIP archive called raw.zip, as in the
GD_ZZIP_ENCODED scheme.
On success, these functions return the format specification index
of the newly added fragment. On error, they return a negative-valued error
code. Possible error codes 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. In this case, the included fragment will still be added to the
dirfile, but the /REFERENCE directive will be ignored.
- GD_E_CALLBACK
- The registered callback function returned an unrecognised response.
- GD_E_FORMAT
- A syntax error occurred in the fragment.
- 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_IO
- An I/O error occured while trying to read or create the fragment.
- GD_E_PROTECTED
- The metadata of the parent fragment was protected from change.
The error code is also stored in the DIRFILE object and may
be retrieved after this function returns by calling gd_error(3). A
descriptive error string for the error may be obtained by calling
gd_error_string(3).
The dirfile_include() function appeared in
GetData-0.4.0.
In GetData-0.7.0, this function was renamed to
gd_include().
The gd_include_affix() function appeared in
GetData-0.8.0.
In GetData-0.10.0, the error return from these functions changed
from -1 to a negative-valued error code. The gd_include_ns() function
also appeared in this release.
See gd_open(3) for history of the flags.
gd_alter_affixes(3), gd_error(3),
gd_error_string(3), gd_fragmentname(3),
gd_nfragments(3), gd_open(3), gd_parser_callback(3),
gd_reference(3), gd_uninclude(3), dirfile(5),
dirfile-encoding(5), dirfile-format(5)