m + add section 3 man pages

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

1 files changed, 78 insertions, 0 deletions

diff --git a/libcontacts_save_contact.3 b/libcontacts_save_contact.3
new file mode 100644
index 0000000..161e190
--- /dev/null
+++ b/libcontacts_save_contact.3
@@ -0,0 +1,78 @@
+.TH LIBCONTACTS_SAVE_CONTACT 3 LIBCONTACTS
+.SH NAME
+libcontacts_save_contact \- Save a contact
+.SH SYNOPSIS
+.nf
+#include <libcontacts.h>
+
+int libcontacts_save_contact(struct libcontacts_contact *\fIcontact\fP, const struct passwd *\fIuser\fP);
+.fi
+.PP
+Link with
+.IR -lcontacts .
+
+.SH DESCRIPTION
+The
+.BR libcontacts_save_contact ()
+function saves the contact entry that is specified in the
+.I contact
+parameter.
+.PP
+If
+.I contact->id
+is
+.I NULL
+an ID will be assigned to it, and stored in
+.IR contact->id .
+If the call is successful, the caller must manually
+free this ID, if the function
+assignee's it, using the
+.BR free (3)
+function.
+.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.
+
+.SH RETURN VALUE
+The
+.BR libcontacts_save_contact ()
+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_save_contact ()
+function will fail if:
+.TP
+.B 0
+The file it saves contains a NUL byte.
+.PP
+The
+.BR libcontacts_save_contact ()
+function may fail for any reason specified for the
+.BR libcontacts_format_contact (3),
+.BR libcontacts_get_path (3),
+.BR malloc (3),
+.BR open (3)
+(other than
+.IR EEXIST ),
+.BR mkdir (3)
+(other than
+.IR EEXIST ),
+.BR write (3),
+.BR fsync (3),
+and
+.BR rename (3)
+functions.
+
+.SH SEE ALSO
+.BR libcontacts.h (0),
+.BR libcontacts (7),
+.BR libcontacts_load_contact (3),
+.BR libcontacts_loads_contact (3),
+.BR libcontacts_contact_destroy (3),
+.BR libcontacts_format_contact (3)