From 32935ef03767814ef54c4c1905e00e320261c67c Mon Sep 17 00:00:00 2001
From: Laurent Bercot <ska-skaware@skarnet.org>
Date: Tue, 3 Jul 2018 21:38:08 +0000
Subject:  Add some documentation

---
 doc/libnsss/index.html       | 134 +++++++++++++++++++++++++++++++------------
 doc/libnsss/nsss-switch.html |  29 ++++++++++
 doc/libnsss/nsss-unix.html   |  29 ++++++++++
 3 files changed, 156 insertions(+), 36 deletions(-)
 create mode 100644 doc/libnsss/nsss-switch.html
 create mode 100644 doc/libnsss/nsss-unix.html

(limited to 'doc/libnsss')

diff --git a/doc/libnsss/index.html b/doc/libnsss/index.html
index 0307725..ac99e54 100644
--- a/doc/libnsss/index.html
+++ b/doc/libnsss/index.html
@@ -21,23 +21,100 @@
 <h2> General information </h2>
 
 <p>
- <tt>libnsss</tt> is a client library meant to be used by client
-programs needing utmp functionality. It interacts with various
-server-side daemons such as
-<a href="../nsssd-unix.html">nsssd-unix</a>.
+ <tt>libnsss</tt> is the generic name for the nsss client library.
+This library is made of several parts:
+</p>
+
+<ul>
+ <li> <a href="nsss-unix.html">nsss-unix</a>: this is a set of
+functions to access the <tt>/etc/passwd</tt>, <tt>/etc/group</tt>
+and <tt>/etc/shadow</tt> files. </li>
+ <li> <a href="nsss-switch.html">nsss-switch</a>: this is a set of
+functions to connect to a <em>nsssd-service</em> and interact with
+various server-side daemons such as
+<a href="../nsssd-unix.html">nsssd-unix</a> or
+<a href="../nsssd-nslcd.html">nsssd-nslcd</a>. </li>
+ <li> nsss-all: this is a set of
+functions that try connecting to a nsssd service first, and fall
+back to the <a href="nsss-unix.html">nsss-unix</a> implementation
+if the connection fails (no nsssd service is running). </li>
 </p>
 
 <p>
- Application programs can use it directly, but most existing programs
-simply use the standard
+ Both <a href="nsss-unix.html">nsss-unix</a> and
+<a href="nsss-switch.html">nsss-switch</a> are made of two parts:
+</p>
+
+<ul>
+ <li> An internal, clean API, that applications can use directly
+if they include the <tt>nsss/nsss.h</tt> header, or the relevant
+<tt>nsss/nsss-unix.h</tt> or <tt>nsss/nsss-switch.h</tt> header. </li>
+ <li> As a series of thin wrappers around the internal API, an
+implementation of the standard following functions:
+  <ul>
+   <li> endpwent() </li>
+   <li> setpwent() </li>
+   <li> getpwent() </li>
+   <li> getpwent_r() </li>
+   <li> getpwuid() </li>
+   <li> getpwuid_r() </li>
+   <li> getpwnam() </li>
+   <li> getpwnam_r() </li>
+   <li> endgrent() </li>
+   <li> setgrent() </li>
+   <li> getgrent() </li>
+   <li> getgrent_r() </li>
+   <li> getgrgid() </li>
+   <li> getgrgid_r() </li>
+   <li> getgrnam() </li>
+   <li> getgrnam_r() </li>
+   <li> endspent() </li>
+   <li> setspent() </li>
+   <li> getspent() </li>
+   <li> getspent_r() </li>
+   <li> getspnam() </li>
+   <li> getspnam_r() </li>
+  </ul> </li>
+ The functions are prefixed with <tt>nsss_unix_</tt> or
+<tt>nsss_switch_</tt>. For instance, <tt>nsss_unix_getpwnam()</tt>
+is the implementation of <tt>getpwnam()</tt> that uses the
+<tt>/etc/passwd</tt> backend. </li>
+</ul>
+
+<p>
+ nsss-all does not have an internal API. It only contains the
+implementation of the above standard functions, as
+<tt>nsss_all_getpwnam()</tt> and similar.
+</p>
+
+<h2> Compiling </h2>
+
+<p>
+ Application programs can use the internal API directly, or
+the prefixed <tt>nsss_</tt> functions directly. Most programs,
+however, will simply use the standard
 <a href="http://pubs.opengroup.org/onlinepubs/9699919799/basedefs/pwd.h.html">pwd.h</a>,
 <a href="http://pubs.opengroup.org/onlinepubs/9699919799/basedefs/grp.h.html">grp.h</a> or
 <a href="http://man7.org/linux/man-pages/man3/getspnam.3.html">shadow.h</a>
-interfaces, which in nsss are implemented as a series of thin wrappers
-around the nsss library.
+interfaces. nsss provides a version of these standard headers: if an
+application is built with these headers, then <tt>getpwnam()</tt>
+will automatically be aliased to <tt>nsss_all_getpwnam()</tt>, and
+the other functions will be aliased similarly.
 </p>
 
-<h2> Compiling </h2>
+<p>
+ If the NSSS_DISABLE_SWITCH macro is defined before inclusion of the
+nsss headers, then <tt>getpwnam()</tt> will be aliased to
+<tt>nsss_unix_getpwnam()</tt> instead, and the other functions will
+follow the same pattern. If, instead, the NSSS_DISABLE_UNIX macro
+is defined before inclusion of the nsss headers, then <tt>getpwnam()</tt>
+will be aliased to <tt>nsss_switch_getpwnam()</tt>, and the other
+functions will follow the same pattern.
+</p>
+
+<p>
+ So, the proper steps to compile an application with libnsss are:
+</p>
 
 <ul>
  <li> Make sure the nsss headers, as well as the skalibs headers,
