pidfile_open (3)

Leading comments

Copyright (c) 2005 Pawel Jakub Dawidek <pjd@FreeBSD.org>
All rights reserved.

Redistribution and use in source and binary forms, with or without
modification, are permitted provided that the following conditions
are met:
1. Redistributions of source code must retain the above copyright
   notice, this list of conditions and the following disclaimer.
2. Redistributions in binary form must reproduce the above copyright
   notice, this list of conditions and the following disclaimer in the
   d...

(The comments found at the beginning of the groff file "man3/pidfile_open.3bsd".)

NAME

pidfile_open pidfile_write pidfile_close pidfile_remove - library for PID files handling

LIBRARY

Lb libbsd

SYNOPSIS

In libutil.h (See libbsd(7) for include usage.) 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 *pfh

DESCRIPTION

The pidfile family of functions allows daemons to handle PID files. It uses flopen(3bsd) 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(3bsd) library function.

SEE ALSO

open(2), daemon(3), flopen(3bsd)

AUTHORS

An -nosplit The pidfile functionality is based on ideas from An John-Mark Gurney Aq jmg@FreeBSD.org .

The code and manual page was written by An Pawel Jakub Dawidek Aq pjd@FreeBSD.org .