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()  and  gd_discard()  attempt to close the open Dirfile dirfile and free all
       memory associated with it.

       The gd_close() function first flushes all pending metadata updates to disk.  This step  is
       skipped  by  gd_discard(),  which  simply  discards metadata changes.  For dirfiles opened
       read-only, these two functions are equivalent.

       Next, all pending data is flushed to disk and all open data files  closed.   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 gd_discard().

       Finally, if the above didn't encounter an error, these functions  free  memory  associated
       with the DIRFILE object.

       If dirfile is NULL, nothing happens, and the call succeeds.

       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 instead return a negative-valued error code.  Possible error codes 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  error  code  is  also  stored  in  the DIRFILE object and may be retrieved after this
       function returns by calling gd_error(3).  A descriptive error string for the error may  be
       obtained by calling gd_error_string(3).

HISTORY

       The function dirfile_close() appeared in GetData-0.3.0.

       The function dirfile_discard() appeared in GetData-0.6.0.

       In GetData-0.7.0 these functions were renamed to gd_close() and gd_discard().

       In  GetData-0.10.0,  the  error return from these functions changed from -1 to a negative-
       valued error code.

SEE ALSO

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