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, -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 fragment index was out of range, or an attempt was made to remove the
               primary format specification.

       GD_E_FLUSH
               A  temporary  file  could  not  be  opened  into  which to write the metadata of a
               modified, removed fragment, or renaming  the  temporary  file  over  the  original
               fragment failed.

       GD_E_PROTECTED
               The  metadata  of  the  fragment which included the removed fragment was protected
               from change.

       GD_E_RAW_IO
               An error occurred while trying to flush or close a removed field.

       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.

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.

       Unlike gd_delete(3), fields which depend on  fields  removed  by  this  function  are  not
       automatically  updated,  nor is any check made to ensure that this function does not leave
       fields with missing input fields.  Because of this, a fragment  inclusion  may  be  easily
       moved from one fragment to another with a combination of gd_uninclude() and gd_include(3).
       However, if such checks are required, use gd_delete(3) to delete the fields defined in the
       removed fragments first.

SEE ALSO

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