171 lines
4.6 KiB
Groff
171 lines
4.6 KiB
Groff
.\" $NetBSD: pidfile.3,v 1.15 2016/04/11 08:49:57 wiz Exp $
|
|
.\"
|
|
.\" Copyright (c) 1999, 2016 The NetBSD Foundation, Inc.
|
|
.\" All rights reserved.
|
|
.\"
|
|
.\" This code is derived from software contributed to The NetBSD Foundation
|
|
.\" by Jason R. Thorpe and Roy Marples.
|
|
.\"
|
|
.\" Redistribution and use in source and binary forms, with or without
|
|
.\" modification, are permitted provided that the following conditions
|
|
.\" are met:
|
|
.\" 1. Redistributions of source code must retain the above copyright
|
|
.\" notice, this list of conditions and the following disclaimer.
|
|
.\" 2. Redistributions in binary form must reproduce the above copyright
|
|
.\" notice, this list of conditions and the following disclaimer in the
|
|
.\" documentation and/or other materials provided with the distribution.
|
|
.\"
|
|
.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS
|
|
.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED
|
|
.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
|
|
.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS
|
|
.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
|
|
.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
|
|
.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
|
|
.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
|
|
.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
|
|
.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
|
|
.\" POSSIBILITY OF SUCH DAMAGE.
|
|
.\"
|
|
.Dd April 10, 2016
|
|
.Dt PIDFILE 3
|
|
.Os
|
|
.Sh NAME
|
|
.Nm pidfile
|
|
.Nd write a daemon pid file
|
|
.Sh LIBRARY
|
|
.Lb libutil
|
|
.Sh SYNOPSIS
|
|
.In util.h
|
|
.Ft int
|
|
.Fn pidfile "const char *path"
|
|
.Ft pid_t
|
|
.Fn pidfile_lock "const char *path"
|
|
.Ft pid_t
|
|
.Fn pidfile_read "const char *path"
|
|
.Ft int
|
|
.Fn pidfile_clean "void"
|
|
.Sh DESCRIPTION
|
|
.Fn pidfile
|
|
and
|
|
.Fn pidfile_lock
|
|
create and lock a file containing the process ID of the calling program.
|
|
The pid file can be used as a quick reference if
|
|
the process needs to be sent a signal.
|
|
The pid file is truncated and removed automatically when the program exits,
|
|
unless the program receives a fatal signal.
|
|
.Pp
|
|
If
|
|
.Ar path
|
|
is
|
|
.Dv NULL
|
|
or a plain basename (a name containing no directory components), the pid file
|
|
is created in the
|
|
.Pa /var/run
|
|
directory.
|
|
The file name has the form
|
|
.Pa /var/run/basename.pid .
|
|
The basename part is either the value of
|
|
.Ar path
|
|
if it was not
|
|
.Dv NULL ,
|
|
or the program name as returned by
|
|
.Xr getprogname 3
|
|
otherwise.
|
|
.Pp
|
|
If
|
|
.Ar path
|
|
is an absolute or relative path (i.e. it contains the
|
|
.Sq /
|
|
character),
|
|
the pid file is created in the provided location.
|
|
.Pp
|
|
If called with a new
|
|
.Ar path ,
|
|
.Fn pidfile
|
|
and
|
|
.Fn pidfile_lock
|
|
will remove the old pid file.
|
|
.Pp
|
|
The pid file is truncated, so these functions can be called multiple times and
|
|
allow a child process to take over the lock.
|
|
.Pp
|
|
.Fn pidfile_read
|
|
will read the last pid file created, or specified by
|
|
.Ar path ,
|
|
and return the process ID it contains.
|
|
.Pp
|
|
.Fn pidfile_clean
|
|
will
|
|
.Xr ftruncate 2 ,
|
|
.Xr close 2 ,
|
|
and
|
|
.Xr unlink 2
|
|
the last opening pid file if, and only if, the current process wrote it.
|
|
This function should be called if the program needs to call
|
|
.Xr _exit 2
|
|
(such as from a signal handler) and needs to clean up the pid file.
|
|
.Sh RETURN VALUES
|
|
.Fn pidfile
|
|
and
|
|
.Fn pidfile_clean
|
|
returns 0 on success and \-1 on failure.
|
|
.Pp
|
|
.Fn pidfile_lock
|
|
returns 0 on success.
|
|
Otherwise, the process ID who owns the lock is returned and if that
|
|
cannot be derived then \-1 is returned.
|
|
.Pp
|
|
.Fn pidfile_read
|
|
returns the process ID if known, otherwise \-1.
|
|
.Sh ERRORS
|
|
The
|
|
.Fn pidfile
|
|
and
|
|
.Fn pidfile_lock
|
|
functions will fail if:
|
|
.Bl -tag -width Er
|
|
.It Bq Er EEXIST
|
|
Some process already holds the lock on the given pid file, meaning that a
|
|
daemon is already running.
|
|
.It Bq Er ENAMETOOLONG
|
|
Specified pidfile's name is too long.
|
|
.El
|
|
.Sh SEE ALSO
|
|
.Xr flock 2 ,
|
|
.Xr atexit 3
|
|
.Sh HISTORY
|
|
The
|
|
.Fn pidfile
|
|
function call appeared in
|
|
.Nx 1.5 .
|
|
Support for creating pid files in any arbitrary path was added in
|
|
.Nx 6.0 .
|
|
.Pp
|
|
The
|
|
.Fn pidfile_lock ,
|
|
.Fn pidfile_read ,
|
|
and
|
|
.Fn pidfile_clean
|
|
function calls appeared in
|
|
.Nx 8 .
|
|
.Sh CAVEATS
|
|
.Fn pidfile
|
|
and
|
|
.Fn pidfile_lock
|
|
use
|
|
.Xr atexit 3
|
|
to ensure the pid file is cleaned at program exit.
|
|
However, programs that use the
|
|
.Xr _exit 2
|
|
function (for example, in signal handlers)
|
|
will not trigger this behaviour and should call
|
|
.Fn pidfile_clean .
|
|
Like-wise, if the program creates a pid file before
|
|
.Xr fork 2 Ns ing
|
|
a child to take over, it should use the
|
|
.Xr _exit 2
|
|
function instead of returning or using the
|
|
.Xr exit 3
|
|
function to ensure the pid file is not cleaned.
|