From 32935ef03767814ef54c4c1905e00e320261c67c Mon Sep 17 00:00:00 2001 From: Laurent Bercot Date: Tue, 3 Jul 2018 21:38:08 +0000 Subject: Add some documentation --- doc/libnsssd/index.html | 102 ++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 102 insertions(+) create mode 100644 doc/libnsssd/index.html (limited to 'doc/libnsssd/index.html') diff --git a/doc/libnsssd/index.html b/doc/libnsssd/index.html new file mode 100644 index 0000000..ec2c5d4 --- /dev/null +++ b/doc/libnsssd/index.html @@ -0,0 +1,102 @@ + + + + + + nsss: the nsssd library interface + + + + + + +

+nsss
+Software
+skarnet.org +

+ +

The `nsssd` library interface

+ +

General information

+ +

+ libnsssd is a library that can be used by external applications +to implement extra nsss backends, in the style of +nsssd-unix and +nsssd-nslcd, without learning the +details of the nsss protocol or having to perform IO themselves. +

+ +

Compiling

+ +

Make sure the nsss headers, as well as the skalibs headers, +are visible in your header search path.
Use #include <skalibs/strerr2.h> and +#include <nsss/nsssd.h>

+ +

Linking

+ +

Make sure the nsssd library, as well as the skalibs library, +are visible in your library search path.
Link against -lnsssd, -lskarnet,

`cat $SYSDEPS/socket.lib`

`cat $SYSDEPS/tainnow.lib`

+ +

Programming

+ +

In your main() function, start with assigning +the name of your program to the PROG variable. Example: +PROG = "nsssd-foobar";
Your main() function can parse options and +take command line arguments as it sees fit. But once it's done +parsing options, give control to the nsssd_main() +function, using your argv and envp as +arguments: return nsssd_main(argv, envp);

+ +

+ The rest of your program should implement the functions needed by +nsssd_main(). Here is what those functions are: +

+ +

`void *nsssd_handle_init (void)`

+This function must return a pointer to an uninitialized +handle. The handle can be whatever you need to implement your +backend; the pointer to your handle will be passed to every +subsequent function. The function must not return NULL. +

+ +

`int nsssd_handle_start (void handle, char const const argv, char const const *envp)`

+This function must initialize the handle. The arguments +it receives are the argv and envp that have been +passed to nsssd_main(). This allows you to write daemons +that can be somewhat configured via the command line: it is how +nsssd-nslcd takes an argument +telling it where the nslcd socket is, and uses that argument in +its own nsssd_handle_start to actually connect to the +nslcd daemon.
+The function must return nonzero if it succeeds, and 0 if it +fails, setting errno appropriately. +

+ +

`void nsssd_handle_end (void *handle)`

+This function must deinitialize the handle and free all +related resources: close connections to external processes, etc. +

+ +

+ TODO: to be completed. +

+ + + -- cgit v1.2.3

The nsssd library interface