Skip site navigation (1)Skip section navigation (2)

FreeBSD Man Pages

Man Page or Keyword Search:
Man Architecture
Apropos Keyword Search (all sections) Output format
home | help
PIDFILE(3)             FreeBSD Library Functions Manual             PIDFILE(3)

NAME
     pidfile_open, pidfile_write, pidfile_close, pidfile_remove -- library for
     PID files handling

LIBRARY
     System Utilities Library (libutil, -lutil)

SYNOPSIS
     #include <sys/param.h>
     #include <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 flock(2) 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 with the flock(2) system call.  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.

     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: %d.", 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 %d started.", 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 pid-
                        file, 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 pid-
                        file, but PID read from there is invalid.

     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:

     [EDOOFUS]          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 speci-
     fied for the close(2) and fstat(2) calls.

     The pidfile_remove() function will fail if:

     [EDOOFUS]          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), flock(2), fstat(2), write(2), and unlink(2)
     calls.

SEE ALSO
     flock(2), open(2), daemon(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>.

FreeBSD 6.2                     August 22, 2005                    FreeBSD 6.2

NAME | LIBRARY | SYNOPSIS | DESCRIPTION | RETURN VALUES | EXAMPLES | ERRORS | SEE ALSO | AUTHORS

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=pidfile&sektion=3&manpath=FreeBSD+6.2-RELEASE>

home | help