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