Provided by: libgetdata-doc_0.11.0-4_all bug


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


       #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

               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

               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.

               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

               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

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

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

               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

               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.

               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.

               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.

               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

               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.

               Specifies that raw data files  are  compressed  using  the  Burrows-Wheeler  block
               sorting text compression algorithm and Huffman coding, as implemented in the bzip2

               Specifies that raw data files are compressed using the Free Lossless  Audio  Coded

               Specifies  that  raw  data  files are compressed using Lempel-Ziv coding (LZ77) as
               implemented in the gzip format.

               Specifies that raw data files are compressed using  the  Lempel-Ziv  Markov  Chain
               Algorithm (LZMA) as implemented in the xz container format.

               Specified  that  raw  data  files  are sample-index encoded, similar to run-length
               encoding, suitable for data that change rarely.

               Specifies that raw data files are compressed using the slimlib library.

               Specifies that raw data files are encoded as text files containing one data sample
               per line.

               Specifies that raw data files are not encoded, but written verbatim to disk.

               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

               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, 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:

               The supplied dirfile was opened in read-only mode.

               The library was unable to allocate memory.

               The supplied dirfile was invalid.

               The supplied parent fragment index was out of range.

               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.

               The registered callback function returned an unrecognised response.

               A syntax error occurred in the fragment.

               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.

               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)