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 metadata, 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 conforms 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, -1 is returned and the dirfile error is set to  a
       non-zero error value.  Possible error values 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 maximum allowed length.  On most platforms, the maximum length is  at
               least 2**31 bytes, so this typically indicates something pathological happening.

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

BUGS

       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.

SEE ALSO

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