gd_rewrite_fragment(3)

NAME

gd_rewrite_fragment—re-write a Dirfile format specification fragment

SYNOPSIS

#include <getdata.h>

int gd_rewrite_fragment(DIRFILE *dirfile, int fragment);

DESCRIPTION

The gd_rewrite_fragment() writes the format specification fragment specified by fragment to disk, regardless of whether it has changed or not, overwriting the existing file.

In addition to being simply a valid fragment index, fragment may also be the special value GD_ALL_FRAGMENTS, which indicates that all fragments should be rewritten.

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.

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_BAD_INDEX
The supplied fragment index was out of range.
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 231 bytes, so this typically 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).

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.

HISTORY

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

SEE ALSO

gd_close(3), gd_dirfile_standards(3), gd_error(3), gd_error_string(3), gd_flush(3), gd_metaflush(3), gd_open(3)


Last updated on 25 December 2016 for GetData Version 0.10.0.