FreeBSD manual
download PDF document: pidfile.3.pdf
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 <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);
int
pidfile_fileno(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 pidptr argument is not NULL and file can
not be locked, the function will use it to store a PID of an already
running daemon or -1 in case daemon did not write its PID yet. 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_open() function sets the O_CLOEXEC close-on-exec flag when
opening the pidfile.
The pidfile_write() function writes process' PID into a previously opened
file. The file is truncated before write, so calling the pidfile_write()
function multiple times is supported.
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.
The pidfile_fileno() function returns the file descriptor for the open
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
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(), pidfile_close() and pidfile_fileno() 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");
/*
* Even though pfh is NULL we can continue, as the other pidfile_*
* function can handle such situation by doing nothing except setting
* errno to EDOOFUS.
*/
}
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. If
pidptr argument is not NULL the function will use it
to store a PID of an already running daemon or -1 in
case daemon did not write its PID yet.
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
specified 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), fstat(2), write(2), and unlink(2) system
calls and the flopen(3) library function.
The pidfile_fileno() function will fail if:
[EDOOFUS] Improper function use. Probably called not from the
process which used pidfile_open().
SEE ALSO
open(2), daemon(3), flopen(3)
HISTORY
The functions pidfile_open(), pidfile_write(), pidfile_close() and
pidfile_remove() first appeared in FreeBSD 5.5.
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 14.0-RELEASE-p6 May 10, 2020 FreeBSD 14.0-RELEASE-p6