Makefile: add simexec(1)

Makefile

@@ -32,7 +32,7 @@ RUSTLIBS = --extern getopt=build/o/libgetopt.rlib \
 CFLAGS += -I$(SYSEXITS)
 
 .PHONY: all
-all: dj false fop hru intcmp mm npc rpn scrut str strcmp swab true
+all: dj false fop hru intcmp mm npc rpn simexec scrut str strcmp swab true
 
 # keep build/include until bindgen(1) has stdin support
 # https://github.com/rust-lang/rust-bindgen/issues/2703
@@ -132,6 +132,11 @@ scrut: build/bin/scrut
 build/bin/scrut: src/scrut.c build
 	$(CC) $(CFLAGS) -o $@ src/scrut.c
 
+.PHONY: simexec
+simexec: build/bin/simexec
+build/bin/simexec: src/simexec.c build
+	$(CC) $(CFLAGS) -o $@ src/simexec.c
+
 .PHONY: str
 str: build/bin/str
 build/bin/str: src/str.c build

docs/simexec.1

@@ -1,49 +1,79 @@
-.TH SIMEXEC 1
-
+.\" Copyright (c) 2022–2024 DTB <trinity@trinity.moe>
+.\"
+.\" This work is licensed under CC BY-SA 4.0. To see a copy of this license,
+.\" visit <http://creativecommons.org/licenses/by-sa/4.0/>.
+.\"
+.TH SIMEXEC 1 2024-07-23 "Harakit-overgrown X.X.X"
 .SH NAME
-
-simexec \(en execute a program with the given argv
-
+simexec \(en execute a program with argv
+.\"
 .SH SYNOPSIS
 
 simexec
-.RB [ pathname ]
-.RB [ argv... ]
-
+.B binary argv...
 .SH DESCRIPTION
+Execute a binary with a certain argv.
+.SH CAVEATS
 
-Simexec executes a given program with the given argv.
+Non-binary programs cannot be executed on their own. The PATH environment
+variable is not used and a valid pathname (relative or absolute) must be
+specified.
 
-.SH PITFALLS
+.BR simexec (1)
+requires caution.
+.B argv
+are not just the operands for the binary but in fact the direct
+.B argv
+it will receive in runtime;
+the first argv entry is the program\(cqs name, and omitting this, though valid
+use of
+.BR simexec (1),
+can break false assumptions made by programmers.
+for example, the
+.BR true (1)
+implementation in the GNU coreutils project suffers a segmentation fault it is
+given no argv[0].
 
-Non-binary programs cannot be executed. The PATH environment variable is not used and a valid pathname (relative or absolute) must be specified.
-.PP
-Simexec relies on the user to take proper precautions.
-argv is not just the operands for the program but in fact directly the argv it will receive in runtime;
-the first argv entry is the program's name, and forgoing this, though acceptable by simexec, can break customary assumptions.
-for example, the true(1) implementation in the GNU coreutils suffers a segmentation fault if there is no argv[0].
-.PP
-While POSIX.1-2017 doesn't mandate there being an argv[0] per se a Strictly Conforming POSIX Application must pass an argv[0].
-It has also been said that those who do not pass an argv[0] are mean and nasty and smell of elderberries.
-.PP
-Simexec directly uses the execv library function. It cannot execute shell scripts intelligently (via shebang).
-It is inadviseable to use simexec as an alternative to simply calling a program, and in fact probably inadviseable to use simexec at all.
+While POSIX.1-2017 doesn't mandate there being an argv[0] per se, a Strictly
+Conforming POSIX Application must pass an argv[0]. It has also been said that
+those who do not pass an argv[0] are mean and nasty and smell of elderberries.
 
+.BR simexec (1)
+directly uses the
+.BR execv (3p)
+library function. It cannot execute shell scripts intelligently (via shebang).
+It is inadviseable to use
+.BR simexec (1)
+to simply execute a program when other methods would suffice.
+.\"
 .SH DIAGNOSTICS
 
-Simexec returns the value of execv(3), which will be -1 (or 0xFF; 255) if an error occurs.
-This is not distinguishable from the executed program returning the same exit status.
-.PP
-Simexec will print a error message and return the proper sysexits(3) value if used in an invalid manner.
+.BR simexec (1)
+exits with the returned value of
+.BR execv (3p),
+which will be 255 if an error occurs in execution, such as the binary not being
+found.
+This is indistinguishable from the executed binary exiting with the same
+status.
 
+Simexec will print a error message and return the proper
+.BR sysexits.h (3)
+value if invoked in an invalid manner.
+.\"
+.SH AUTHOR
+
+Written by DTB
+.MT trinity@trinity.moe
+.ME .
+.\"
 .SH COPYRIGHT
-
-Public domain.
-
+.\"
+Copyright \(co 2022–2024 DTB. License AGPLv3+: GNU AGPL version 3 or later
+<https://gnu.org/licenses/gpl.html>.
+.\"
 .SH SEE ALSO
+.BR execv (3p)
 
-exec(3)
-.PP
 The C89 standard's draft, section 2.1.2.2: "Hosted environment".
-.PP
+
 POSIX.1-2017 System Interfaces: execv. Particularly under the RATIONALE section header.

src/simexec.c

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2023 DTB <trinity@trinity.moe>
+ * Copyright (c) 2022–2024 DTB <trinity@trinity.moe>
  * SPDX-License-Identifier: AGPL-3.0-or-later
  *
  * This program is free software: you can redistribute it and/or modify it under
@@ -23,7 +23,6 @@
 char *program_name = "simexec";
 
 int main(int argc, char *argv[]){
-
 	if (argc < 2) {
 		fprintf(stderr, "Usage: %s binary argv...\n",
 			argv[0] == NULL ? program_name : argv[0]