1pidfile(3bsd) LOCAL pidfile(3bsd)
2
4 pidfile_open, pidfile_write, pidfile_close, pidfile_remove,
5 pidfile_fileno — library for PID files handling
6
8 Utility functions from BSD systems (libbsd, -lbsd)
9
11 #include <libutil.h>
12 (See libbsd(7) for include usage.)
13 struct pidfh *
15 pidfile_open(const char *path, mode_t mode, pid_t *pidptr);
16 int
18 pidfile_write(struct pidfh *pfh);
19 int
21 pidfile_close(struct pidfh *pfh);
22 int
24 pidfile_remove(struct pidfh *pfh);
25 int
27 pidfile_fileno(struct pidfh *pfh);
28
30 The pidfile family of functions allows daemons to handle PID files. It
31 uses flopen(3bsd) to lock a pidfile and detect already running daemons.
32 The pidfile_open() function opens (or creates) a file specified by the
34 path argument and locks it. If pidptr argument is not NULL and file can
35 not be locked, the function will use it to store a PID of an already run‐
36 ning daemon or -1 in case daemon did not write its PID yet. The function
37 does not write process' PID into the file here, so it can be used before
38 fork()ing and exit with a proper error message when needed. If the path
39 argument is NULL, /var/run/⟨progname⟩.pid file will be used. The
40 pidfile_open() function sets the O_CLOEXEC close-on-exec flag when open‐
41 ing the pidfile.
42 The pidfile_write() function writes process' PID into a previously opened
44 file. The file is truncated before write, so calling the pidfile_write()
45 function multiple times is supported.
46 The pidfile_close() function closes a pidfile. It should be used after
48 daemon fork()s to start a child process.
49 The pidfile_remove() function closes and removes a pidfile.
51 The pidfile_fileno() function returns the file descriptor for the open
53 pidfile.
54
56 The pidfile_open() function returns a valid pointer to a pidfh structure
57 on success, or NULL if an error occurs. If an error occurs, errno will
58 be set.
59 The pidfile_write(), pidfile_close(), and pidfile_remove() functions re‐
61 turn the value 0 if successful; otherwise the value -1 is returned and
62 the global variable errno is set to indicate the error.
63 The pidfile_fileno() function returns the low-level file descriptor. It
65 returns -1 and sets errno if a NULL pidfh is specified, or if the pidfile
66 is no longer open.
67
69 The following example shows in which order these functions should be
70 used. Note that it is safe to pass NULL to pidfile_write(),
71 pidfile_remove(), pidfile_close() and pidfile_fileno() functions.
72 struct pidfh *pfh;
74 pid_t otherpid, childpid;
75 pfh = pidfile_open("/var/run/daemon.pid", 0600, &otherpid);
77 if (pfh == NULL) {
78 if (errno == EEXIST) {
79 errx(EXIT_FAILURE, "Daemon already running, pid: %jd.",
80 (intmax_t)otherpid);
81 }
82 /* If we cannot create pidfile from other reasons, only warn. */
83 warn("Cannot open or create pidfile");
84 /*
85 * Even though pfh is NULL we can continue, as the other pidfile_*
86 * function can handle such situation by doing nothing except setting
87 * errno to EINVAL.
88 */
89 }
90 if (daemon(0, 0) == -1) {
92 warn("Cannot daemonize");
93 pidfile_remove(pfh);
94 exit(EXIT_FAILURE);
95 }
96 pidfile_write(pfh);
98 for (;;) {
100 /* Do work. */
101 childpid = fork();
102 switch (childpid) {
103 case -1:
104 syslog(LOG_ERR, "Cannot fork(): %s.", strerror(errno));
105 break;
106 case 0:
107 pidfile_close(pfh);
108 /* Do child work. */
109 break;
110 default:
111 syslog(LOG_INFO, "Child %jd started.", (intmax_t)childpid);
112 break;
113 }
114 }
115 pidfile_remove(pfh);
117 exit(EXIT_SUCCESS);
118
120 The pidfile_open() function will fail if:
121 [EEXIST] Some process already holds the lock on the given pid‐
123 file, meaning that a daemon is already running. If
124 pidptr argument is not NULL the function will use it
125 to store a PID of an already running daemon or -1 in
126 case daemon did not write its PID yet.
127 [ENAMETOOLONG] Specified pidfile's name is too long.
129 [EINVAL] Some process already holds the lock on the given pid‐
131 file, but PID read from there is invalid.
132 The pidfile_open() function may also fail and set errno for any errors
134 specified for the fstat(2), open(2), and read(2) calls.
135 The pidfile_write() function will fail if:
137 [EINVAL] Improper function use. Probably called before
139 pidfile_open().
140 The pidfile_write() function may also fail and set errno for any errors
142 specified for the fstat(2), ftruncate(2), and write(2) calls.
143 The pidfile_close() function may fail and set errno for any errors speci‐
145 fied for the close(2) and fstat(2) calls.
146 The pidfile_remove() function will fail if:
148 [EINVAL] Improper function use. Probably called not from the
150 process which made pidfile_write().
151 The pidfile_remove() function may also fail and set errno for any errors
153 specified for the close(2), fstat(2), write(2), and unlink(2) system
154 calls and the flopen(3bsd) library function.
155 The pidfile_fileno() function will fail if:
157 [EINVAL] Improper function use. Probably called not from the
159 process which used pidfile_open().
160
162 open(2), daemon(3), flopen(3bsd)
163
165 The pidfile functionality is based on ideas from John-Mark Gurney
166 <jmg@FreeBSD.org>.
167 The code and manual page was written by Pawel Jakub Dawidek
169 <pjd@FreeBSD.org>.
170BSD February 8, 2012 BSD