NAME

       gd_uninclude — remove a format specification fragment from a Dirfile

SYNOPSIS

       #include <getdata.h>

       int gd_uninclude(DIRFILE *dirfile, int fragment_index, int del);

DESCRIPTION

       The  gd_uninclude()  removes  the  format specification fragment indexed by fragment_index
       from the specified dirfile, as well as any  fragments  the  indicated  fragment  INCLUDEs.
       Fields defined in the removed fragments will be removed from the dirfile.

       Before  removing  the  specified  fragment,  all  pending writes are flushed to RAW fields
       defined the the removed fragments.  If del is zero, metadata changes will also be  written
       to  the removed fragments.  If del is non-zero, the format specification fragments will be
       deleted from disk, if possible.  Regardless  of  the  value  of  del,  binary  data  files
       associated  with  RAW  fields  defined  in  the removed fragments will not be deleted.  To
       delete these binary files, use gd_delete(3) before calling this function.

       The primary format specification (the fragment indexed by zero) cannot be removed from the
       dirfile.

RETURN VALUE

       On  success,  gd_uninclude()  returns  zero.   On  error,  a negative-valued error code is
       returned.  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 fragment index was out of range, or an attempt was made to remove the
               primary format specification.

       GD_E_IO An I/O error occurred while trying to write modified data or metadata to disk.

       GD_E_PROTECTED
               The  metadata  of  the  fragment which included the removed 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).

NOTES

       This function re-arranges the remaining format specification fragments in some unspecified
       way,  except  for  the  primary  fragment,  which  is  guaranteed to remain at index zero.
       Callers which cache format specification fragment indices must re-initialise  their  cache
       after calling this function.

HISTORY

       The dirfile_uninclude() function appeared in GetData-0.5.0.

       In GetData-0.7.0, this function was renamed to gd_uninclude().

       In  GetData-0.10.0,  the  error  return  from this function changed from -1 to a negative-
       valued error code.

SEE ALSO

       gd_delete(3),     gd_include(3),     gd_open(3),     gd_error(3),      gd_error_string(3),
       gd_fragmentname(3),  gd_nfragments(3),  gd_reference(3),  dirfile(5), dirfile-encoding(5),
       dirfile-format(5)