NAME¶
gd_rename — change the name of a dirfile field
SYNOPSIS¶
#include <getdata.h>
int gd_rename(DIRFILE *dirfile, const char
*old_code, const char *new_name, int
move_data);
DESCRIPTION¶
The
gd_rename() function changes the name of the field specified by
old_code, which should not contain a representation suffix, defined in
the dirfile specified by
dirfile to
new_name. If the new name is
the same as the old name, this function does nothing.
When renaming a metafield, the metafield should be specified in
old_code
by its full (slashed) field code, while
new_name should only contain
the new name (without slash).
If the flag
move_data is non-zero, and
old_code specifies a
RAW field, the binary file associated with the field will be renamed as
well. 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.
RETURN VALUE¶
On success,
gd_rename() 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 old_code was not found.
- GD_E_BAD_DIRFILE
- The supplied dirfile was invalid.
- GD_E_BAD_FIELD_TYPE
- An attempt was made to rename the immutable INDEX field.
- GD_E_BAD_REPR
- The representation suffix specified in field_code was not
recognised.
- GD_E_DUPLICATE
- The new name specified is already in use by another field.
- GD_E_PROTECTED
- The metadata of the format specification fragment containing the field was
protected from change, or the binary data of the fragments was protected
from change and binary file translation was requested.
- GD_E_RAW_IO
- An I/O error occurred while attempting to rename the binary file.
- GD_E_UNKNOWN_ENCODING
- The encoding scheme of the specified field could not be determined or was
not understood by GetData.
- GD_E_UNSUPPORTED
- The encoding scheme of the field does not support binary file
renaming.
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).
SEE ALSO¶
gd_metaflush(3),
gd_open(3),
gd_error(3),
gd_error_string(3),
dirfile(5),
dirfile-format(5)