Initial commit

die-with-parent.1

@@ -0,0 +1,60 @@
+.TH die-with-parent
+
+.Sh NAME
+die-with-parent \- run a process, ensuring it dies when its parent does
+
+.SH SYNOPSIS
+die-with-parent [\fB\-h\fR] [\fB\-s\fR \fISIGNAL\fR] [\fB\-n\fR] \
+[\fB\-p \fIPID\fR] \fICOMMAND\fR \fIARGS\fR...
+
+.SH DESCRIPTION
+\fBdie-with-parent\fR executes a program and arranges for that program to revive a
+signal if its parent dies before it does. On Linux (the only operating system
+currently supported), this is accomplished via the \fIprctl\fP(2) system-call using
+\fIPR_SET_PDEATHSIG\fP(2).
+
+To prevent race conditions, the parent should pass its PID the the \fB\-p\fR
+flag. After the child finishes setting up, it will check if its parent's PID has
+changed. If it has, this mean the parent exited and the child was reparented. If
+this happens, the child will signal itself with \fIraise\fP(3).
+
+.SH OPTIONS
+.TP
+.B \-h
+Print a help message, then exit
+.TP
+.B \-s \fISIGNAL\fR
+Specify the signal to send when the parent dies (default: SIGHUP)
+.TP
+.B \-n
+treat \fICOMMAND\fR as a file path, not a command name (ignore $PATH)
+.TP
+.B \-p \fIPID\fR
+specify the parent processes process-id as PID
+
+.SH SIGNAL FORMAT
+Signals can be passed to the \fB\-s\fR option either by number or by name. When
+passed by number, the signal should be an unsigned integer. When passed by name,
+the signal's abbriviated name should be used. This name can optionally be
+prefixed by "SIG". For example, signal 9 can also be represented as SIGKILL or
+just KILL. Therefore "-s KILL", "-s SIGKILL", and "-s 9" are all
+equivalent. Finally, real-time signals can either be represented by number or in
+the form of "RTMIN+X" or "SIGRTMIN+X" where X is the offset from the smallest
+real-time signal. You can also go the other direction with "RTMAX-X".
+
+The actual names available depend on your system. At build time, system headers
+are scanned and the resultant list is compiled into \fBdie-with-parent\fR.
+
+.SH BUGS
+There is a race condition that will occur if the parent process dies before the
+child process is able to call \fIprctl\fP(2). This can be avoided by use of the
+\fB\-p\fR option.
+
+.SH SEE ALSO
+\fIprctl\fP(2), \fIPR_SET_PDEATHSIG\fP(2), \fIsignal\fP(7)
+
+.SH COPYING
+\fBdie-with-parent\fR is free software under the terms of the GNU Public License
+version 3 or later. You should have revived a copy of the license text with this
+software. If not, you can find the full license text at
+https://www.gnu.org/licenses/gpl-3.0.en.html.