.\" gd_rewrite_fragment.3.  The gd_rewrite_fragment man page.
.\"
.\" Copyright (C) 2010, 2011, 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_rewrite_fragment 3 "16 October 2014" "Version 0.9.0" "GETDATA"
.SH NAME
gd_rewrite_fragment \(em re-write a dirfile format specification fragment
.SH SYNOPSIS
.B #include <getdata.h>
.HP
.nh
.ad l
.BI "int gd_rewrite_fragment(DIRFILE *" dirfile ", int " fragment );
.hy
.ad n
.SH DESCRIPTION
The
.BR gd_rewrite_fragment ()
writes the format specification fragment specified by
.I fragment
to disk, regardless of whether it has changed or not, overwriting the existing
file.
.PP
In addition to being simply a valid fragment index,
.I fragment
may also be the special value
.BR GD_ALL_FRAGMENTS ,
which indicates that all fragments should be rewritten.
.PP
Metadata is written to disk using the current Standards Version as stored in the
.I dirfile
object.  See
.BR 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.
.SH 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:
.TP 8
.B GD_E_ACCMODE
The supplied dirfile was opened in read-only mode.
.TP
.B GD_E_ALLOC
The library was unable to allocate memory.
.TP
.B GD_E_BAD_DIRFILE
The supplied dirfile was invalid.
.TP
.B GD_E_BAD_INDEX
The supplied fragment index was out of range.
.TP
.B GD_E_IO
An I/O error occurred while trying to write modified 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.
.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 BUGS
When writing metadata using Standards Version 4 or earlier, the reference field
may change, owing to the lack of a
.B /REFERENCE
directive.  A work-around is to upgrade to Standards Version 5 or later.
.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_flush (3),
.BR gd_metaflush (3)