.TH LIBENV_GET_CHOSEN_LIST 3 libenv
.SH NAME
libenv_get_chosen_list - List recognised environment variables by class

.SH SYNOPSIS
.nf
#include <libenv.h>

const char **libenv_get_chosen_list(enum libenv_class, ... /*, LIBENV_END */);
const char **libenv_vget_chosen_list(enum libenv_class, va_list);
.fi
.PP
Link with
.IR -lenv .

.SH DESCRIPTION
The
.BR libenv_get_chosen_list ()
function returns a
.I NULL
terminated list of the names of all environment variables, that it knows of,
regardless if they are set in the environemnt, and that belong to at least
one of the environment variable classes listed in the functions argument list.
The argument list must be termianted with
.I LIBENV_END
so that the function knonws when there are no more arguments to read.
.PP
The
.BR libenv_vget_chosen_list ()
function is a variant of the
.BR libenv_get_chosen_list ()
function that uses
.I va_list
rather than being properly variadic.

.SH RETURN VALUE
Upon successful completion, the
.BR libenv_get_chosen_list ()
and
.BR libenv_vget_chosen_list ()
functions return a
.IR NULL -
terminated list of statically allocated
strings, representing environment variable names.
The returned list, but not it's element, shall
be deallocated using the
.BR free (3)
function. On failure
.I NULL
is returned and
.I errno
is appropriately set to describe the error.

.SH ERRORS
The
.BR libenv_get_chosen_list ()
and
.BR libenv_vget_chosen_list ()
functions may fail if:
.TP
.B ENOMEM
Insufficient memory available.

.SH SEE ALSO
.BR libenv (7),
.BR enum_libenv_class (3),
.BR libenv_get_complete_list (3),
.BR libenv_filter_variable_list (3),
.BR libenv_select_variable_list (3).