add manpage

3 files changed, 130 insertions, 0 deletions

diff --git a/Makefile b/Makefile
index fb1f502..8693606 100644
--- a/Makefile
+++ b/Makefile
@@ -12,4 +12,12 @@ all: $(ALL)
 clean: FRC
 	rm -f $(ALL)
 
+install: FRC all
+	mkdir -p $(DESTDIR)$(BINDIR) $(DESTDIR)$(MANDIR)/man1
+	install -m0755 $(ALL) $(DESTDIR)$(BINDIR)
+	install -m0644 $(ALL:=.1) $(DESTDIR)$(MANDIR)/man1
+
+README: reap.1
+	mandoc -Tutf8 $< | col -bx >$@
+
 FRC:
diff --git a/README b/README
new file mode 100644
index 0000000..3ef974d
--- /dev/null
+++ b/README
@@ -0,0 +1,50 @@
+REAP(1)                     General Commands Manual                    REAP(1)
+
+NAME
+     reap – run process until all its spawned processes are dead
+
+SYNOPSIS
+     reap [-vw] command line ...
+
+DESCRIPTION
+     The reap utility executes the given command line and ensures all spawned
+     processes are dead before it exits.
+
+     By default, it will start slaying the spawned processes when the main
+     process exits.  When the option -w is given, reap will instead wait for
+     the processes to terminate.
+
+     Upon receiving SIGINT or SIGTERM, reap will start slaying all children
+     immediately.
+
+     The options are as follows:
+
+     -w      Wait for all spawned processes to finish.
+
+     -v      Verbose mode, report what reap is doing.
+
+EXIT STATUS
+     The reap utility exits with the exit status of the spawned command.
+
+     On fatal errors, exit codes 111 is returned.
+
+ASSUMPTIONS
+     reap uses the PR_SET_CHILD_SUBREAPER feature of Linux.  Slaying the
+     children only works when the kernel configuration CONFIG_PROC_CHILDREN is
+     enabled.
+
+     reap can only work reliably when it has permission to kill all spawned
+     processes and they respect SIGTERM.
+
+AUTHORS
+     Leah Neukirchen <leah@vuxu.org>
+
+LICENSE
+     reap is in the public domain.
+
+     To the extent possible under law, the creator of this work has waived all
+     copyright and related or neighboring rights to this work.
+
+     http://creativecommons.org/publicdomain/zero/1.0/
+
+Void Linux                      August 13, 2019                     Void Linux
diff --git a/reap.1 b/reap.1
new file mode 100644
index 0000000..f5c8701
--- /dev/null
+++ b/reap.1
@@ -0,0 +1,72 @@
+.Dd August 13, 2019
+.Dt REAP 1
+.Os
+.Sh NAME
+.Nm reap
+.Nd run process until all its spawned processes are dead
+.Sh SYNOPSIS
+.Nm
+.Op Fl vw
+.Ar command\ line ...
+.Sh DESCRIPTION
+The
+.Nm
+utility executes the given command line and ensures
+all spawned processes are dead before it exits.
+.Pp
+By default, it will start slaying the spawned processes
+when the main process exits.
+When the option
+.Fl w
+is given,
+.Nm
+will instead wait for the processes to terminate.
+.Pp
+Upon receiving
+.Dv SIGINT
+or
+.Dv SIGTERM ,
+.Nm
+will start slaying all children immediately.
+.Pp
+The options are as follows:
+.Bl -tag -width Ds
+.It Fl w
+Wait for all spawned processes to finish.
+.It Fl v
+Verbose mode, report what
+.Nm
+is doing.
+.El
+.Sh EXIT STATUS
+The
+.Nm
+utility exits with the exit status of the spawned command.
+.Pp
+On fatal errors, exit codes 111 is returned.
+.Sh ASSUMPTIONS
+.Nm
+uses the
+.Dv PR_SET_CHILD_SUBREAPER
+feature of Linux.
+Slaying the children only works when
+the kernel configuration
+.Dv CONFIG_PROC_CHILDREN
+is enabled.
+.Pp
+.Nm
+can only work reliably when it has permission to kill all spawned
+processes and they respect
+.Dv SIGTERM .
+.Sh AUTHORS
+.An Leah Neukirchen Aq Mt leah@vuxu.org
+.Sh LICENSE
+.Nm
+is in the public domain.
+.Pp
+To the extent possible under law,
+the creator of this work
+has waived all copyright and related or
+neighboring rights to this work.
+.Pp
+.Lk http://creativecommons.org/publicdomain/zero/1.0/