PIDFILE(3)

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

# NAME

`pidfile`, `pidfile_lock`, `pidfile_read`, `pidfile_clean` —
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 9.3