NAME

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

LIBRARY

     library “libbsd”

SYNOPSIS

     #include <libutil.h>
     (See libbsd(7) for include usage.)

     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(3bsd) 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(3bsd) library function.

SEE ALSO

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

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>.