Read Me

-*- text -*-

Description
-----------
Simple C library based on libdaemon and popt for starting and stopping
a background process which runs a select(2) loop; hence the library
name libdaemonselect!

Here select(2) refers to synchronous I/O multiplexing function
select(nfds, readfds, writefds, exceptfds, timeout) in section 2 of
the Programmer's Manual, i.e. enter the following to view the
appropriate page.

	man 2 select

Licensing
---------
The library has an LGPL license and entirely uses Open Source-based dependencies.

Example
-------
The idea is this: you write a C or C++ module defining at least three
functions as follows.  Note, if C++ do not forget to include the
extern "C" storage class specification in order to avoid C++ name mangling.

	#include <libdaemonselect/daemon_start_stop.h>
	#include <libdaemonselect/daemon_select.h>

	int
	daemon_start(int argc, char **argv)
	{
	  /*
	   * now do something to START the daemon...
	   */
	  return 0;
	}

	int
	daemon_stop()
	{
	  /*
	   * now do something to STOP the daemon...
	   */
	  return 0;
	}

	void
	daemon_select_read(int fd)
	{
	  /*
	   * now do something to read the file descriptor...
	   */
	}

You then link the module with libdaemonselect, libdaemon and libpopt
using a makefile along the following lines.

	LDLIBS = -ldaemonselect -ldaemon -lpopt

The result is an executable which runs as a background process.  Say
you have called the binary myd, running

	./myd

returns as soon as daemon_start(argc, argv) returns.  However, a daemon process
continues running in the background.  Importantly, the return code
from the above originates from the daemon process (sent through a
pipe).  The new daemon writes its PID to a PID file at
/var/run/myd.pid and you can kill the background process using

	./myd -k

Why Bother?
-----------
Why not just cut-and-paste the daemon-ising code?  Why make it a library?
Well, there are a number of small advantages.  If you plan to run a
number of simple background processes along similar lines, it removes
the duplicated code.  It also means that the daemon-ising library can
alter its behaviour if necessary without recompiling a number of
different daemon programs.  This assumes linkage is dynamic of course.

Why Use C?
----------
C is the natural language for daemon-ising a Unix-like process; the
entire operating system is C software after all.  But there is another
subtlety.  C has a simple scheme for binding names externally, in
comparison with C++ especially.