.\" $Id: forever.man,v 1.5 2012/10/09 13:43:30 ksb Exp $
.\" by Kevin 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/man1/forever.1
.\" $Deinstall: ${rm-rm} -f $DESTDIR/usr/local/man/[cm]a[nt]1/forever.1*
.TH FOREVER 1 LOCAL
.SH NAME
forever \- block until interrupted
.SH SYNOPSIS
.ds PN "forever
\fI\*(PN\fP \fIlabel\fP
.br
\fI\*(PN\fP \fB\-h\fP
.br
\fI\*(PN\fP \fB\-V\fP

.SH DESCRIPTION
\fIForever\fP blocks until an externally generated signal terminates
it.  The basic function is expressed in \fBperl\fP as:
.nf
	perl \-e "use POSIX qw(pause); pause() while (1);"
.fi
.P
In some ways this resembles \fBsleep\fP(1), but it never exits without
some external intervention (usually a signal). See \fBkill\fP(1).
.P
The most common way to terminate \fI\*(PN\fP is via \fBpkill\fP(1).
Usually by specifying a \fIppid\fP, a \fIpattern\fP, and optionally
a known \fIuid\fP or matching the \fIlabel\fP provided.
.P
The program also calls \fBclose\fP(2) on \fIstdin\fP, \fIstdout\fP, and
\fIstderr\fP to release any pipes that might be open.  If you want to
hold a pipe open duplicate the descriptor to a slot above 2.
This adds some code to the \fBperl\fP version:
.nf
	\fI...\fP; close(STDIN);close(STDOUT);close(STDERR); pause() \fI...\fP
.fi

.SH OPTIONS
\fIForever\fP doesn't read any environment variable for options.
.TP
\fB\-h\fP
Print a brief help message.
.TP
\fB\-V\fP
Show only the version information for \fI\*(PN\fP.

.SH EXAMPLES
.TP
.nf
wrapw \-mN /var/run/tiger \fI...\fP \-\- \fI\*(PN\fP honey
.fi
Start a persistent instance of \fBwrapw\fP on a \*(lqlocally known\*(rq
unix domain socket.  This is intended to run until system shutdown.
.TP
.nf
pkill \-TERM  \-fU ${USER:-`id \-un`} "forever.*honey"
.fi
Terminate the \fI\*(PN\fP that holds the previous \fBwrapw\fP diversion open.
We specify our login to limit the signal to just our login.
.TP
.nf
\fI\*(PN\fP \-V
.fi
Output the version of \fI\*(PN\fP.  Note this doesn't block forever
(nor does \fB\-h\fP's help output).

.SH BUGS
This should really be an option to \fBsleep\fP(1), like \fB\-F\fP.

.SH AUTHOR
KS Braunsdorf, NonPlayer Character Guild
.br
msrc at ksb single-dot npcguild.org

.SH "SEE ALSO"
.hlm 0
sh(1), sleep(1), kill(1), pkill(1),
wrapw(1L), ptbw(1L), opal(1L), xclate(1L), gtfw(1L), sshw(1L),
close(2)