--- name: "gd_include" section: "3" platform: "linux" package: "libgetdata-doc" version: "0.11.0-15" release: "Debian 13 (Trixie)" platforms: ["linux"] url: "https://new.carta.tech/gd_include" --- # gd\_include(3) add a format specification fragment to a Dirfile ## NAME gd\_include, gd\_include\_affix, gd\_include\_ns — add a format specification fragment to a Dirfile ## SYNOPSIS **#include \** **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** *\ \ \* (see [dirfile-format(5)](/dirfile-format/5.md)). 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)](/gd_cbopen/3.md), or added later with [**gd\_parser\_callback**(3)](/gd_parser_callback/3.md), 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: .PP **GD\_ARM\_ENDIAN**\ .TP 8 **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.\ .PP **GD\_BIG\_ENDIAN**\ .TP 8 **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.\ .TP 8 **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)](/umask/2.md)).\ .TP 8 **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)](/open/2.md).\ .TP 8 **GD\_FORCE\_ENCODING** Specifies that **/ENCODING** directives (see [dirfile-format(5)](/dirfile-format/5.md)) found in the fragment should be ignored. The encoding scheme specified in *flags* will be used instead (see below).\ .TP 8 **GD\_FORCE\_ENDIAN** Specifies that **/ENDIAN** directives (see [dirfile-format(5)](/dirfile-format/5.md)) 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.\ .TP 8 **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.\ .TP 8 **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.\ .TP 8 **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)](/dirfile-format/5.md)) indicates that the fragment being opened conforms Standards Version newer than the version understood by the library, unrecognised lines will be silently ignored.\ .TP 8 **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)](/dirfile-encoding/5.md) for details on dirfile encoding schemes.\ .TP 8 **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)](/gd_putdata/3.md) 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.\ .TP 8 **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.\ .TP 8 **GD\_FLAC\_ENCODED** Specifies that raw data files are compressed using the Free Lossless Audio Coded (FLAC).\ .TP 8 **GD\_GZIP\_ENCODED** Specifies that raw data files are compressed using Lempel-Ziv coding (LZ77) as implemented in the gzip format.\ .TP 8 **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.\ .TP 8 **GD\_SIE\_ENCODED** Specified that raw data files are sample-index encoded, similar to run-length encoding, suitable for data that change rarely.\ .TP 8 **GD\_SLIM\_ENCODED** Specifies that raw data files are compressed using the slimlib library.\ .TP 8 **GD\_TEXT\_ENCODED** Specifies that raw data files are encoded as text files containing one data sample per line. \ .TP 8 **GD\_UNENCODED** Specifies that raw data files are not encoded, but written verbatim to disk.\ .TP 8 **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.\ .TP 8 **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:\ .TP 8 **GD\_E\_ACCMODE** The supplied dirfile was opened in read-only mode.\ .TP 8 **GD\_E\_ALLOC** The library was unable to allocate memory.\ .TP 8 **GD\_E\_BAD\_DIRFILE** The supplied dirfile was invalid.\ .TP 8 **GD\_E\_BAD\_INDEX** The supplied parent fragment index was out of range.\ .TP 8 **GD\_E\_BAD\_REFERENCE** The reference field specified by a **/REFERENCE** directive in the fragment (see [dirfile-format(5)](/dirfile-format/5.md)) 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.\ .TP 8 **GD\_E\_CALLBACK** The registered callback function returned an unrecognised response.\ .TP 8 **GD\_E\_FORMAT** A syntax error occurred in the fragment.\ .TP 8 **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.\ .TP 8 **GD\_E\_IO** An I/O error occured while trying to read or create the fragment.\ .TP 8 **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)](/gd_error/3.md). A descriptive error string for the error may be obtained by calling [**gd\_error\_string**(3)](/gd_error_string/3.md). ## 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)](/gd_open/3.md) for history of the flags. ## SEE ALSO [**gd\_alter\_affixes**(3)](/gd_alter_affixes/3.md), [**gd\_error**(3)](/gd_error/3.md), [**gd\_error\_string**(3)](/gd_error_string/3.md), [**gd\_fragmentname**(3)](/gd_fragmentname/3.md), [**gd\_nfragments**(3)](/gd_nfragments/3.md), [**gd\_open**(3)](/gd_open/3.md), [**gd\_parser\_callback**(3)](/gd_parser_callback/3.md), [**gd\_reference**(3)](/gd_reference/3.md), [**gd\_uninclude**(3)](/gd_uninclude/3.md), [dirfile(5)](/dirfile/5.md), [dirfile-encoding(5)](/dirfile-encoding/5.md), [dirfile-format(5)](/dirfile-format/5.md)