NAME

       gd_mvector_list — retrieve a list of vector fields in a dirfile

SYNOPSIS

       #include <getdata.h>

       const char **gd_mvector_list(DIRFILE *dirfile, const char *parent);

DESCRIPTION

       The  gd_mvector_list()  function  queries  a  dirfile(5) database specified by dirfile and
       returns a read-only list of names of the all vector  type  metafields  for  the  specified
       parent     field     defined     in     the    database    (i.e.     fields    of    types
       BIT, LINCOM, LINTERP, MULTIPLY, PHASE, POLYNOM, RAW, SBIT).

       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_nmvectors(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_mvector_list() 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_mvector_list()  returns a pointer to an array of strings
       containing the names of all the vector metafields for the given parent field.  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 supplied parent field code was not found, or referred to a metafield itself.

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

SEE ALSO

       dirfile(5),     gd_open(3),     gd_error(3),     gd_error_string(3),    gd_mfield_list(3),
       gd_nmetavectors(3), gd_vector_list(3)