---
name: "pidfile"
section: "3"
platform: "macos"
package: "libutil"
version: "73"
release: "macOS 26.5"
platforms: ["linux", "freebsd", "macos"]
url: "https://new.carta.tech/pidfile"
---

# pidfile(3)

library for PID files handling

## 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)](/flock/2.md) to lock a pidfile and detect already running daemons.

The **pidfile\_open**() function opens (or creates) a file specified by the *path* argument and locks it with the [flock(2)](/flock/2.md) system call. If a file can not be locked, a PID of an already running daemon is returned 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**(*Ns*, *ing*) and exit with a proper error message when needed. If the *path* argument is NULL, */var/run/*⟨*progname*⟩*.pid* file will be used.

The **pidfile\_write**() function writes process' PID into a previously opened file.

The **pidfile\_close**() function closes a pidfile. It should be used after daemon **fork**(*Ns*, *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()**, **pidfile\_close()**, and **pidfile\_remove()** functions return the value 0 if successful; 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. Note that it is safe to pass NULL to **pidfile\_write**(), **pidfile\_remove**() and **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 **pidfile\_open**() function will fail if:

- \[EEXIST\]

  Some process already holds the lock on the given pidfile, 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 pidfile, 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)](/fstat/2.md), [open(2)](/open/2.md), and [read(2)](/read/2.md) 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)](/fstat/2.md), [ftruncate(2)](/ftruncate/2.md), and [write(2)](/write/2.md) calls.

The **pidfile\_close**() function may fail and set *errno* for any errors specified for the [close(2)](/close/2.md) and [fstat(2)](/fstat/2.md) 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)](/close/2.md), [flock(2)](/flock/2.md), [fstat(2)](/fstat/2.md), [write(2)](/write/2.md), and [unlink(2)](/unlink/2.md) calls.

## SEE ALSO

[flock(2)](/flock/2.md), [open(2)](/open/2.md), [daemon(3)](/daemon/3.md)

## 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⟩.