1.\" $NetBSD: pidfile.3,v 1.16 2017/10/22 16:55:32 abhinav 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.Nm pidfile_lock , 36.Nm pidfile_read , 37.Nm pidfile_clean 38.Nd write a daemon pid file 39.Sh LIBRARY 40.Lb libutil 41.Sh SYNOPSIS 42.In util.h 43.Ft int 44.Fn pidfile "const char *path" 45.Ft pid_t 46.Fn pidfile_lock "const char *path" 47.Ft pid_t 48.Fn pidfile_read "const char *path" 49.Ft int 50.Fn pidfile_clean "void" 51.Sh DESCRIPTION 52.Fn pidfile 53and 54.Fn pidfile_lock 55create and lock a file containing the process ID of the calling program. 56The pid file can be used as a quick reference if 57the process needs to be sent a signal. 58The pid file is truncated and removed automatically when the program exits, 59unless the program receives a fatal signal. 60.Pp 61If 62.Ar path 63is 64.Dv NULL 65or a plain basename (a name containing no directory components), the pid file 66is created in the 67.Pa /var/run 68directory. 69The file name has the form 70.Pa /var/run/basename.pid . 71The basename part is either the value of 72.Ar path 73if it was not 74.Dv NULL , 75or the program name as returned by 76.Xr getprogname 3 77otherwise. 78.Pp 79If 80.Ar path 81is an absolute or relative path (i.e. it contains the 82.Sq / 83character), 84the pid file is created in the provided location. 85.Pp 86If called with a new 87.Ar path , 88.Fn pidfile 89and 90.Fn pidfile_lock 91will remove the old pid file. 92.Pp 93The pid file is truncated, so these functions can be called multiple times and 94allow a child process to take over the lock. 95.Pp 96.Fn pidfile_read 97will read the last pid file created, or specified by 98.Ar path , 99and return the process ID it contains. 100.Pp 101.Fn pidfile_clean 102will 103.Xr ftruncate 2 , 104.Xr close 2 , 105and 106.Xr unlink 2 107the last opening pid file if, and only if, the current process wrote it. 108This function should be called if the program needs to call 109.Xr _exit 2 110(such as from a signal handler) and needs to clean up the pid file. 111.Sh RETURN VALUES 112.Fn pidfile 113and 114.Fn pidfile_clean 115returns 0 on success and \-1 on failure. 116.Pp 117.Fn pidfile_lock 118returns 0 on success. 119Otherwise, the process ID who owns the lock is returned and if that 120cannot be derived then \-1 is returned. 121.Pp 122.Fn pidfile_read 123returns the process ID if known, otherwise \-1. 124.Sh ERRORS 125The 126.Fn pidfile 127and 128.Fn pidfile_lock 129functions will fail if: 130.Bl -tag -width Er 131.It Bq Er EEXIST 132Some process already holds the lock on the given pid file, meaning that a 133daemon is already running. 134.It Bq Er ENAMETOOLONG 135Specified pidfile's name is too long. 136.El 137.Sh SEE ALSO 138.Xr flock 2 , 139.Xr atexit 3 140.Sh HISTORY 141The 142.Fn pidfile 143function call appeared in 144.Nx 1.5 . 145Support for creating pid files in any arbitrary path was added in 146.Nx 6.0 . 147.Pp 148The 149.Fn pidfile_lock , 150.Fn pidfile_read , 151and 152.Fn pidfile_clean 153function calls appeared in 154.Nx 8 . 155.Sh CAVEATS 156.Fn pidfile 157and 158.Fn pidfile_lock 159use 160.Xr atexit 3 161to ensure the pid file is cleaned at program exit. 162However, programs that use the 163.Xr _exit 2 164function (for example, in signal handlers) 165will not trigger this behaviour and should call 166.Fn pidfile_clean . 167Like-wise, if the program creates a pid file before 168.Xr fork 2 Ns ing 169a child to take over, it should use the 170.Xr _exit 2 171function instead of returning or using the 172.Xr exit 3 173function to ensure the pid file is not cleaned. 174