Ubuntu Manpage: gd_include — add a format specification fragment to a dirfile

Provided by: libgetdata-dev_0.7.3-6ubuntu1_amd64

NAME

       gd_include — 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);

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>

(see dirfile-format(5)). 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.

The flags argument should be a bitwise-or'd collection of the following flags, or zero if
no flags are desired:

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.

This flag is ignored completely if an ENDIAN directive occurs in the fragment,
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. 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.

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

This flag is ignored completely if an ENDIAN directive occurs in the fragment,
unless GD_FORCE_ENDIAN is also specified.

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 the gd_include() 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 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.

The dirfile error may be retrieved by calling gd_error(3). A descriptive error string for
the last error encountered can be obtained from a call to gd_error_string(3). When
finished with it, the DIRFILE object may be de-allocated with a call to gd_close(3), even
if the open failed.

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.

NAME

SYNOPSIS

DESCRIPTION

RETURN VALUE

BUGS

SEE ALSO