NAME

       genders_nodelist_create,   genders_nodelist_clear,   genders_nodelist_destroy,   genders_attrlist_create,
       genders_attrlist_clear,    genders_attrlist_destroy,    genders_vallist_create,    genders_vallist_clear,
       genders_vallist_destroy - list create, clear, and destroy routines

SYNOPSIS

       #include <genders.h>

       int genders_nodelist_create(genders_t handle, char ***nodelist);

       int genders_nodelist_clear(genders_t handle, char **nodelist);

       int genders_nodelist_destroy(genders_t handle, char **nodelist);

       int genders_attrlist_create(genders_t handle, char ***attrlist);

       int genders_attrlist_clear(genders_t handle, char **attrlist);

       int genders_attrlist_destroy(genders_t handle, char **attrlist);

       int genders_vallist_create(genders_t handle, char ***vallist);

       int genders_vallist_clear(genders_t handle, char **vallist);

       int genders_vallist_destroy(genders_t handle, char **vallist);

DESCRIPTION

       genders_nodelist_create(),              genders_nodelist_clear(),             genders_nodelist_destroy(),
       genders_attrlist_create(),             genders_attrlist_clear(),              genders_attrlist_destroy(),
       genders_vallist_create(),  genders_vallist_clear(),  and  genders_vallist_destroy()  are  used to create,
       clear, and destroy lists (arrays of strings) for use with  genders_getnodes(3),  genders_getattr(3),  and
       genders_getattr_all(3).

       genders_nodelist_create(),  genders_attrlist_create(),  and  genders_vallist_create() creates a list with
       minimum size to store nodes, attributes, and attribute  values  respectively.   nodelist,  attrlist,  and
       vallist are respectively set to point to the created list.  The created lists are guaranteed to store all
       the node, attribute, and value information returned  from  genders_getnodes(3),  genders_getattr(3),  and
       genders_getattr_all(3).

       genders_nodelist_clear(),  genders_attrlist_clear(),  and  genders_vallist_clear()  clear any information
       stored in the lists pointed to by nodelist, attrlist, and vallist  repectively.   They  do  not  have  be
       called  after  their  respective  create  functions.   They only have to be called after they are used in
       genders_getnodes(3), genders_getattr(3), and genders_getattr_all(3), and the programmer wishes to  re-use
       the list.

       genders_nodelist_destroy(),  genders_attrlist_destroy(),  and genders_vallist_destroy() destroy the lists
       pointed to by nodelist, attrlist, and vallist respectively.

       If no attributes or values are listed in the genders database all of the attrlist and  vallist  functions
       will do nothing.  The pointer passed into genders_attrlist_create() and genders_vallist_create() will not
       be set.

RETURN VALUES

       On success, genders_nodelist_create(), genders_attrlist_create(), and genders_vallist_create() return the
       number   of   elements   the   created   list   can   store.    On   success,   genders_nodelist_clear(),
       genders_attrlist_clear(), genders_vallist_clear() genders_nodelist_destroy(), genders_attrlist_destroy(),
       genders_vallist_destroy()  return  0.  On error, -1 is returned, and an error code is returned in handle.
       The error code can be retrieved via genders_errnum(3) , and a  description  of  the  error  code  can  be
       retrieved via genders_strerror(3).  Error codes are defined in genders.h.

ERRORS

       GENDERS_ERR_NULLHANDLE
              The handle parameter is NULL.  The genders handle must be created with genders_handle_create(3).

       GENDERS_ERR_NOTLOADED
              genders_load_data(3)  has  not been called to load genders data.  Before lists of appropriate size
              can be created, the genders file must be read and parsed.

       GENDERS_ERR_PARAMETERS
              An incorrect parameter has been passed in.

       GENDERS_ERR_NULLPTR
              A null pointer has been found in the list passed in.

       GENDERS_ERR_OUTMEM
              malloc(3) has failed internally, system is out of memory.

       GENDERS_ERR_MAGIC
              handle has an incorrect magic number.  handle does not point to a genders  handle  or  handle  has
              been destroyed by genders_handle_destroy(3).

FILES

       /usr/include/genders.h

SEE ALSO

       libgenders(3),  genders_handle_create(3),  genders_load_data(3), genders_getnodes(3), genders_getattr(3),
       genders_getattr_all(3), genders_errnum(3), genders_strerror(3)