[hcoop/debian/courier-authlib.git] / liblock / liblock.h

/* $Id: liblock.h,v 1.6 2009/06/27 16:32:38 mrsam Exp $ */

#ifndef liblock_h
#define liblock_h

/*
** Copyright 1998 - 1999 Double Precision, Inc.  See COPYING for
** distribution information.
*/

#ifdef	__cplusplus
extern "C" {
#endif

#include	<sys/types.h>

#ifndef liblock_config_h
#if	HAVE_CONFIG_H
#include	"config.h"
#endif
#endif

#define	ll_whence_start	0
#define	ll_whence_curpos 1
#define	ll_whence_end 2

#define	ll_readlock	0
#define	ll_writelock	4
#define	ll_unlock	8
#define	ll_wait		16

int	ll_lockfd(int,	/* File descriptor */
		int,	/* ll_ bitmask */
		LL_OFFSET_TYPE,	/* Start */
		LL_OFFSET_TYPE);	/* Length */


/* Some useful macros: ll_lock_ex - exclusive lock on a file,
		ll_lock_ex_test - attempt an exclusive lock on a file
		ll_unlock_ex - unlock a file
*/

#define	ll_lock_ex(f)	\
	ll_lockfd( (f), ll_writelock|ll_whence_start|ll_wait, 0, 0)

#define	ll_lock_ex_test(f)	\
	ll_lockfd( (f), ll_writelock|ll_whence_start, 0, 0)

#define	ll_unlock_ex(f)	\
	ll_lockfd( (f), ll_unlock|ll_whence_start, 0, 0)


/*
** Value-added: functions that reliably start and stop a daemon process,
** permitting only one daemon process running.  Utilizes a lock file, and a
** pidfile.
*/

int ll_daemon_start(const char *lockfile);
void ll_daemon_started(const char *pidfile, int fd);
int ll_daemon_resetio();
int ll_daemon_stop(const char *lockfile, const char *pidfile);
int ll_daemon_restart(const char *lockfile, const char *pidfile);

/*
  The basic scenario

main()
{
    if ((fd=ll_daemon_start(lockfilename)) < 0)
    {
           error();  exit(1);
    }

    ... Some custom initialization here ...

    ll_daemon_started(pidfile, fd);

    ll_daemon_resetio();   ... this one is optional
}

To stop this daemon:

ll_daemon_stop (lockfilename, pidfile)


ll_daemon_start attempts to start a daemon process going.  It does only
a partial setup.  If it detects that the daemon process is already
running, it itself does an exit(0), not returning to the parent.

If there was a failure starting a daemon process, -1 is return, else
we return a transparent file descriptor, which will have to be passed as
the secodn argument to ll_daemon_started().

When ll_daemon_start returns, we're already running in a partially set-up
daemon process.  The setup isn't complete just yet.  The parent function
can perform any other custom initialization.  If initialization fails,
the parent function can simply exit.  Otherwise, if the initialization
completes, ll_daemon_started must be called in order to save this daemon
process's pid in the pid file (2nd arg must be the return from ll_daemon_start.

To stop a daemon process, simply call ll_daemon_stop.  Nothing too
sophisticated here.

To send the daemon process a SIGHUP, call ll_daemon_restart.
*/

#ifdef	__cplusplus
}
#endif

#endif
Commit	Line	Data
8d138742	1	/* $Id: liblock.h,v 1.6 2009/06/27 16:32:38 mrsam Exp $ */
d9898ee8	2
	3	#ifndef liblock_h
	4	#define liblock_h
	5
	6	/*
	7	** Copyright 1998 - 1999 Double Precision, Inc. See COPYING for
	8	** distribution information.
	9	*/
	10
	11	#ifdef __cplusplus
	12	extern "C" {
	13	#endif
	14
	15	#include <sys/types.h>
	16
	17	#ifndef liblock_config_h
	18	#if HAVE_CONFIG_H
	19	#include "config.h"
	20	#endif
	21	#endif
	22
	23	#define ll_whence_start 0
	24	#define ll_whence_curpos 1
	25	#define ll_whence_end 2
	26
	27	#define ll_readlock 0
	28	#define ll_writelock 4
	29	#define ll_unlock 8
	30	#define ll_wait 16
	31
	32	int ll_lockfd(int, /* File descriptor */
	33	int, /* ll_ bitmask */
	34	LL_OFFSET_TYPE, /* Start */
	35	LL_OFFSET_TYPE); /* Length */
	36
	37
	38	/* Some useful macros: ll_lock_ex - exclusive lock on a file,
	39	ll_lock_ex_test - attempt an exclusive lock on a file
	40	ll_unlock_ex - unlock a file
	41	*/
	42
	43	#define ll_lock_ex(f) \
	44	ll_lockfd( (f), ll_writelock\|ll_whence_start\|ll_wait, 0, 0)
	45
	46	#define ll_lock_ex_test(f) \
	47	ll_lockfd( (f), ll_writelock\|ll_whence_start, 0, 0)
	48
	49	#define ll_unlock_ex(f) \
	50	ll_lockfd( (f), ll_unlock\|ll_whence_start, 0, 0)
	51
	52
	53	/*
	54	** Value-added: functions that reliably start and stop a daemon process,
	55	** permitting only one daemon process running. Utilizes a lock file, and a
	56	** pidfile.
	57	*/
	58
	59	int ll_daemon_start(const char *lockfile);
	60	void ll_daemon_started(const char *pidfile, int fd);
	61	int ll_daemon_resetio();
	62	int ll_daemon_stop(const char lockfile, const char pidfile);
	63	int ll_daemon_restart(const char lockfile, const char pidfile);
	64
	65	/*
66	The basic scenario
67
68	main()
69	{
70	if ((fd=ll_daemon_start(lockfilename)) < 0)
71	{
72	error(); exit(1);
73	}
74
75	... Some custom initialization here ...
76
77	ll_daemon_started(pidfile, fd);
78
79	ll_daemon_resetio(); ... this one is optional
80	}
81
82	To stop this daemon:
83
84	ll_daemon_stop (lockfilename, pidfile)
85
86
87	ll_daemon_start attempts to start a daemon process going. It does only
88	a partial setup. If it detects that the daemon process is already
89	running, it itself does an exit(0), not returning to the parent.
90
91	If there was a failure starting a daemon process, -1 is return, else
92	we return a transparent file descriptor, which will have to be passed as
93	the secodn argument to ll_daemon_started().
94
95	When ll_daemon_start returns, we're already running in a partially set-up
96	daemon process. The setup isn't complete just yet. The parent function
97	can perform any other custom initialization. If initialization fails,
98	the parent function can simply exit. Otherwise, if the initialization
99	completes, ll_daemon_started must be called in order to save this daemon
100	process's pid in the pid file (2nd arg must be the return from ll_daemon_start.
101
102	To stop a daemon process, simply call ll_daemon_stop. Nothing too
103	sophisticated here.
104
105	To send the daemon process a SIGHUP, call ll_daemon_restart.
106	*/
107
108	#ifdef __cplusplus
8d138742	109	}
d9898ee8	110	#endif
	111
	112	#endif