bionic (3) gd_aliases.3.gz

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)