80 lines
2.2 KiB
Groff
80 lines
2.2 KiB
Groff
.\" 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.
|