PIDFILE(3)

PIDFILE(3) | Library Functions Manual | PIDFILE(3)

# NAME

pidfile — write a daemon pid file

# LIBRARY

System Utilities Library (libutil, -lutil)

# SYNOPSIS

#include <util.h>
int
pidfile(const char *path);
pid_t
pidfile_lock(const char *path);
pid_t
pidfile_read(const char *path);
int
pidfile_clean(void);

# DESCRIPTION

pidfile() and pidfile_lock() create and lock a file containing the process ID of the calling program. The pid file can be used as a quick reference if the process needs to be sent a signal. The pid file is truncated and removed automatically when the program exits, unless the program receives a fatal signal.
If path is `NULL` or a plain basename (a name containing no directory components), the pid file is created in the /var/run directory. The file name has the form /var/run/basename.pid. The basename part is either the value of path if it was not `NULL`, or the program name as returned by getprogname(3) otherwise.
If path is an absolute or relative path (i.e. it contains the ‘/’ character), the pid file is created in the provided location.
If called with a new path, pidfile() and pidfile_lock() will remove the old pid file.
The pid file is truncated, so these functions can be called multiple times and allow a child process to take over the lock.
pidfile_read() will read the last pid file created, or specified by path, and return the process ID it contains.
pidfile_clean() will ftruncate(2), close(2), and unlink(2) the last opening pid file if, and only if, the current process wrote it. This function should be called if the program needs to call _exit(2) (such as from a signal handler) and needs to clean up the pid file.

# RETURN VALUES

pidfile() and pidfile_clean() returns 0 on success and -1 on failure.
pidfile_lock() returns 0 on success. Otherwise, the process ID who owns the lock is returned and if that cannot be derived then -1 is returned.
pidfile_read() returns the process ID if known, otherwise -1.

# ERRORS

The pidfile() and pidfile_lock() functions 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.

# SEE ALSO

flock(2), atexit(3)

# HISTORY

The pidfile() function call appeared in NetBSD 1.5. Support for creating pid files in any arbitrary path was added in NetBSD 6.0.
The pidfile_lock(), pidfile_read(), and pidfile_clean() function calls appeared in NetBSD 8.

# CAVEATS

pidfile() and pidfile_lock() use atexit(3) to ensure the pid file is cleaned at program exit. However, programs that use the _exit(2) function (for example, in signal handlers) will not trigger this behaviour and should call pidfile_clean(). Like-wise, if the program creates a pid file before fork(2)ing a child to take over, it should use the _exit(2) function instead of returning or using the exit(3) function to ensure the pid file is not cleaned.

April 10, 2016 | NetBSD 8.3