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.\"
| 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: head/lib/libutil/pidfile.3 156280 2006-03-04 15:20:28Z keramida $
| 25.\" $FreeBSD: head/lib/libutil/pidfile.3 172577 2007-10-12 10:38:05Z kib $
|
26.\"
27.Dd August 22, 2005
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 flock 2
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 with the
62.Xr flock 2
63system call.
64If a file can not be locked, a PID of an already running daemon is returned in
65the
66.Fa pidptr
67argument (if it is not
68.Dv NULL ) .
69The function does not write process' PID into the file here, so it can be
70used before
71.Fn fork Ns ing
72and exit with a proper error message when needed.
73If the
74.Fa path
75argument is
76.Dv NULL ,
77.Pa /var/run/ Ns Ao Va progname Ac Ns Pa .pid
78file will be used.
79.Pp
80The
81.Fn pidfile_write
82function writes process' PID into a previously opened file.
83.Pp
84The
85.Fn pidfile_close
86function closes a pidfile.
87It should be used after daemon
88.Fn fork Ns s
89to start a child process.
90.Pp
91The
92.Fn pidfile_remove
93function closes and removes a pidfile.
94.Sh RETURN VALUES
95The
96.Fn pidfile_open
97function returns a valid pointer to a
98.Vt pidfh
99structure on success, or
100.Dv NULL
101if an error occurs.
102If an error occurs,
103.Va errno
104will be set.
105.Rv -std pidfile_write pidfile_close pidfile_remove
106.Sh EXAMPLES
107The following example shows in which order these functions should be used.
108Note that it is safe to pass
109.Dv NULL
110to
111.Fn pidfile_write ,
112.Fn pidfile_remove
113and
114.Fn pidfile_close
115functions.
116.Bd -literal
117struct pidfh *pfh;
118pid_t otherpid, childpid;
119
120pfh = pidfile_open("/var/run/daemon.pid", 0600, &otherpid);
121if (pfh == NULL) {
122 if (errno == EEXIST) {
123 errx(EXIT_FAILURE, "Daemon already running, pid: %jd.",
124 (intmax_t)otherpid);
125 }
126 /* If we cannot create pidfile from other reasons, only warn. */
127 warn("Cannot open or create pidfile");
128}
129
130if (daemon(0, 0) == -1) {
131 warn("Cannot daemonize");
132 pidfile_remove(pfh);
133 exit(EXIT_FAILURE);
134}
135
136pidfile_write(pfh);
137
138for (;;) {
139 /* Do work. */
140 childpid = fork();
141 switch (childpid) {
142 case -1:
143 syslog(LOG_ERR, "Cannot fork(): %s.", strerror(errno));
144 break;
145 case 0:
146 pidfile_close(pfh);
147 /* Do child work. */
148 break;
149 default:
150 syslog(LOG_INFO, "Child %jd started.", (intmax_t)childpid);
151 break;
152 }
153}
154
155pidfile_remove(pfh);
156exit(EXIT_SUCCESS);
157.Ed
158.Sh ERRORS
159The
160.Fn pidfile_open
161function will fail if:
162.Bl -tag -width Er
163.It Bq Er EEXIST
164Some process already holds the lock on the given pidfile, meaning that a
165daemon is already running.
166.It Bq Er ENAMETOOLONG
167Specified pidfile's name is too long.
168.It Bq Er EINVAL
169Some process already holds the lock on the given pidfile, but PID read
170from there is invalid.
| 26.\"
27.Dd August 22, 2005
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 flock 2
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 with the
62.Xr flock 2
63system call.
64If a file can not be locked, a PID of an already running daemon is returned in
65the
66.Fa pidptr
67argument (if it is not
68.Dv NULL ) .
69The function does not write process' PID into the file here, so it can be
70used before
71.Fn fork Ns ing
72and exit with a proper error message when needed.
73If the
74.Fa path
75argument is
76.Dv NULL ,
77.Pa /var/run/ Ns Ao Va progname Ac Ns Pa .pid
78file will be used.
79.Pp
80The
81.Fn pidfile_write
82function writes process' PID into a previously opened file.
83.Pp
84The
85.Fn pidfile_close
86function closes a pidfile.
87It should be used after daemon
88.Fn fork Ns s
89to start a child process.
90.Pp
91The
92.Fn pidfile_remove
93function closes and removes a pidfile.
94.Sh RETURN VALUES
95The
96.Fn pidfile_open
97function returns a valid pointer to a
98.Vt pidfh
99structure on success, or
100.Dv NULL
101if an error occurs.
102If an error occurs,
103.Va errno
104will be set.
105.Rv -std pidfile_write pidfile_close pidfile_remove
106.Sh EXAMPLES
107The following example shows in which order these functions should be used.
108Note that it is safe to pass
109.Dv NULL
110to
111.Fn pidfile_write ,
112.Fn pidfile_remove
113and
114.Fn pidfile_close
115functions.
116.Bd -literal
117struct pidfh *pfh;
118pid_t otherpid, childpid;
119
120pfh = pidfile_open("/var/run/daemon.pid", 0600, &otherpid);
121if (pfh == NULL) {
122 if (errno == EEXIST) {
123 errx(EXIT_FAILURE, "Daemon already running, pid: %jd.",
124 (intmax_t)otherpid);
125 }
126 /* If we cannot create pidfile from other reasons, only warn. */
127 warn("Cannot open or create pidfile");
128}
129
130if (daemon(0, 0) == -1) {
131 warn("Cannot daemonize");
132 pidfile_remove(pfh);
133 exit(EXIT_FAILURE);
134}
135
136pidfile_write(pfh);
137
138for (;;) {
139 /* Do work. */
140 childpid = fork();
141 switch (childpid) {
142 case -1:
143 syslog(LOG_ERR, "Cannot fork(): %s.", strerror(errno));
144 break;
145 case 0:
146 pidfile_close(pfh);
147 /* Do child work. */
148 break;
149 default:
150 syslog(LOG_INFO, "Child %jd started.", (intmax_t)childpid);
151 break;
152 }
153}
154
155pidfile_remove(pfh);
156exit(EXIT_SUCCESS);
157.Ed
158.Sh ERRORS
159The
160.Fn pidfile_open
161function will fail if:
162.Bl -tag -width Er
163.It Bq Er EEXIST
164Some process already holds the lock on the given pidfile, meaning that a
165daemon is already running.
166.It Bq Er ENAMETOOLONG
167Specified pidfile's name is too long.
168.It Bq Er EINVAL
169Some process already holds the lock on the given pidfile, but PID read
170from there is invalid.
|
| 171.It Bq Er EAGAIN
172Some process already holds the lock on the given pidfile, but the file
173is truncated. Most likely, the existing daemon is writing new PID into
174the file.
|
171.El
172.Pp
173The
174.Fn pidfile_open
175function may also fail and set
176.Va errno
177for any errors specified for the
178.Xr fstat 2 ,
179.Xr open 2 ,
180and
181.Xr read 2
182calls.
183.Pp
184The
185.Fn pidfile_write
186function will fail if:
187.Bl -tag -width Er
188.It Bq Er EDOOFUS
189Improper function use.
190Probably called before
191.Fn pidfile_open .
192.El
193.Pp
194The
195.Fn pidfile_write
196function may also fail and set
197.Va errno
198for any errors specified for the
199.Xr fstat 2 ,
200.Xr ftruncate 2 ,
201and
202.Xr write 2
203calls.
204.Pp
205The
206.Fn pidfile_close
207function may fail and set
208.Va errno
209for any errors specified for the
210.Xr close 2
211and
212.Xr fstat 2
213calls.
214.Pp
215The
216.Fn pidfile_remove
217function will fail if:
218.Bl -tag -width Er
219.It Bq Er EDOOFUS
220Improper function use.
221Probably called not from the process which made
222.Fn pidfile_write .
223.El
224.Pp
225The
226.Fn pidfile_remove
227function may also fail and set
228.Va errno
229for any errors specified for the
230.Xr close 2 ,
231.Xr flock 2 ,
232.Xr fstat 2 ,
233.Xr write 2 ,
234and
235.Xr unlink 2
236calls.
237.Sh SEE ALSO
238.Xr flock 2 ,
239.Xr open 2 ,
240.Xr daemon 3
241.Sh AUTHORS
242.An -nosplit
243The
244.Nm pidfile
245functionality is based on ideas from
246.An John-Mark Gurney Aq jmg@FreeBSD.org .
247.Pp
248The code and manual page was written by
249.An Pawel Jakub Dawidek Aq pjd@FreeBSD.org .
| 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 flock 2 ,
236.Xr fstat 2 ,
237.Xr write 2 ,
238and
239.Xr unlink 2
240calls.
241.Sh SEE ALSO
242.Xr flock 2 ,
243.Xr open 2 ,
244.Xr daemon 3
245.Sh AUTHORS
246.An -nosplit
247The
248.Nm pidfile
249functionality is based on ideas from
250.An John-Mark Gurney Aq jmg@FreeBSD.org .
251.Pp
252The code and manual page was written by
253.An Pawel Jakub Dawidek Aq pjd@FreeBSD.org .
|