overgrown/docs/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 argv
.\"
.SH SYNOPSIS

simexec
.B binary argv...
.SH DESCRIPTION
Execute a binary with a certain argv.
.SH CAVEATS

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.

.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].

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

.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
.\"
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)

The C89 standard's draft, section 2.1.2.2: "Hosted environment".

POSIX.1-2017 System Interfaces: execv. Particularly under the RATIONALE section header.