liblock/liblock.h

   1 /* $Id: liblock.h,v 1.5 2004/10/21 00:10:49 mrsam Exp $ */
   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
 109 } ;
 110 #endif
 111
 112 #endif