NAME

       gd_metaflush — write modified Dirfile metadata to disk

SYNOPSIS

       #include <getdata.h>

       int gd_metaflush(DIRFILE *dirfile);

DESCRIPTION

       The  gd_metaflush()  function flushes all pending metadata changes in the dirfile specified by dirfile to
       disk.  This is accomplished by re-writing the format specification fragments containing modified  metada‐
       ta, overwriting the existing files.  Format file fragments which are unchanged are not touched.

       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, a Standards non-compliant fragment will be written.

       This function flushes only metadata.  To flush the field data as well, call gd_sync(3) instead.

RETURN VALUE

       On  success, zero is returned.  On error, a negative-valued error code is returned.  Possible error codes
       are:

       GD_E_ACCMODE
               The supplied dirfile was opened in read-only mode.

       GD_E_ALLOC
               The library was unable to allocate memory.

       GD_E_BAD_DIRFILE
               The supplied dirfile was invalid.

       GD_E_IO An I/O error occurred while trying to write modified metadata to disk.

       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.

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

NOTES

       When writing metadata using Standards Version 4 or earlier, the reference field may change, owing to  the
       lack of a /REFERENCE directive.  A work-around is to upgrade to Standards Version 5 or later.

HISTORY

       The dirfile_metaflush() function appeared in GetData-0.4.0.

       In GetData-0.7.0, this function was renamed to gd_metaflush().

       in GetData-0.10.0, the error return from this function changed from -1 to a negative-valued error code.

SEE ALSO

       gd_close(3),       gd_dirfile_standards(3),       gd_error(3),       gd_error_string(3),      gd_open(3),
       gd_rewrite_fragment(3), gd_sync(3)

Version 0.10.0                                  25 December 2016                                 gd_metaflush(3)