1.\" $NetBSD: pidfile.3,v 1.15 2016/04/11 08:49:57 wiz Exp $ 2.\" 3.\" Copyright (c) 1999, 2016 The NetBSD Foundation, Inc. 4.\" All rights reserved. 5.\" 6.\" This code is derived from software contributed to The NetBSD Foundation 7.\" by Jason R. Thorpe and Roy Marples. 8.\" 9.\" Redistribution and use in source and binary forms, with or without 10.\" modification, are permitted provided that the following conditions 11.\" are met: 12.\" 1. Redistributions of source code must retain the above copyright 13.\" notice, this list of conditions and the following disclaimer. 14.\" 2. Redistributions in binary form must reproduce the above copyright 15.\" notice, this list of conditions and the following disclaimer in the 16.\" documentation and/or other materials provided with the distribution. 17.\" 18.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS 19.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED 20.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR 21.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS 22.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR 23.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF 24.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS 25.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN 26.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) 27.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE 28.\" POSSIBILITY OF SUCH DAMAGE. 29.\" 30.Dd April 10, 2016 31.Dt PIDFILE 3 32.Os 33.Sh NAME 34.Nm pidfile 35.Nd write a daemon pid file 36.Sh LIBRARY 37.Lb libutil 38.Sh SYNOPSIS 39.In util.h 40.Ft int 41.Fn pidfile "const char *path" 42.Ft pid_t 43.Fn pidfile_lock "const char *path" 44.Ft pid_t 45.Fn pidfile_read "const char *path" 46.Ft int 47.Fn pidfile_clean "void" 48.Sh DESCRIPTION 49.Fn pidfile 50and 51.Fn pidfile_lock 52create and lock a file containing the process ID of the calling program. 53The pid file can be used as a quick reference if 54the process needs to be sent a signal. 55The pid file is truncated and removed automatically when the program exits, 56unless the program receives a fatal signal. 57.Pp 58If 59.Ar path 60is 61.Dv NULL 62or a plain basename (a name containing no directory components), the pid file 63is created in the 64.Pa /var/run 65directory. 66The file name has the form 67.Pa /var/run/basename.pid . 68The basename part is either the value of 69.Ar path 70if it was not 71.Dv NULL , 72or the program name as returned by 73.Xr getprogname 3 74otherwise. 75.Pp 76If 77.Ar path 78is an absolute or relative path (i.e. it contains the 79.Sq / 80character), 81the pid file is created in the provided location. 82.Pp 83If called with a new 84.Ar path , 85.Fn pidfile 86and 87.Fn pidfile_lock 88will remove the old pid file. 89.Pp 90The pid file is truncated, so these functions can be called multiple times and 91allow a child process to take over the lock. 92.Pp 93.Fn pidfile_read 94will read the last pid file created, or specified by 95.Ar path , 96and return the process ID it contains. 97.Pp 98.Fn pidfile_clean 99will 100.Xr ftruncate 2 , 101.Xr close 2 , 102and 103.Xr unlink 2 104the last opening pid file if, and only if, the current process wrote it. 105This function should be called if the program needs to call 106.Xr _exit 2 107(such as from a signal handler) and needs to clean up the pid file. 108.Sh RETURN VALUES 109.Fn pidfile 110and 111.Fn pidfile_clean 112returns 0 on success and \-1 on failure. 113.Pp 114.Fn pidfile_lock 115returns 0 on success. 116Otherwise, the process ID who owns the lock is returned and if that 117cannot be derived then \-1 is returned. 118.Pp 119.Fn pidfile_read 120returns the process ID if known, otherwise \-1. 121.Sh ERRORS 122The 123.Fn pidfile 124and 125.Fn pidfile_lock 126functions will fail if: 127.Bl -tag -width Er 128.It Bq Er EEXIST 129Some process already holds the lock on the given pid file, meaning that a 130daemon is already running. 131.It Bq Er ENAMETOOLONG 132Specified pidfile's name is too long. 133.El 134.Sh SEE ALSO 135.Xr flock 2 , 136.Xr atexit 3 137.Sh HISTORY 138The 139.Fn pidfile 140function call appeared in 141.Nx 1.5 . 142Support for creating pid files in any arbitrary path was added in 143.Nx 6.0 . 144.Pp 145The 146.Fn pidfile_lock , 147.Fn pidfile_read , 148and 149.Fn pidfile_clean 150function calls appeared in 151.Nx 8 . 152.Sh CAVEATS 153.Fn pidfile 154and 155.Fn pidfile_lock 156use 157.Xr atexit 3 158to ensure the pid file is cleaned at program exit. 159However, programs that use the 160.Xr _exit 2 161function (for example, in signal handlers) 162will not trigger this behaviour and should call 163.Fn pidfile_clean . 164Like-wise, if the program creates a pid file before 165.Xr fork 2 Ns ing 166a child to take over, it should use the 167.Xr _exit 2 168function instead of returning or using the 169.Xr exit 3 170function to ensure the pid file is not cleaned. 171