NAME

       pidfile_open, pidfile_write, pidfile_close, pidfile_remove — library for PID files handling

LIBRARY

       library “libbsd”

SYNOPSIS

       #include <bsd/libutil.h>

       struct pidfh *
       pidfile_open(const char *path, mode_t mode, pid_t *pidptr);

       int
       pidfile_write(struct pidfh *pfh);

       int
       pidfile_close(struct pidfh *pfh);

       int
       pidfile_remove(struct pidfh *pfh);

DESCRIPTION

       The  pidfile family of functions allows daemons to handle PID files.  It uses flopen(3) to lock a pidfile
       and detect already running daemons.

       The pidfile_open() function opens (or creates) a file specified by the path argument and locks it.  If  a
       file  can  not be locked, a PID of an already running daemon is returned in the pidptr argument (if it is
       not NULL).  The function does not write process' PID into the  file  here,  so  it  can  be  used  before
       fork()ing  and  exit  with  a  proper  error  message  when  needed.   If  the  path  argument  is  NULL,
       /var/run/⟨progname⟩.pid file will be used.

       The pidfile_write() function writes process' PID into a previously opened file.

       The pidfile_close() function closes a pidfile.  It should be used after daemon fork()s to start  a  child
       process.

       The pidfile_remove() function closes and removes a pidfile.

RETURN VALUES

       The  pidfile_open() function returns a valid pointer to a pidfh structure on success, or NULL if an error
       occurs.  If an error occurs, errno will be set.

       The pidfile_write(), pidfile_close(), and pidfile_remove() functions return the value  0  if  successful;
       otherwise the value -1 is returned and the global variable errno is set to indicate the error.

EXAMPLES

       The  following example shows in which order these functions should be used.  Note that it is safe to pass
       NULL to pidfile_write(), pidfile_remove() and pidfile_close() functions.

       struct pidfh *pfh;
       pid_t otherpid, childpid;

       pfh = pidfile_open("/var/run/daemon.pid", 0600, &otherpid);
       if (pfh == NULL) {
               if (errno == EEXIST) {
                       errx(EXIT_FAILURE, "Daemon already running, pid: %jd.",
                           (intmax_t)otherpid);
               }
               /* If we cannot create pidfile from other reasons, only warn. */
               warn("Cannot open or create pidfile");
       }

       if (daemon(0, 0) == -1) {
               warn("Cannot daemonize");
               pidfile_remove(pfh);
               exit(EXIT_FAILURE);
       }

       pidfile_write(pfh);

       for (;;) {
               /* Do work. */
               childpid = fork();
               switch (childpid) {
               case -1:
                       syslog(LOG_ERR, "Cannot fork(): %s.", strerror(errno));
                       break;
               case 0:
                       pidfile_close(pfh);
                       /* Do child work. */
                       break;
               default:
                       syslog(LOG_INFO, "Child %jd started.", (intmax_t)childpid);
                       break;
               }
       }

       pidfile_remove(pfh);
       exit(EXIT_SUCCESS);

ERRORS

       The pidfile_open() function will fail if:

       [EEXIST]           Some process already holds the lock on the given pidfile, meaning  that  a  daemon  is
                          already running.

       [ENAMETOOLONG]     Specified pidfile's name is too long.

       [EINVAL]           Some  process  already holds the lock on the given pidfile, but PID read from there is
                          invalid.

       [EAGAIN]           Some process already holds the lock on the given pidfile, but the file  is  truncated.
                          Most likely, the existing daemon is writing new PID into the file.

       The  pidfile_open()  function  may  also  fail  and  set errno for any errors specified for the fstat(2),
       open(2), and read(2) calls.

       The pidfile_write() function will fail if:

       [EINVAL]           Improper function use.  Probably called before pidfile_open().

       The pidfile_write() function may also fail and set errno for  any  errors  specified  for  the  fstat(2),
       ftruncate(2), and write(2) calls.

       The  pidfile_close()  function  may  fail  and  set  errno  for any errors specified for the close(2) and
       fstat(2) calls.

       The pidfile_remove() function will fail if:

       [EINVAL]           Improper  function  use.   Probably  called  not   from   the   process   which   made
                          pidfile_write().

       The  pidfile_remove()  function  may  also  fail and set errno for any errors specified for the close(2),
       fstat(2), write(2), and unlink(2) system calls and the flopen(3) library function.

SEE ALSO

       open(2), daemon(3), flopen(3)

AUTHORS

       The pidfile functionality is based on ideas from John-Mark Gurney <jmg@FreeBSD.org>.

       The code and manual page was written by Pawel Jakub Dawidek <pjd@FreeBSD.org>.

Debian                                          October 20, 2008                                      PIDFILE(3)