.\" gd_flush.3.  The gd_flush man page.
.\"
.\" Copyright (C) 2008, 2009, 2010, 2011, 2012, 2014 D. V. Wiebe
.\"
.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
.\"
.\" This file is part of the GetData project.
.\"
.\" Permission is granted to copy, distribute and/or modify this document
.\" under the terms of the GNU Free Documentation License, Version 1.2 or
.\" any later version published by the Free Software Foundation; with no
.\" Invariant Sections, with no Front-Cover Texts, and with no Back-Cover
.\" Texts.  A copy of the license is included in the `COPYING.DOC' file
.\" as part of this distribution.
.\"
.TH gd_flush 3 "16 October 2014" "Version 0.9.0" "GETDATA"
.SH NAME
gd_flush gd_raw_close gd_sync \(em write all pending dirfile changes to disk or
close open raw fields
.SH SYNOPSIS
.B #include <getdata.h>
.HP
.nh
.ad l
.HP
.BI "int gd_flush(DIRFILE *" dirfile ", const char *" field_code );
.HP
.BI "int gd_raw_close(DIRFILE *" dirfile ", const char *" field_code );
.HP
.BI "int gd_sync(DIRFILE *" dirfile ", const char *" field_code );
.hy
.ad n
.SH DESCRIPTION
The
.BR gd_sync ()
function flushes all pending writes to disk of raw data files associated with
.IR field_code ,
or its input(s), in the dirfile specified by
.IR dirfile .
If the
.I field_code
contains a valid representation suffix, it will be ignored.  As a special case,
if
.I field_code
is NULL, all fields in
.I dirfile
will be flushed.  In this special case, modified metadata will also be flushed
to disk as if
.BR gd_metaflush (3)
had been called.  If the dirfile has been opened read-only, this function does
nothing.  Additionally, some encoding schemes may implement this as a NOP.
.PP
The
.BR gd_raw_close ()
function closes any raw data files which GetData has opened associated with
.IR field_code ,
or its input(s).  Again, if
.I field_code
is NULL, all open data files are closed.  The I/O pointer of any
.B RAW
field which is closed is reset to the beginning-of-field.
.PP
Calling
.BR gd_flush ()
is essentially equivalent to calling first
.BR gd_sync ()
and then
.BR gd_raw_close ()
(ie. it does both tasks), although, if
.I field_code
is NULL, the order of operations if may be different than making the two explicit
calls.
.SH RETURN VALUE
On success, these functions return zero.  On error, -1 is returned and the
dirfile error is set to a non-zero error value.  Possible error values are:
.TP 8
.B GD_E_ALLOC
The library was unable to allocate memory.
.TP
.B GD_E_BAD_CODE
The field specified by
.I field_code
was not found in the database.
.TP
.B GD_E_BAD_DIRFILE
The supplied dirfile was invalid.
.TP
.B GD_E_IO
An I/O error occurred while trying to write modified data or metadata to disk.
.TP
.B 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.
.TP
.B GD_E_RECURSE_LEVEL
Too many levels of recursion were encountered while trying to resolve
.IR field_code .
This usually indicates a circular dependency in field specification in the
dirfile.
.PP
The dirfile error may be retrieved by calling
.BR gd_error (3).
A descriptive error string for the last error encountered can be obtained from
a call to
.BR gd_error_string (3).
.SH SEE ALSO
.BR gd_open (3),
.BR gd_close (3),
.BR gd_dirfile_standards (3),
.BR gd_error (3),
.BR gd_error_string (3),
.BR gd_metaflush (3)