.\" 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_rename.3.  The gd_rename man page.
.\"
.\" Copyright (C) 2008, 2009, 2010, 2011, 2012, 2013, 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_rename 3 "25 December 2016" "Version 0.10.0" "GETDATA"

.SH NAME
gd_rename \(em change the name of a Dirfile field or alias

.SH SYNOPSIS
.SC
.B #include <getdata.h>
.HP
.BI "int gd_rename(DIRFILE *" dirfile ", const char"
.BI * old_code ", const char *" new_name ", unsigned int " flags );
.EC

.SH DESCRIPTION
The
.FN gd_rename
function changes the name of the field or alias 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 and
returns no error.

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 
.I old_code
specifies a top-level field with meta subfields, the subfields will be renamed,
too.  By default, this function also updates
.B ALIAS
entries whose target contains
.I old_code
to point to the new field.  Similarly, specifying the
.B GD_REN_UPDB
flag will cause this function to modify any field entry containing
.IR old_code .
As a result, this function may cause more than one metadata fragment to be
modified.

The
.I flags
parameter should be zero or more of the following flags, bitwise or'd together:
.DD GD_REN_DANGLE
Don't update
.B ALIAS
entries, instead turning them into dangling aliases.
.DD GD_REN_DATA
if
.I old_code
specifies a
.B RAW
field, the binary file associated with the field will be renamed as well.
Without this flag, no changes are made to the binary file.  In this case, the
field's I/O pointer will be reset to the beginning-of-frame.  If
.I field_code
specifies a field of type other than
.BR RAW ,
this flag is ignored.
.DD GD_REN_FORCE
When updating field metadata (either the target of an alias, or else when
specified along with
.BR GD_REN_UPDB ), 
skip updating field codes which would be invalid (due to
.B /INCLUDE
affixes).  Without this flag, such invalid field codes causes this function to
fail with the error
.BR GD_E_BAD_CODE .
.DD GD_REN_UPDB
Rename the field in any other field specifications which use this field as an
input (either as a vector input field to a derived field, or else as a scalar
field parameter).  Without this flag, fields which depend on the old name of
this field are left unmodified.

.SH RETURN VALUE
On success,
.FN gd_rename
returns zero.   On error, a negative-valued error code is returned.  Possible
error codes are:
.DD GD_E_ACCMODE
The specified dirfile was opened read-only.
.DD GD_E_ALLOC
The library was unable to allocate memory.
.DD GD_E_BAD_CODE
The field specified by
.I old_code
was not found.  Or else the resultant metadata update tried to change a
field code into something prohibited by a fragment's affixes.
.DD GD_E_BAD_DIRFILE
The supplied dirfile was invalid.
.DD GD_E_BAD_FIELD_TYPE
An attempt was made to rename the immutable
.I INDEX
field.
.DD GD_E_DUPLICATE
The new name specified is already in use by another entry.
.DD GD_E_IO
An I/O error occurred while attempting to rename the binary file.
.DD GD_E_PROTECTED
The metadata of the format specification fragment containing the renamed entry,
or another entry affected by this change, was protected from change, or the
binary data of the fragment was protected from change and a binary file move
was requested.
.DD GD_E_UNKNOWN_ENCODING
The encoding scheme of the specified field could not be determined or was not
understood by GetData.
.DD GD_E_UNSUPPORTED
The encoding scheme of the field does not support binary file renaming.
.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 HISTORY
The
.FN dirfile_rename
function appeared in GetData-0.5.0.  It had no
.ARG flags
argument.  In its place was
.B int
.ARG move_data .
Passing a non-zero value for this parameter has the same effect as the
.B GD_REN_DATA
flag does now.

In GetData-0.7.0, this function was renamed to
.FN gd_rename .

In GetData-0.8.0, the
.ARG move_data
parameter was replaced with the
.ARG flags
parameter.  The only flags available were
.B GD_REN_DATA
and
.BR GD_REN_UBDB .

The flags
.B GD_REN_DANGLE
and
.B GD_REN_FORCE
flags appeared in GetData-0.9.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_error ,
.F3 gd_error_string ,
.F3 gd_metaflush ,
.F3 gd_open ,
dirfile(5), dirfile-format(5)