.\" gd_add_alias.3.  The gd_add_alias man page.
.\"
.\" Copyright (C) 2012 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_add_alias 3 "26 July 2012" "Version 0.8.1" "GETDATA"
.SH NAME
gd_add_alias, gd_madd_alias \(em add a field to a dirfile
.SH SYNOPSIS
.B #include <getdata.h>
.HP
.nh
.ad l
.BI "int gd_add_alias(DIRFILE *" dirfile ", const char *" alias_name ,
.BI "const char *" target_code ", int " fragment_index );
.HP
.BI "int gd_madd_alias(DIRFILE *" dirfile ", const char *" parent ,
.BI "const char *" alias_name ", const char *" target_code );
.hy
.ad n
.SH DESCRIPTION
The
.BR gd_add_alias ()
function adds the alias named
.I alias_name
pointing to
.I target_code
to the fragment indexed by
.I fragment_index
in the dirfile specified by
.IR dirfile .
The
.BR gd_madd_alias ()
function behaves similarly, but adds the field as a meta-entry under the field
indicated by the field code
.IR parent .

.SH RETURN VALUE
On success,
.BR gd_add_alias ()
and
.BR gd_madd_alias ()
return 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
.IR alias_name
contained invalid characters; or it or an input field did not contain the
affected fragment's prefix or suffix. Alternately, the
.I parent
field code was not found, or was already a metafield.
.TP
.B GD_E_BAD_DIRFILE
The supplied dirfile was invalid.
.TP
.B GD_E_BAD_INDEX
The
.I fragment_index
specified was out of range.
.TP
.B GD_E_DUPLICATE
The
.I alias_name
parameter duplicated that of an already existing entry.
.TP
.B GD_E_PROTECTED
The metadata of the fragment was protected from change.  Or, the creation of a
.B RAW
field was attempted and the data of the fragment was protected.
.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_add (3),
.BR gd_alias_target (3),
.BR gd_entry (3),
.BR gd_madd (3),
.BR gd_metaflush (3),
.BR gd_open (3),
.BR dirfile-format (5)