NAME¶
gd_move — move a dirfile field between format specification fragments
SYNOPSIS¶
#include <getdata.h>
int gd_move(DIRFILE *dirfile, const char
*field_code, int new_fragment, int
move_data);
DESCRIPTION¶
The
gd_move() function transfers the field specified by
field_code, which should not have a representation suffix, defined in
the dirfile specified by
dirfile from it's current format specification
fragment to the fragment index by
new_fragment. If the field is already
defined in the fragment index by
new_fragment, this function does
nothing.
If the flag
move_data is non-zero, and
field_code specifies a
RAW field, the binary file associated with the field will be translated
to account for the possibly different encoding, endianness, and frame offset
of the new format specification fragment. It will also be moved to a new
directory, if necessary. If
move_data is zero, no changes will be made
to the binary file. If
field_code specifies a field of type other than
RAW, the
move_data flag is ignored.
If the binary file is translated, and the frame offset of the destination
fragment is larger than that of the source fragment, this will result in
permanent deletion of data from the database. If the new frame offset is
smaller than the old frame offset, the binary file will be padded at the front
with zeroes.
RETURN VALUE¶
On success,
gd_move() returns zero. 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 specified dirfile was opened read-only.
- GD_E_ALLOC
- The library was unable to allocate memory.
- GD_E_BAD_CODE
- The field specified by field_code was not found.
- GD_E_BAD_DIRFILE
- The supplied dirfile was invalid.
- GD_E_BAD_FIELD_TYPE
- An attempt was made to move the immutable INDEX field.
- GD_E_BAD_INDEX
- The new_fragment argument did not index a valid format
specification fragment.
- GD_E_PROTECTED
- The metadata of the source or destination format specification fragments
was protected from change, or the binary data of the source or destination
fragments was protected from change and binary file translation was
requested.
- GD_E_RAW_IO
- An I/O error occurred while attempting to translate a binary file.
- GD_E_UNKNOWN_ENCODING
- The encoding scheme of the source or destination fragment is unknown.
- GD_E_UNSUPPORTED
- The encoding scheme of the source or destination fragment does not support
binary file translation.
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).
NOTES¶
A binary file translation occurs out-of-place. As a result, sufficient space
must be present on the filesystem for both the binary file before translation
and the binary file after translation.
SEE ALSO¶
gd_metaflush(3),
gd_open(3),
gd_error(3),
gd_error_string(3),
dirfile(5),
dirfile-format(5)