pidfile(3bsd) 3bsd pidfile(3bsd) # [NAME](#NAME) `pidfile_open`, `pidfile_write`, `pidfile_close`, `pidfile_remove`, `pidfile_fileno` — library for PID files handling # [LIBRARY](#LIBRARY) library “libbsd” # [SYNOPSIS](#SYNOPSIS) `#include ` (See [libbsd(7)](/man/os/libbsd/libbsd.7) for include usage.) `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`); `int` `pidfile_fileno`(`struct pidfh *pfh`); # [DESCRIPTION](#DESCRIPTION) The `pidfile` family of functions allows daemons to handle PID files. It uses [flopen(3bsd)](/man/os/libbsd/flopen.3bsd) to lock a pidfile and detect already running daemons. The [`pidfile_open`](#pidfile_open)() function opens (or creates) a file specified by the `path` argument and locks it. If `pidptr` argument is not `NULL` and file can not be locked, the function will use it to store a PID of an already running daemon or `-1` in case daemon did not write its PID yet. The function does not write process' PID into the file here, so it can be used before [`fork`](#fork)()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_open`() function sets the O\_CLOEXEC close-on-exec flag when opening the pidfile. The [`pidfile_write`](#pidfile_write)() function writes process' PID into a previously opened file. The file is truncated before write, so calling the `pidfile_write`() function multiple times is supported. The [`pidfile_close`](#pidfile_close)() function closes a pidfile. It should be used after daemon [`fork`](#fork~2)()s to start a child process. The [`pidfile_remove`](#pidfile_remove)() function closes and removes a pidfile. The [`pidfile_fileno`](#pidfile_fileno)() function returns the file descriptor for the open pidfile. # [RETURN VALUES](#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. The `pidfile_fileno`() function returns the low-level file descriptor. It returns `-1` and sets `errno` if a NULL `pidfh` is specified, or if the pidfile is no longer open. # [EXAMPLES](#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`(), `pidfile_close`() and `pidfile_fileno`() 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"); /* * Even though pfh is NULL we can continue, as the other pidfile_* * function can handle such situation by doing nothing except setting * errno to EINVAL. */ } 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](#ERRORS) The `pidfile_open`() function will fail if: \[[`EEXIST`](#EEXIST)] Some process already holds the lock on the given pidfile, meaning that a daemon is already running. If `pidptr` argument is not `NULL` the function will use it to store a PID of an already running daemon or `-1` in case daemon did not write its PID yet. \[[`ENAMETOOLONG`](#ENAMETOOLONG)] Specified pidfile's name is too long. \[[`EINVAL`](#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)](/man/os/libbsd/fstat.2), [open(2)](/man/os/libbsd/open.2), and [read(2)](/man/os/libbsd/read.2) calls. The `pidfile_write`() function will fail if: \[[`EINVAL`](#EINVAL~2)] 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)](/man/os/libbsd/fstat.2), [ftruncate(2)](/man/os/libbsd/ftruncate.2), and [write(2)](/man/os/libbsd/write.2) calls. The `pidfile_close`() function may fail and set `errno` for any errors specified for the [close(2)](/man/os/libbsd/close.2) and [fstat(2)](/man/os/libbsd/fstat.2) calls. The `pidfile_remove`() function will fail if: \[[`EINVAL`](#EINVAL~3)] 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)](/man/os/libbsd/close.2), [fstat(2)](/man/os/libbsd/fstat.2), [write(2)](/man/os/libbsd/write.2), and [unlink(2)](/man/os/libbsd/unlink.2) system calls and the [flopen(3bsd)](/man/os/libbsd/flopen.3bsd) library function. The `pidfile_fileno`() function will fail if: \[[`EINVAL`](#EINVAL~4)] Improper function use. Probably called not from the process which used `pidfile_open`(). # [SEE ALSO](#SEE_ALSO) [open(2)](/man/os/libbsd/open.2), [daemon(3)](/man/os/libbsd/daemon.3), [flopen(3bsd)](/man/os/libbsd/flopen.3bsd) # [HISTORY](#HISTORY) The functions `pidfile_open`(), `pidfile_write`(), `pidfile_close`() and `pidfile_remove`() first appeared in FreeBSD 5.5. The function `pidfile_fileno`() first appeared in FreeBSD 10.0. # [AUTHORS](#AUTHORS) The `pidfile` functionality is based on ideas from John-Mark Gurney <[jmg@FreeBSD.org](mailto:jmg@FreeBSD.org)>. The code and manual page was written by Pawel Jakub Dawidek <[pjd@FreeBSD.org](mailto:pjd@FreeBSD.org)>. February 8, 2012 Linux 4.19.0-gvisor --- Document: pidfile_close(3bsd) from libbsd 0.12.2-r11 (Chainguard OS) Source: https://gitlab.freedesktop.org/libbsd/libbsd