.\" gd_rename.3.  The gd_rename man page.
.\"
.\" Copyright (C) 2008, 2009, 2010 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_rename 3 "20 July 2010" "Version 0.7.0" "GETDATA"
.SH NAME
gd_rename \(em change the name of a dirfile field
.SH SYNOPSIS
.B #include <getdata.h>
.HP
.nh
.ad l
.BI "int gd_rename(DIRFILE *" dirfile ", const char"
.BI * old_code ", const char *" new_name ", int " move_data );
.hy
.ad n
.SH DESCRIPTION
The
.BR gd_rename ()
function changes the name of the field specified by
.IR old_code ,
which should not contain a representation suffix, defined in the dirfile
specified by
.IR dirfile
to
.IR 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
.I old_code
by its full (slashed) field code, while
.I new_name
should only contain the new name (without slash).

If the flag
.I move_data
is non-zero, and
.I old_code
specifies a
.B RAW
field, the binary file associated with the field will be renamed as well.
If
.I move_data
is zero, no changes will be made to the binary file.  If
.I field_code
specifies a field of type other than
.BR RAW ,
the
.I move_data
flag is ignored.

.SH RETURN VALUE
On success,
.BR 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:
.TP 8
.B GD_E_ACCMODE
The specified dirfile was opened read-only.
.TP
.B GD_E_ALLOC
The library was unable to allocate memory.
.TP
.B GD_E_BAD_CODE
The field specified by
.I old_code
was not found.
.TP
.B GD_E_BAD_DIRFILE
The supplied dirfile was invalid.
.TP
.B GD_E_BAD_FIELD_TYPE
An attempt was made to rename the immutable
.I INDEX
field.
.TP
.B GD_E_BAD_REPR
The representation suffix specified in
.I field_code
was not recognised.
.TP
.B GD_E_DUPLICATE
The new name specified is already in use by another field.
.TP
.B 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.
.TP
.B GD_E_RAW_IO
An I/O error occurred while attempting to rename the binary file.
.TP
.B GD_E_UNKNOWN_ENCODING
The encoding scheme of the specified field could not be determined or was not
understood by GetData.
.TP
.B GD_E_UNSUPPORTED
The encoding scheme of the field does not support binary file renaming.
.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 SEE ALSO
.BR gd_metaflush (3),
.BR gd_open (3),
.BR gd_error (3),
.BR gd_error_string (3),
.BR dirfile (5),
.BR dirfile-format (5)