Other Alias
pidfile_open, pidfile_close, pidfile_removeLIBRARY
Lb libbsdSYNOPSIS
In bsd/libutil.h Ft struct pidfh * Fn pidfile_open const char *path mode_t mode pid_t *pidptr Ft int Fn pidfile_write struct pidfh *pfh Ft int Fn pidfile_close struct pidfh *pfh Ft int Fn pidfile_remove struct pidfh *pfhDESCRIPTION
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 Fn pidfile_open function opens (or creates) a file specified by the Fa path argument and locks it. If a file can not be locked, a PID of an already running daemon is returned in the Fa pidptr argument (if it is not NULL ) The function does not write process' PID into the file here, so it can be used before Fn fork Ns ing and exit with a proper error message when needed. If the Fa path argument is NULL /var/run/ Ao progname Ac .pid file will be used.
The Fn pidfile_write function writes process' PID into a previously opened file.
The Fn pidfile_close function closes a pidfile. It should be used after daemon Fn fork Ns s to start a child process.
The Fn pidfile_remove function closes and removes a pidfile.
RETURN VALUES
The Fn pidfile_open function returns a valid pointer to a Vt pidfh structure on success, or NULL if an error occurs. If an error occurs, errno will be set.Rv -std pidfile_write pidfile_close pidfile_remove
EXAMPLES
The following example shows in which order these functions should be used. Note that it is safe to pass NULL to Fn pidfile_write , Fn pidfile_remove and Fn 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 Fn pidfile_open function will fail if:- Bq Er EEXIST
- Some process already holds the lock on the given pidfile, meaning that a daemon is already running.
- Bq Er ENAMETOOLONG
- Specified pidfile's name is too long.
- Bq Er EINVAL
- Some process already holds the lock on the given pidfile, but PID read from there is invalid.
- Bq Er 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 Fn pidfile_open function may also fail and set errno for any errors specified for the fstat(2), open(2), and read(2) calls.
The Fn pidfile_write function will fail if:
- Bq Er EINVAL
- Improper function use. Probably called before Fn pidfile_open .
The Fn pidfile_write function may also fail and set errno for any errors specified for the fstat(2), ftruncate(2), and write(2) calls.
The Fn pidfile_close function may fail and set errno for any errors specified for the close(2) and fstat(2) calls.
The Fn pidfile_remove function will fail if:
- Bq Er EINVAL
- Improper function use. Probably called not from the process which made Fn pidfile_write .
The Fn 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.
AUTHORS
An -nosplit The pidfile functionality is based on ideas from An John-Mark Gurney Aq [email protected] .The code and manual page was written by An Pawel Jakub Dawidek Aq [email protected] .