pidfile (3) - Linux Manuals
NAME
pidfile_open pidfile_write pidfile_close pidfile_remove - library for PID files handling
LIBRARY
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 jmg [at] FreeBSD.org .The code and manual page was written by An Pawel Jakub Dawidek Aq pjd [at] FreeBSD.org .