Manpages - pidfile.3bsd

(See

for include usage.)

The

family of functions allows daemons to handle PID files. It uses

to lock a pidfile and detect already running daemons.

The

function opens (or creates) a file specified by the

argument and locks it. If

argument is not

and file can not be locked, the function will use it to store a PID of an already running daemon or

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

and exit with a proper error message when needed. If the

argument is

file will be used. The

function sets the O_CLOEXEC close-on-exec flag when opening the pidfile.

The

function writes process’ PID into a previously opened file. The file is truncated before write, so calling the

function multiple times is supported.

The

function closes a pidfile. It should be used after daemon

to start a child process.

The

function closes and removes a pidfile.

The

function returns the file descriptor for the open pidfile.

The

function returns a valid pointer to a

structure on success, or

if an error occurs. If an error occurs,

will be set.

The

function returns the low-level file descriptor. It returns

and sets

if a NULL

is specified, or if the pidfile is no longer open.

The following example shows in which order these functions should be used. Note that it is safe to pass

to

and

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);

The

function will fail if:

Some process already holds the lock on the given pidfile, meaning that a daemon is already running. If

argument is not

the function will use it to store a PID of an already running daemon or

in case daemon did not write its PID yet.

Specified pidfile’s name is too long.

Some process already holds the lock on the given pidfile, but PID read from there is invalid.

The

function may also fail and set

for any errors specified for the

and

calls.

The

function will fail if:

Improper function use. Probably called before

The

function may also fail and set

for any errors specified for the

and

calls.

The

function may fail and set

for any errors specified for the

and

calls.

The

function will fail if:

Improper function use. Probably called not from the process which made

The

function may also fail and set

for any errors specified for the

and

system calls and the

library function.

The

function will fail if:

Improper function use. Probably called not from the process which used

The

functionality is based on ideas from

The code and manual page was written by