table of contents
PIDFILE(3) | Library Functions Manual | PIDFILE(3) |
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¶
Thepidfile
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¶
Thepidfile_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 passNULL
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¶
Thepidfile_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.
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
().
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
().
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¶
Thepidfile
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⟩.October 20, 2008 | Debian |