1 files changed, 69 insertions, 0 deletions
diff --git a/libenv_get_chosen_list.3 b/libenv_get_chosen_list.3
new file mode 100644
index 0000000..0b87403
--- /dev/null
+++ b/libenv_get_chosen_list.3
@@ -0,0 +1,69 @@
+.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).