m + add section 3 man pages

Signed-off-by: Mattias Andrée <maandree@kth.se>

1 files changed, 67 insertions, 0 deletions

diff --git a/libcontacts_list_contacts.3 b/libcontacts_list_contacts.3
new file mode 100644
index 0000000..abe4365
--- /dev/null
+++ b/libcontacts_list_contacts.3
@@ -0,0 +1,67 @@
+.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)