PIDFILE(3)

💅 PIDFILE(3) 💅

Okay so this is the Library Functions Manual entry for the pidfile crew, and bestie, it's giving "tiny but mighty sysadmin helper" energy. Let's get into it. ✨

---

🌸 NAME 🌸

pidfile_open, pidfile_write, pidfile_close, pidfile_remove — the library for PID files handling. Yes, the whole little squad. 💖

---

🧚 LIBRARY 🧚

System Utilities Library (libutil, -lutil). That's where these functions live, no cap.

---

🦋 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. Lowkey iconic behavior. 🔥

• pidfile_open() — opens (or creates) a file specified 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 returned in the pidptr argument (if it is not NULL). The function does not write the process's 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 argument is NULL, the /var/run/⟨progname⟩.pid file will be used. 🎀
• pidfile_write() — writes the process's PID into a previously opened file. That's the moment the file gets its main character info. 💅
• pidfile_close() — closes a pidfile. It should be used after the daemon fork()s to start a child process. Important timing, bestie. ⏰
• pidfile_remove() — closes and removes a pidfile. Cleanup queen behavior. 🧹

---

⭐ 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. So 0 = slay, -1 = check errno, fr fr. 💀

---

🌈 EXAMPLES 🌈

The following example shows in which order these functions should be used. Note that it is safe to pass NULL to the 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. Girl, that name is doing too much. 😭
• [EINVAL] — Some process already holds the lock on the given pidfile, but PID read from there is invalid. Messy. 🙈

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(). Bestie, that's the funniest errno and it means you skipped a step. 💀

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(). Wrong process energy. 🫠

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

---

💌 Source/version: Debian, dated August 22, 2005. That's the whole page, bestie—go lock those PID files responsibly! 🫶✨