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)