gd_include_affix(3) GETDATA gd_include_affix(3)NAME
gd_include_affix, gd_include — add a format specification fragment to a
dirfile
SYNOPSIS
#include <getdata.h>
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(DIRFILE *dirfile, const char *include_file, int
parent_fragment, unsigned long flags);
DESCRIPTION
The gd_include_affix() function adds the format specification fragment
given by the path include_file to the specified dirfile, possibly cre‐
ating the fragment, using the affixes specified. This occurs as if, in
the existing fragment indexed by parent_fragment, the following direc‐
tive were present:
/INCLUDE <include_file> <prefix> <suffix>
(see dirfile-format(5)). If a parser callback function had been speci‐
fied 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 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 old‐
er ARM processors.
These flag only set the default endianness, and will be overrid‐
den 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 oppo‐
site to that of the native architecture, whatever that might be.
These flag only set the default endianness, and will be overrid‐
den 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 ex‐
ist. 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 in‐
cluded 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 en‐
coding 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-encod‐
ing(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 accom‐
plished by searching for raw data files with extensions appro‐
priate to the encoding scheme. This method will notably fail if
the the library is called via gd_putdata(3) to create a previ‐
ously 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 subse‐
quent 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_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 con‐
tainer 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 contain‐
ing one data sample per line.
GD_UNENCODED
Specifies that raw data files are not encoded, but written ver‐
batim 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 collect‐
ed together and stored in a PKZIP archive called raw.zip.
GD_ZZSLIM_ENCODED
Specifies that raw data files are compressed using a combina‐
tions 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.
RETURN VALUE
On success, these functions return the format specification index of
the newly added fragment. On error, -1 is returned and the dirfile er‐
ror 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. In this case, the included fragment will still be
added to the dirfile, but the /REFERENCE directive will be ig‐
nored. See also the BUGS section below.
GD_E_CALLBACK
The registered callback function returned an unrecognised re‐
sponse.
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_OPEN_FRAGMENT
The fragment could not be opened or created.
GD_E_PROTECTED
The metadata of the parent fragment was protected from change.
The dirfile error may be retrieved by calling gd_error(3). A descrip‐
tive error string for the last error encountered can be obtained from a
call to gd_error_string(3).
BUGS
If this function fails with the error GD_E_BAD_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 ALSOgd_open(3), gd_alter_affixes(3), gd_error(3), gd_error_string(3),
gd_fragmentname(3), gd_nfragments(3), gd_parser_callback(3), gd_refer‐
ence(3), gd_uninclude(3), dirfile(5), dirfile-encoding(5), dirfile-for‐
mat(5)Version 0.8.0 21 April 2012 gd_include_affix(3)