1.\" $NetBSD: pidfile.3,v 1.13 2011/03/29 13:55:37 jmmv 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 March 23, 2011 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.Sh DESCRIPTION 43.Fn pidfile 44creates a file containing the process ID of the caller program. 45The pid file can be used as a quick reference if 46the process needs to be sent a signal. 47When the program exits, the pid file is removed automatically, unless 48the program receives a fatal signal. 49.Pp 50If 51.Ar path 52is 53.Dv NULL 54or a plain basename (a name containing no directory components), the pid file 55is created in the 56.Pa /var/run 57directory. 58The file name has the form 59.Pa /var/run/basename.pid . 60The basename part is either the value of 61.Ar path 62if it was not 63.Dv NULL , 64or the program name as returned by 65.Xr getprogname 3 66otherwise. 67.Pp 68If 69.Ar path 70is an absolute or relative path (i.e. it contains the 71.Sq / 72character), 73the pid file is created in the provided location. 74.Pp 75Note that only the first invocation of 76.Fn pidfile 77causes a pid file to be written; subsequent invocations have no effect 78unless a new 79.Ar path 80is supplied. 81If called with a new 82.Ar path , 83.Fn pidfile 84will remove the old pid file and write the new one. 85.Sh RETURN VALUES 86.Fn pidfile 87returns 0 on success and -1 on failure. 88.Sh SEE ALSO 89.Xr atexit 3 90.Sh HISTORY 91The 92.Fn pidfile 93function call appeared in 94.Nx 1.5 . 95Support for creating pid files in any arbitrary path was added in 96.Nx 6.0 . 97.Sh BUGS 98.Fn pidfile 99uses 100.Xr atexit 3 101to ensure the pid file is unlinked at program exit. 102However, programs that use the 103.Xr _exit 2 104function (for example, in signal handlers) 105will not trigger this behaviour. 106