gd_include man page on OpenSuSE

Man page or keyword search:  
man Server   25941 pages
apropos Keyword Search (all sections)
Output format
OpenSuSE logo
[printable version]

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 ALSO
       gd_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)
[top]

List of man pages available for OpenSuSE

Copyright (c) for man pages and the logo by the respective OS vendor.

For those who want to learn more, the polarhome community provides shell access and support.

[legal] [privacy] [GNU] [policy] [cookies] [netiquette] [sponsors] [FAQ]
Tweet
Polarhome, production since 1999.
Member of Polarhome portal.
Based on Fawad Halim's script.
....................................................................
Vote for polarhome
Free Shell Accounts :: the biggest list on the net