pidfile(3)

NAME

pidfile_open, pidfile_write, pidfile_close, pidfile_remove

library for
PID files handling

LIBRARY

System Utilities Library (libutil, -lutil)

SYNOPSIS

#include <sys/param.h>
#include <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

The pidfile family of functions allows daemons to handle PID

files. It
uses flock(2) to lock a pidfile and detect already running

daemons.

The pidfile_open() function opens (or creates) a file speci

fied by the
path argument and locks it with the flock(2) system call.

If a file can
not be locked, a PID of an already running daemon is re

turned 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 argu

ment is NULL,
/var/run/<progname>.pid file will be used.

The pidfile_write() function writes process' PID into a pre

viously 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

The pidfile_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() function returns the value 0 if success

ful; 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.

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: %d.", 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.", str

error(errno));
break;

case 0:

pidfile_close(pfh);
/* Do child work. */
break;

default:

syslog(LOG_INFO, "Child %d started.", child

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

file, 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 pid

file, but PID read from there is invalid.

The 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:

[EDOOFUS] Improper function use. Probably called

before

pidfile_open().

The 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:

[EDOOFUS] Improper function use. Probably called

not from the

process which made pidfile_write().

The pidfile_remove() function may also fail and set errno

for any errors
specified for the close(2), flock(2), fstat(2), write(2),

and unlink(2)
calls.

SEE ALSO

flock(2), open(2), daemon(3)

AUTHORS

The pidfile 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>.

BSD August 22, 2005

BSD