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)