1.\" $NetBSD: pidfile.3,v 1.10 2008/04/30 13:10:52 martin Exp $ 2.\" 3.\" Copyright (c) 1999 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. 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 June 5, 1999 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 *basename" 42.Sh DESCRIPTION 43.Fn pidfile 44writes a file containing the process ID of the program to the 45.Pa /var/run 46directory. 47The file name has the form 48.Pa /var/run/basename.pid . 49If the 50.Ar basename 51argument is NULL, 52.Nm 53will determine the program name and use that instead. 54.Pp 55The pid file can be used as a quick reference if 56the process needs to be sent a signal. 57When the program exits, the pid file will be removed automatically, unless 58the program receives a fatal signal. 59.Pp 60Note that only the first invocation of 61.Nm 62causes a pid file to be written; subsequent invocations have no effect 63unless a new 64.Ar basename 65is supplied. 66If called with a new 67.Ar basename , 68.Fn pidfile 69will remove the old pid file and write the new one. 70.Sh RETURN VALUES 71.Fn pidfile 72returns 0 on success and -1 on failure. 73.Sh SEE ALSO 74.Xr atexit 3 75.Sh HISTORY 76The 77.Nm 78function call appeared in 79.Nx 1.5 . 80.Sh BUGS 81.Fn pidfile 82uses 83.Xr atexit 3 84to ensure the pidfile is unlinked at program exit. 85However, programs that use the 86.Xr _exit 2 87function (for example, in signal handlers) 88will not trigger this behaviour. 89