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 modi‐
       fied 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() re‐
       turns 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 con‐
       forms 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  in‐
       stead 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 max‐
               imum allowed length.  On most platforms, the maximum length is at least 2**31 bytes, so this typ‐
               ically 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, an‐
               other 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)

Version 0.10.0                                  25 December 2016                                     gd_close(3)