@@ -48,6 +125,10 @@ just <tt>#include &lt;pwd.h&gt;</tt>, which will work as long
 as the <tt>nsss/pwd.h</tt> header is accessible in your header
 search path. </li>
  <li> Same thing for <tt>grp.h</tt> and <tt>shadow.h</tt>. </li>
+ <li> If don't want to use the nsss-all implementation of
+"try nsss-switch and fall back to nsss-unix if it fails", then
+compile with -DNSSS_DISABLE_SWITCH or -DNSSS_DISABLE_UNIX as
+desired. </li>
 </ul>
 
 <h2> Linking </h2>
@@ -63,35 +144,16 @@ sysdeps directory. </li>
 
 <h2> Programming </h2>
 
-<p>
- The <tt>nsss/nsss.h</tt> header is actually a collection of headers:
-</p>
-
 <ul>
- <li> <tt>nsss/nsss-unix.h</tt> implements basic access to the
-<tt>/etc/passwd</tt>, <tt>/etc/group</tt> and <tt>/etc/shadow</tt>
-database. </li>
- <li> <tt>nsss/nsss-switch.h</tt> implements connection via a Unix
-domain socket to a listening <tt>nsssd</tt> daemon, implementing an
-authentication backend based on what implementation of
-the daemon is listening. </li>
- <li> <tt>nsss/nsss-all.h</tt> implements a safe policy: first a
-connection via <tt>nsss-switch</tt> is attempted, and if no daemon
-is listening, the safe <tt>nsss-unix</tt> backend is used. </li>
+ <li> nsss-all, nsss-switch and nsss-unix implement the
+<a href="http://pubs.opengroup.org/onlinepubs/9699919799/functions/getpwnam.html">POSIX
+layer</a> of user database access, plus a few
+<a href="http://man7.org/linux/man-pages/man3/getpwent_r.3.html">GNU extensions</a>. </li>
+ <li> The <a href="nsss-unix.html">nsss/nsss-unix.h</a> header
+can be used to access the internal nsss-unix API. </li>
+ <li> The <a href="nsss-switch.html">nsss/nsss-switch.h</a> header
+can be used to access the internal nsss-switch API. </li>
 </ul>
 
-<p>
- By default, the <tt>getpwnam()</tt> et al. functions are aliased
-to their <tt>nsss-all</tt> implementations. You can disable the
-<tt>nsss-unix</tt> fallback by compiling with the NSSS_DISABLE_UNIX
-macro defined (-DNSSS_DISABLE_UNIX). Or you can disable any
-attempt to connect to a daemon by compiling with the
-NSSS_DISABLE_SWITCH macro defined (-DNSSS_DISABLE_SWITCH).
-</p>
-
-<p>
- (To be completed.)
-</p>
-
 </body>
 </html>
diff --git a/doc/libnsss/nsss-switch.html b/doc/libnsss/nsss-switch.html
new file mode 100644
index 0000000..224cea6
--- /dev/null
+++ b/doc/libnsss/nsss-switch.html
@@ -0,0 +1,29 @@
+<html>
+  <head>
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <meta http-equiv="Content-Type" content="text/html; charset=UTF-8" />
+    <meta http-equiv="Content-Language" content="en" />
+    <title>nsss: the nsss-switch library interface</title>
+    <meta name="Description" content="nsss: the nsss-switch library interface" />
+    <meta name="Keywords" content="NSS pwd group shadow library libnsss switch nsss-switch client server nsssd backend connection socket skarnet" />
+    <!-- <link rel="stylesheet" type="text/css" href="//skarnet.org/default.css" /> -->
+  </head>
+<body>
+
+<p>
+<a href="index.html">libnsss</a><br />
+<a href="../">nsss</a><br />
+<a href="//skarnet.org/software/">Software</a><br />
+<a href="//skarnet.org/">skarnet.org</a>
+</p>
+
+<h1> The <tt>nsss-switch</tt> library interface </h1>
+
+<h2> General information </h2>
+
+<h2> Programming </h2>
+
+<p> TODO: to be completed. </p>
+
+</body>
+</html>
diff --git a/doc/libnsss/nsss-unix.html b/doc/libnsss/nsss-unix.html
new file mode 100644
index 0000000..b51985b
--- /dev/null
+++ b/doc/libnsss/nsss-unix.html
@@ -0,0 +1,29 @@
+<html>
+  <head>
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <meta http-equiv="Content-Type" content="text/html; charset=UTF-8" />
+    <meta http-equiv="Content-Language" content="en" />
+    <title>nsss: the nsss-unix library interface</title>
+    <meta name="Description" content="nsss: the nsss-unix library interface" />
+    <meta name="Keywords" content="NSS pwd group shadow library libnsss unix nsss-unix files /etc/passwd /etc/group /etc/shadow skarnet" />
+    <!-- <link rel="stylesheet" type="text/css" href="//skarnet.org/default.css" /> -->
+  </head>
+<body>
+
+<p>
+<a href="index.html">libnsss</a><br />
+<a href="../">nsss</a><br />
+<a href="//skarnet.org/software/">Software</a><br />
+<a href="//skarnet.org/">skarnet.org</a>
+</p>
+
+<h1> The <tt>nsss-unix</tt> library interface </h1>
+
+<h2> General information </h2>
+
+<h2> Programming </h2>
+
+<p> TODO: to be completed. </p>
+
+</body>
+</html>
-- 
cgit v1.3.1