.\" $Id: daemon.man,v 1.11 2012/02/29 18:45:36 ksb Exp $
.\" by KS Braunsdorf
.\" $Compile: Display%h
.\" $Display: ${groff:-groff} -Tascii -man %f |${PAGER:-less}
.\" $Display(*): ${groff:-groff} -T%s -man %f
.\" $Install: %b -mDeinstall %o %f && cp %f $DESTDIR/usr/local/man/man8/daemon.8
.\" $Deinstall: ${rm-rm} -f $DESTDIR/usr/local/man/[cm]a[nt]8/daemon.8*
.TH DAEMON 8 LOCAL
.SH NAME
daemon - run a process detached from the current session
.SH SYNOPSIS
.ds PN "daemon
\fI\*(PN\fP [\fB\-c\fP\fBf\fP] [\fB\-p\fP\~\fIpidfile\fP] [\fB\-u\fP\~\fIuser\fP[:\fIgroup\fP]] \fIutility\fP [\fIarguments\fP]
.br
\fI\*(PN\fP \fB\-h\fP
.br
\fI\*(PN\fP \fB\-V\fP
.br

.SH DESCRIPTION
The positional parameter \fIutility\fP
is the path to the new detached program.
.SH OPTIONS
If the program is called as \fI\*(PN\fP then no options are forced.
.TP
\fB\-c\fP
Change the current working directory to the root of the filesystem
before executing \fIutility\fP.
.TP
\fB\-f\fP
Redirect standard input, output and error to \fB/dev/null\fP.
.TP
\fB\-h\fP
Print the standard help message.
.TP
\fB\-p\fP \fIpidfile\fP
Write new process ID to this file, delete on failure.  Don't start
the \fIutility\fP if the process ID in \fIpidfile\fP is presently
running.  Specification of dash (\fB\-\fP) as the \fIpidfile\fP
is an extension of the program which builds a default name
from the basename of the \fIutility\fP under \fI/var/run\fP.
.TP
\fB\-u\fP \fIuser\fP[:\fIgroup\fP]
Drop credentials to this login before utility execution.
Whan a \fIgroup\fP is specified it is set by a call to
\fBsetgid\fP(2) after the call to \fBinitgroups\fP.
The original credentials must allow the \fBsetuid\fP(2) to
succeed (viz. only the superuser can do this).
The empty \fIuser\fP is mapped to \fBnobody\fP.
.TP
\fB\-V\fP
Show version information.

.SH EXAMPLES
.TP
\fI\*(PN\fP sleep 1000
Push a \fBsleep\fP(1) command into the background, but don't track the
process ID.
.TP
\fI\*(PN\fP \-u nobody /usr/local/libexec/unixstats \-p113
Run the PEG data collector \fBunixstats\fP as \fBnobody\fP.
.TP
\fI\*(PN\fP \-u nobody:sample /usr/local/libexec/unixstats \-p113
Same as the previous, but run the collector \fBnobody\fP in group \fBsample\fP.
.TP
\fI\*(PN\fP \-c \-p /var/run/dealer.pid \-u house /usr/local/libexec/dealer
Run the \fIdealer\fP program as \fBhouse\fP with a pid file in
\fI/var/run/dealer.pid\fP to prevent multiple instances.
.TP
\fI\*(PN\fP \-c \-p \- \-u house /usr/local/libexec/dealer
Same as the above command, but let \fI\*(PN\fP build \fIpidfile\fP.
.TP
\fBpkill\fP \-QUIT \-F /var/run/dealer.pid \-U house
Safely terminate any running \fIdealer\fP process.  By including both
the \fIpidfile\fP and the login name we limit \fBpkill\fP's actions
enough that we are unlikely to shoot an innocent (unrelated) process.
.TP
\fI\*(PN\fP \-V
See the informative version output, which includes the \fBprintf\fP(3)
format used to construct default \fIpidfile\fP names.

.SH BUGS
The addition of a \fIgroup\fP is non-portable, so it is not listed in
the on-line help output.
.P
The \fBflock\fP(2) system call the BSD version of this program used
to lock \fIpidfile\fP is, sadly, not portable (anymore).  This version
only locks the \fIpidfile\fP for updates.
.P
A \fIpidilfe\fP left-over from a previous system boot may contain
the process ID of an unrelated process, which will keep \fI\*(PN\fP
from starting a new instance.  Always clean \fI/var/run\fP at system
boot to prevent this bug.
.P
A \fIpidfile\fP with a non-numeric string in it prevents \fI\*(PN\fP
from \fBever\fP starting a process, or updating the file.  This is
also a feature.
For example I use the string \*(lq#locked\*(rq to denote an
explicitly locked facillity.  A file with only white-space in it
is still going to block the process, so check for just a newline in it.
.P
The exit codes are not from \fBsysexits\fP(3).  They are 1 for for
failed system calls, 2 for failure to build or update the \fIpidfile\fP,
and 3 when the process in the \fIpidfile\fP is running or the file is
removed while we are updating it.

.SH AUTHOR
KS Braunsdorf with liberal consultation from the FreeBSD version.
.br
NonPlayer Character Guild
.br
op at ksb dot npc guild dot orgspam-me-not

.SH "SEE ALSO"
.hlm 0
sh(1), nohup(1), op(1l)