NAME

       gd_aliases — retrieve a list of aliases for a field in a Dirfile database

SYNOPSIS

       #include <getdata.h>

       const char **gd_aliases(DIRFILE *dirfile, const char *field_code);

DESCRIPTION

       The gd_aliases() function queries a dirfile(5) database specified by dirfile and returns a read-only list
       of aliases of the field specified by field_code.

       The dirfile argument must point to a valid DIRFILE object previously created by a call to gd_open(3).

       The  array  returned  will be de-allocated by a call to gd_close(3) and should not be de-allocated by the
       caller.  The list returned should not be assumed to be in any particular order.  The array is  terminated
       by a NULL pointer.  The number of strings in the array can be obtained from a call to gd_naliases(3).

       The  caller  may  not  modify any strings in the array, or the array itself.  Doing so may cause database
       corruption.  The pointer returned is guaranteed to be valid until gd_aliases() is called again  with  the
       same arguments, or until the array is de-allocated by a call to gd_close(3).

RETURN VALUE

       Upon  successful  completion, gd_aliases() returns a pointer to an array of strings containing the values
       of all the aliases for the specified field.  The array is terminated by a NULL pointer.   If  successful,
       this list will always contain at least one entry, to wit: field_code.

       On  error  it  returns  NULL and sets the dirfile error to a non-zero error value.  Possible error values
       are:

       GD_E_ALLOC
               The library was unable to allocate memory.

       GD_E_BAD_CODE
               The specified field code was not found in the database.

       GD_E_BAD_DIRFILE
               The supplied dirfile was invalid.

       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).

HISTORY

       The gd_aliases() function appeared in GetData-0.8.0.

SEE ALSO

       gd_open(3), gd_alias_target(3), gd_naliases(3), dirfile(5)

Version 0.10.0                                  25 December 2016                                   gd_aliases(3)