int gd_close(DIRFILE *dirfile);
- int gd_discard(DIRFILE *dirfile);
The gd_discard() function behaves similarly, except modified metadata is not written to disk, but simply discarded. In order to ensure that modified data files associated with RAW fields are properly terminated, changes to RAW data files are still flushed to disk by this function. If dirfile was opened in read-only mode, gd_discard() and gd_close() behave identically.
One of these functions should be called on all pointers returned by gd_cbopen(3), gd_open(3), and gd_invalid_dirfile(3), even if the call to those function failed. After gd_close() or gd_discard() returns successfully, the pointer dirfile should be considered invalid.
Metadata is written to disk using the current Standards Version as stored in the dirfile object. See gd_dirfile_standards(3) to change or report the current Standards Version. If the dirfile metadata conforms to no known Standards Version, Standards non-compliant metadata will be written.
RETURN VALUEgd_close() and gd_discard() return zero on success. On error, they do not de-allocate dirfile and set the dirfile error to a non-zero error value. Possible error values are:
- The library was unable to allocate memory.
- While attempting to flush modified metadata to disk, a field specification line exceeded the maximum allowed length. On most platforms, the maximum length is at least 2**31 bytes, so this typically indicates something pathological happening.
- An I/O error occurred while trying to write modified data or metadata to disk. In this case, another call to gd_close() or gd_discard() may be attempted.