pidfile.3 (7e857dd14fe7f42f5b46af4904f84915215d8987) pidfile.3 (412fa8f1145545ad30922007c6cb607d7ddb1003)
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.

--- 10 unchanged lines hidden (view full) ---

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

--- 10 unchanged lines hidden (view full) ---

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
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
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"
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
36.Sh LIBRARY
37.Lb libutil
38.Sh SYNOPSIS
39.In sys/param.h
40.In libutil.h
41.Ft "struct pidfh *"
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
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.
51.Nm libpidfile
52library provides functions for daemons to handle file with PID.
53It uses
53It uses
54.Xr flopen 3
55to lock a pidfile and detect already running daemons.
54.Xr flock 2
55to lock pidfile and detect already running daemons.
56.Pp
57The
58.Fn pidfile_open
56.Pp
57The
58.Fn pidfile_open
59function opens (or creates) a file specified by the
59function opens (or creates) a file specified by
60.Fa path
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
61argument and locks it with
62.Xr flock 2
63syscall.
64If file can not be locked, PID of already running daemon is returned in
64.Fa pidptr
65.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
66argument (if it is not NULL).
67The function doesn't write process' PID into the file here, so it can be
68used before fork()ing and exit with proper error message when needed.
69If
72.Fa path
70.Fa path
73argument is
74.Dv NULL ,
75.Pa /var/run/ Ns Ao Va progname Ac Ns Pa .pid
71argument is NULL,
72.Pa /var/run/<progname>.pid
76file will be used.
77.Pp
78The
79.Fn pidfile_write
73file will be used.
74.Pp
75The
76.Fn pidfile_write
80function writes process' PID into a previously opened file.
77function write process' PID into previously opened file.
81.Pp
82The
83.Fn pidfile_close
78.Pp
79The
80.Fn pidfile_close
84function closes a pidfile.
85It should be used after daemon
86.Fn fork Ns s
87to start a child process.
81function closes pidfile.
82It should be used after daemon fork()s to start a child process.
88.Pp
89The
90.Fn pidfile_remove
83.Pp
84The
85.Fn pidfile_remove
91function closes and removes a pidfile.
86function closes and removes pidfile.
92.Sh RETURN VALUES
93The
94.Fn pidfile_open
87.Sh RETURN VALUES
88The
89.Fn pidfile_open
95function returns a valid pointer to a
96.Vt pidfh
97structure on success, or
90function return a valid pointer to a pidfh structure on success or
98.Dv NULL
99if an error occurs.
91.Dv NULL
92if an error occurs.
100If an error occurs,
93If an error does occur,
101.Va errno
102will be set.
94.Va errno
95will be set.
103.Pp
104.Rv -std pidfile_write pidfile_close pidfile_remove
105.Sh EXAMPLES
96.Rv -std pidfile_write pidfile_close pidfile_remove
97.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.
98The following example shows in which order those functions should be used.
115.Bd -literal
116struct pidfh *pfh;
117pid_t otherpid, childpid;
118
99.Bd -literal
100struct pidfh *pfh;
101pid_t otherpid, childpid;
102
119pfh = pidfile_open("/var/run/daemon.pid", 0600, &otherpid);
103pfh = pidfile_open("/var/run/daemon.pid", 0644, &otherpid);
120if (pfh == NULL) {
104if (pfh == NULL) {
121 if (errno == EEXIST) {
122 errx(EXIT_FAILURE, "Daemon already running, pid: %jd.",
123 (intmax_t)otherpid);
124 }
105 if (errno == EEXIST)
106 errx(EXIT_FAILURE, "Daemon already running, pid: %d.", otherpid);
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);

--- 8 unchanged lines hidden (view full) ---

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:
107 /* If we cannot create pidfile from other reasons, only warn. */
108 warn("Cannot open or create pidfile");
109}
110
111if (daemon(0, 0) == -1) {
112 warn("Cannot daemonize");
113 pidfile_remove(pfh);
114 exit(EXIT_FAILURE);

--- 8 unchanged lines hidden (view full) ---

123 case -1:
124 syslog(LOG_ERR, "Cannot fork(): %s.", strerror(errno));
125 break;
126 case 0:
127 pidfile_close(pfh);
128 /* Do child work. */
129 break;
130 default:
149 syslog(LOG_INFO, "Child %jd started.", (intmax_t)childpid);
131 syslog(LOG_INFO, "Child %d started.", 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
132 break;
133 }
134}
135
136pidfile_remove(pfh);
137exit(EXIT_SUCCESS);
138.Ed
139.Sh ERRORS
140The
141.Fn pidfile_open
142function will fail if:
143.Bl -tag -width Er
144.It Bq Er EEXIST
163Some process already holds the lock on the given pidfile, meaning that a
145Some process already holds the lock on the given pidfile, which means,
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.
146daemon is already running.
147.It Bq Er ENAMETOOLONG
148Specified pidfile's name is too long.
149.It Bq Er EINVAL
150Some process already holds the lock on the given pidfile, but PID read
151from 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 ,
152.El
153.Pp
154The
155.Fn pidfile_open
156function may also fail and set
157.Va errno
158for any errors specified for the
159.Xr fstat 2 ,
160.Xr open 2 ,
184and
185.Xr read 2
161.Xr read 2
186calls.
162routines.
187.Pp
188The
189.Fn pidfile_write
190function will fail if:
191.Bl -tag -width Er
192.It Bq Er EDOOFUS
163.Pp
164The
165.Fn pidfile_write
166function will fail if:
167.Bl -tag -width Er
168.It Bq Er EDOOFUS
193Improper function use.
169Inproper 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 ,
170Probably called before
171.Fn pidfile_open .
172.El
173.Pp
174The
175.Fn pidfile_write
176function may also fail and set
177.Va errno
178for any errors specified for the
179.Xr fstat 2 ,
180.Xr ftruncate 2 ,
205and
206.Xr write 2
181.Xr write 2
207calls.
182routines.
208.Pp
209The
210.Fn pidfile_close
211function may fail and set
212.Va errno
213for any errors specified for the
183.Pp
184The
185.Fn pidfile_close
186function may fail and set
187.Va errno
188for any errors specified for the
214.Xr close 2
215and
189.Xr close 2 ,
216.Xr fstat 2
190.Xr fstat 2
217calls.
191routines.
218.Pp
219The
220.Fn pidfile_remove
221function will fail if:
222.Bl -tag -width Er
223.It Bq Er EDOOFUS
192.Pp
193The
194.Fn pidfile_remove
195function will fail if:
196.Bl -tag -width Er
197.It Bq Er EDOOFUS
224Improper function use.
198Inproper 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 ,
199Probably called not from the process which made
200.Fn pidfile_write .
201.El
202.Pp
203The
204.Fn pidfile_remove
205function may also fail and set
206.Va errno
207for any errors specified for the
208.Xr close 2 ,
209.Xr flock 2 ,
235.Xr fstat 2 ,
236.Xr write 2 ,
210.Xr fstat 2 ,
211.Xr write 2 ,
237and
238.Xr unlink 2
212.Xr unlink 2
239system calls and the
240.Xr flopen 3
241library function.
213routines.
214.Pp
242.Sh SEE ALSO
215.Sh SEE ALSO
216.Xr flock 2 ,
243.Xr open 2 ,
217.Xr open 2 ,
244.Xr daemon 3 ,
245.Xr flopen 3
218.Xr daemon 3
246.Sh AUTHORS
247.An -nosplit
248The
219.Sh AUTHORS
220.An -nosplit
221The
249.Nm pidfile
222.Xr pidfile 3
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 .
223functionality is based on ideas from
224.An John-Mark Gurney Aq jmg@FreeBSD.org .
225.Pp
226The code and manual page was written by
227.An Pawel Jakub Dawidek Aq pjd@FreeBSD.org .