NAME

       gd_close, gd_discard — close a dirfile and free associated memory.

SYNOPSIS

       #include <getdata.h>

       int gd_close(DIRFILE *dirfile);

       int gd_discard(DIRFILE *dirfile);

DESCRIPTION

       The gd_close() function first calls gd_flush(3) (with field_code set to NULL) to flush all
       metadata changes to disk and to close all file handles associated with dirfile.   It  then
       frees memory associated with the DIRFILE object.  If dirfile is NULL, nothing happens, and
       the call succeeds.

       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 VALUE

       gd_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:

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

       GD_E_RAW_IO
               An error occurred while trying to flush or close one or more open raw  files.   In
               this case, another call to gd_close() or gd_discard() may be attempted.

       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).

SEE ALSO

       gd_cbopen(3),  gd_dirfile_standards(3),  gd_error(3),   gd_error_string(3),   gd_flush(3),
       gd_invalid_dirfile(3), gd_open(3)