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_ALLOC
               The library was unable to allocate memory.

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

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

       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)