xref: /freebsd/lib/libutil/pidfile.3 (revision aa0a1e58) 
1.\" Copyright (c) 2005 Pawel Jakub Dawidek <pjd@FreeBSD.org>
2.\" All rights reserved.
3.\"
4.\" Redistribution and use in source and binary forms, with or without
5.\" modification, are permitted provided that the following conditions
6.\" are met:
7.\" 1. Redistributions of source code must retain the above copyright
8.\"    notice, this list of conditions and the following disclaimer.
9.\" 2. Redistributions in binary form must reproduce the above copyright
10.\"    notice, this list of conditions and the following disclaimer in the
11.\"    documentation and/or other materials provided with the distribution.
12.\"
13.\" THIS SOFTWARE IS PROVIDED BY THE AUTHORS AND CONTRIBUTORS ``AS IS'' AND
14.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
15.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
16.\" ARE DISCLAIMED.  IN NO EVENT SHALL THE AUTHORS OR CONTRIBUTORS BE LIABLE
17.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
18.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
19.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
20.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
21.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
22.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
23.\" SUCH DAMAGE.
24.\"
25.\" $FreeBSD$
26.\"
27.Dd October 20, 2008
28.Dt PIDFILE 3
29.Os
30.Sh NAME
31.Nm pidfile_open ,
32.Nm pidfile_write ,
33.Nm pidfile_close ,
34.Nm pidfile_remove
35.Nd "library for PID files handling"
36.Sh LIBRARY
37.Lb libutil
38.Sh SYNOPSIS
39.In sys/param.h
40.In libutil.h
41.Ft "struct pidfh *"
42.Fn pidfile_open "const char *path" "mode_t mode" "pid_t *pidptr"
43.Ft int
44.Fn pidfile_write "struct pidfh *pfh"
45.Ft int
46.Fn pidfile_close "struct pidfh *pfh"
47.Ft int
48.Fn pidfile_remove "struct pidfh *pfh"
49.Sh DESCRIPTION
50The
51.Nm pidfile
52family of functions allows daemons to handle PID files.
53It uses
54.Xr flopen 3
55to lock a pidfile and detect already running daemons.
56.Pp
57The
58.Fn pidfile_open
59function opens (or creates) a file specified by the
60.Fa path
61argument and locks it.
62If a file can not be locked, a PID of an already running daemon is returned in
63the
64.Fa pidptr
65argument (if it is not
66.Dv NULL ) .
67The function does not write process' PID into the file here, so it can be
68used before
69.Fn fork Ns ing
70and exit with a proper error message when needed.
71If the
72.Fa path
73argument is
74.Dv NULL ,
75.Pa /var/run/ Ns Ao Va progname Ac Ns Pa .pid
76file will be used.
77.Pp
78The
79.Fn pidfile_write
80function writes process' PID into a previously opened file.
81.Pp
82The
83.Fn pidfile_close
84function closes a pidfile.
85It should be used after daemon
86.Fn fork Ns s
87to start a child process.
88.Pp
89The
90.Fn pidfile_remove
91function closes and removes a pidfile.
92.Sh RETURN VALUES
93The
94.Fn pidfile_open
95function returns a valid pointer to a
96.Vt pidfh
97structure on success, or
98.Dv NULL
99if an error occurs.
100If an error occurs,
101.Va errno
102will be set.
103.Pp
104.Rv -std pidfile_write pidfile_close pidfile_remove
105.Sh EXAMPLES
106The following example shows in which order these functions should be used.
107Note that it is safe to pass
108.Dv NULL
109to
110.Fn pidfile_write ,
111.Fn pidfile_remove
112and
113.Fn pidfile_close
114functions.
115.Bd -literal
116struct pidfh *pfh;
117pid_t otherpid, childpid;
118
119pfh = pidfile_open("/var/run/daemon.pid", 0600, &otherpid);
120if (pfh == NULL) {
121	if (errno == EEXIST) {
122		errx(EXIT_FAILURE, "Daemon already running, pid: %jd.",
123		    (intmax_t)otherpid);
124	}
125	/* If we cannot create pidfile from other reasons, only warn. */
126	warn("Cannot open or create pidfile");
127}
128
129if (daemon(0, 0) == -1) {
130	warn("Cannot daemonize");
131	pidfile_remove(pfh);
132	exit(EXIT_FAILURE);
133}
134
135pidfile_write(pfh);
136
137for (;;) {
138	/* Do work. */
139	childpid = fork();
140	switch (childpid) {
141	case -1:
142		syslog(LOG_ERR, "Cannot fork(): %s.", strerror(errno));
143		break;
144	case 0:
145		pidfile_close(pfh);
146		/* Do child work. */
147		break;
148	default:
149		syslog(LOG_INFO, "Child %jd started.", (intmax_t)childpid);
150		break;
151	}
152}
153
154pidfile_remove(pfh);
155exit(EXIT_SUCCESS);
156.Ed
157.Sh ERRORS
158The
159.Fn pidfile_open
160function will fail if:
161.Bl -tag -width Er
162.It Bq Er EEXIST
163Some process already holds the lock on the given pidfile, meaning that a
164daemon is already running.
165.It Bq Er ENAMETOOLONG
166Specified pidfile's name is too long.
167.It Bq Er EINVAL
168Some process already holds the lock on the given pidfile, but PID read
169from there is invalid.
170.It Bq Er EAGAIN
171Some process already holds the lock on the given pidfile, but the file
172is truncated.
173Most likely, the existing daemon is writing new PID into
174the file.
175.El
176.Pp
177The
178.Fn pidfile_open
179function may also fail and set
180.Va errno
181for any errors specified for the
182.Xr fstat 2 ,
183.Xr open 2 ,
184and
185.Xr read 2
186calls.
187.Pp
188The
189.Fn pidfile_write
190function will fail if:
191.Bl -tag -width Er
192.It Bq Er EDOOFUS
193Improper function use.
194Probably called before
195.Fn pidfile_open .
196.El
197.Pp
198The
199.Fn pidfile_write
200function may also fail and set
201.Va errno
202for any errors specified for the
203.Xr fstat 2 ,
204.Xr ftruncate 2 ,
205and
206.Xr write 2
207calls.
208.Pp
209The
210.Fn pidfile_close
211function may fail and set
212.Va errno
213for any errors specified for the
214.Xr close 2
215and
216.Xr fstat 2
217calls.
218.Pp
219The
220.Fn pidfile_remove
221function will fail if:
222.Bl -tag -width Er
223.It Bq Er EDOOFUS
224Improper function use.
225Probably called not from the process which made
226.Fn pidfile_write .
227.El
228.Pp
229The
230.Fn pidfile_remove
231function may also fail and set
232.Va errno
233for any errors specified for the
234.Xr close 2 ,
235.Xr fstat 2 ,
236.Xr write 2 ,
237and
238.Xr unlink 2
239system calls and the
240.Xr flopen 3
241library function.
242.Sh SEE ALSO
243.Xr open 2 ,
244.Xr daemon 3 ,
245.Xr flopen 3
246.Sh AUTHORS
247.An -nosplit
248The
249.Nm pidfile
250functionality is based on ideas from
251.An John-Mark Gurney Aq jmg@FreeBSD.org .
252.Pp
253The code and manual page was written by
254.An Pawel Jakub Dawidek Aq pjd@FreeBSD.org .
255