NAME
pidfile_open, pidfile_write, pidfile_close, pidfile_remove, pidfile_fileno — library for PID files handlingLIBRARY
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); int
pidfile_fileno(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 pidptr argument is notNULL
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, orNULL
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. The pidfile_fileno() function returns the low-level file descriptor. It returns
-1
and sets
errno if a NULL
pidfh is specified, or if the pidfile is no
longer open.
EXAMPLES
The following example shows in which order these functions should be used. Note that it is safe to passNULL
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 EINVAL. */ } 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. - [
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.
- [
EINVAL
] - Improper function use. Probably called before pidfile_open().
- [
EINVAL
] - Improper function use. Probably called not from the process which made pidfile_write().
- [
EINVAL
] - Improper function use. Probably called not from the process which used pidfile_open().
SEE ALSO
open(2), daemon(3), flopen(3bsd)AUTHORS
The pidfile functionality is based on ideas from John-Mark Gurney <[email protected]>. The code and manual page was written by Pawel Jakub Dawidek <[email protected]>.February 8, 2012 | Debian |