.\" header.tmac.  GetData manual macros.
.\"
.\" Copyright (C) 2016 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.

.\" Format a function name with optional trailer: func_name()trailer
.de FN \" func_name [trailer]
.nh
.BR \\$1 ()\\$2
.hy
..

.\" Format a reference to section 3 of the manual: name(3)trailer
.de F3 \" func_name [trailer]
.nh
.BR \\$1 (3)\\$2
.hy
..

.\" Format the header of a list of definitons
.de DD \" name alt...
.ie "\\$2"" \{ \
.TP 8
.PD
.B \\$1 \}
.el \{ \
.PP
.B \\$1
.PD 0
.DD \\$2 \\$3 \}
..

.\" Start a code block: Note: groff defines an undocumented .SC for
.\" Bell Labs man legacy reasons.
.de SC
.fam C
.na
.nh
..

.\" End a code block
.de EC
.hy
.ad
.fam
..

.\" Format a structure pointer member: struct->member\fRtrailer
.de SPM \" struct member trailer
.nh
.ie "\\$3"" .IB \\$1 ->\: \\$2
.el .IB \\$1 ->\: \\$2\fR\\$3
.hy
..

.\" Format a function argument
.de ARG \" name trailer
.nh
.ie "\\$2"" .I \\$1
.el .IR \\$1 \\$2
.hy
..

.\" Hyphenation exceptions
.hw sarray carray lincom linterp
.\" gd_rewrite_fragment.3.  The gd_rewrite_fragment man page.
.\"
.\" Copyright (C) 2010, 2011, 2014, 2016 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 "25 December 2016" "Version 0.10.0" "GETDATA"

.SH NAME
gd_rewrite_fragment \(em re-write a Dirfile format specification fragment

.SH SYNOPSIS
.SC
.B #include <getdata.h>
.HP
.BI "int gd_rewrite_fragment(DIRFILE *" dirfile ", int " fragment );
.EC

.SH DESCRIPTION
The
.FN 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
.F3 gd_dirfile_standards
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, a negative-valued error code is
returned.  Possible error codes are:
.DD GD_E_ACCMODE
The supplied dirfile was opened in read-only mode.
.DD GD_E_ALLOC
The library was unable to allocate memory.
.DD GD_E_BAD_DIRFILE
The supplied dirfile was invalid.
.DD GD_E_BAD_INDEX
The supplied fragment index was out of range.
.DD GD_E_IO
An I/O error occurred while trying to write modified metadata to disk.
.DD 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 error code is also stored in the
.B DIRFILE
object and may be retrieved after this function returns by calling
.F3 gd_error .
A descriptive error string for the error may be obtained by calling
.F3 gd_error_string .

.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 HISTORY
The
.FN gd_rewrite_fragment
function appeared in GetData-0.7.0.

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

.SH SEE ALSO
.F3 gd_close ,
.F3 gd_dirfile_standards ,
.F3 gd_error ,
.F3 gd_error_string ,
.F3 gd_flush ,
.F3 gd_metaflush ,
.F3 gd_open