path: root/libcontacts_list_contacts.3

.TH LIBCONTACTS_LIST_CONTACTS 3 LIBCONTACTS
.SH NAME
libcontacts_list_contacts \- Get a list of all contacts
.SH SYNOPSIS
.nf
#include <libcontacts.h>

int libcontacts_list_contacts(char ***\fIidsp\fP, const struct passwd *\fIuser\fP, int \fIwith_me\fP);
.fi
.PP
Link with
.IR -lcontacts .

.SH DESCRIPTION
The
.BR libcontacts_list_contacts ()
function create a
.IR NULL -termianted
list of all regular contact entries and stores it in
.I *idsp
upon successful completion. If
.I with_me
is non-zero, the
.B .me
entry will also be included, if it exists.
.PP
.I user
shall be the user's entry in the password database (not
the shadow database). This is used for the get user's
home directory.
.PP
When no longer needed, the caller shall manually
deallocate all elements in
.I *idsp
along with
.I *idsp
itself, using the
.BR free (3)
function.

.SH RETURN VALUE
The
.BR libcontacts_list_contacts ()
function returns 0 upon successful completion;
otherwise -1 is returned and
.I errno
is set appropriately to indicate the error.

.SH ERRORS
The
.BR libcontacts_list_contacts ()
function may fail for any reason specified for the
.BR libcontacts_get_path (3),
.BR opendir (3)
(other than
.IR ENOENT ),
.BR realloc (3),
and
.BR readdir (3)
functions.

.SH SEE ALSO
.BR libcontacts.h (0),
.BR libcontacts (7),
.BR libcontacts_get_path (3),
.BR libcontacts_load_contact (3),
.BR libcontacts_load_contacts (3)