From 6546989d280d8fc1e8e2bc152f08d9b04090d4b8 Mon Sep 17 00:00:00 2001
From: Mattias Andrée <maandree@kth.se>
Date: Tue, 13 Apr 2021 17:29:14 +0200
Subject: m + add section 3 man pages
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Signed-off-by: Mattias Andrée <maandree@kth.se>
---
 libcontacts_get_path.3 | 94 ++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 94 insertions(+)
 create mode 100644 libcontacts_get_path.3

(limited to 'libcontacts_get_path.3')

diff --git a/libcontacts_get_path.3 b/libcontacts_get_path.3
new file mode 100644
index 0000000..d1e62f2
--- /dev/null
+++ b/libcontacts_get_path.3
@@ -0,0 +1,94 @@
+.TH LIBCONTACTS_GET_PATH 3 LIBCONTACTS
+.SH NAME
+libcontacts_get_path \- Get the file information for a contact is or would be stored in
+.SH SYNOPSIS
+.nf
+#include <libcontacts.h>
+
+char *libcontacts_get_path(const char *\fIid\fP, const struct passwd *\fIuser\fP);
+.fi
+.PP
+Link with
+.IR -lcontacts .
+
+.SH DESCRIPTION
+The
+.BR libcontacts_get_path ()
+function get the path to the file for the contact with
+the ID specified in the
+.I id
+parameter, neither this file nor its directory need exist
+for successful completion to the place. If
+.I id
+is the empty string, the directory where all contacts is
+returned with a trailing slash
+.RB ( / ).
+.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_get_path ()
+function returns the path the file where the information
+for the specified contact is stored (or if requested,
+the directory where contact files are stored) upon successful
+completion; on failure
+.I NULL
+is returned and
+.I errno
+is set appropriately to indicate the error.
+
+.SH ERRORS
+The
+.BR libcontacts_get_path ()
+function will fail if:
+.TP
+.B EINVAL
+Either parameter is
+.I NULL
+or the home directory field in
+.I user
+is
+.I NULL
+or the empty string.
+.PP
+The
+.BR libcontacts_get_path ()
+function may also fail for any reason specified for the
+.BR malloc (3)
+function.
+
+.SH EXTENDED DESCRIPTION
+All contact file shall be stored in
+.I .config/contacts/
+within the user's home directory. All environment variables
+shall be ignored.
+.PP
+The contact ID
+.RI ( id )
+must not contain slashes, and should ideally only contain
+lower case ASCII letters, ASCII digits, and ASCII hyphens.
+Contact ID's starting with a dot have special meaning,
+currently define ones are:
+.TP
+.B .me
+Contact information for the user.
+.TP
+.B .groups
+Pseudo-contact where groups that how no members can be
+stored.
+.PP
+The contact ID
+.RI ( id )
+must end with a tilde, these are used to write to until
+file system synchronisation has takes place for the file,
+and the file is subsequently renamed.
+
+.SH SEE ALSO
+.BR libcontacts.h (0),
+.BR libcontacts (7),
+.BR libcontacts_load_contact (7),
+.BR libcontacts_save_contact (7)
-- 
cgit v1.2.3-70-g09d2