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 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. 174Most likely, the existing daemon is writing new PID into 175the file. 176.El 177.Pp 178The 179.Fn pidfile_open 180function may also fail and set 181.Va errno 182for any errors specified for the 183.Xr fstat 2 , 184.Xr open 2 , 185and 186.Xr read 2 187calls. 188.Pp 189The 190.Fn pidfile_write 191function will fail if: 192.Bl -tag -width Er 193.It Bq Er EDOOFUS 194Improper function use. 195Probably called before 196.Fn pidfile_open . 197.El 198.Pp 199The 200.Fn pidfile_write 201function may also fail and set 202.Va errno 203for any errors specified for the 204.Xr fstat 2 , 205.Xr ftruncate 2 , 206and 207.Xr write 2 208calls. 209.Pp 210The 211.Fn pidfile_close 212function may fail and set 213.Va errno 214for any errors specified for the 215.Xr close 2 216and 217.Xr fstat 2 218calls. 219.Pp 220The 221.Fn pidfile_remove 222function will fail if: 223.Bl -tag -width Er 224.It Bq Er EDOOFUS 225Improper function use. 226Probably called not from the process which made 227.Fn pidfile_write . 228.El 229.Pp 230The 231.Fn pidfile_remove 232function may also fail and set 233.Va errno 234for any errors specified for the 235.Xr close 2 , 236.Xr flock 2 , 237.Xr fstat 2 , 238.Xr write 2 , 239and 240.Xr unlink 2 241calls. 242.Sh SEE ALSO 243.Xr flock 2 , 244.Xr open 2 , 245.Xr daemon 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