Ubuntu Manpage: gd_include, gd_include_affix, gd_include_ns — add a format specification fragment to a

Provided by: libgetdata-doc_0.11.0-14_all

NAME

       gd_include,  gd_include_affix,  gd_include_ns  —  add a format specification fragment to a
       Dirfile

SYNOPSIS

       #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);

DESCRIPTION

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_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.

RETURN VALUE

       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).

HISTORY

       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.

NAME

SYNOPSIS

DESCRIPTION

RETURN VALUE

HISTORY

SEE ALSO