xenial (3) gd_close.3.gz

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)