run.1: rename man page from simexec.1

This commit is contained in:
dtb 2024-07-24 23:45:16 -06:00
parent e0f9641e93
commit 2337cedd77
Signed by: trinity
GPG Key ID: 34C0543BBB6AF81B

View File

@ -3,52 +3,31 @@
.\" This work is licensed under CC BY-SA 4.0. To see a copy of this license, .\" 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/>. .\" visit <http://creativecommons.org/licenses/by-sa/4.0/>.
.\" .\"
.TH SIMEXEC 1 2024-07-23 "Harakit-overgrown X.X.X" .TH SIMEXEC 1 2024-07-24 "Harakit-overgrown X.X.X"
.SH NAME .SH NAME
simexec \(en execute a program with argv run \(en execute a program
.\" .\"
.SH SYNOPSIS .SH SYNOPSIS
simexec run
.B binary argv... .B binary argument...
.\"
.SH DESCRIPTION .SH DESCRIPTION
Execute a binary with a certain argv. Execute a binary with arguments.
.\"
.SH CAVEATS .SH CAVEATS
Non-binary programs cannot be executed on their own. The PATH environment 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 variable is not used and a valid pathname (relative or absolute) must be
specified. 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 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 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. 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 .SH DIAGNOSTICS
.BR simexec (1) .BR run (1)
exits with the returned value of exits with the returned value of
.BR execv (3p), .BR execv (3p),
which will be 255 if an error occurs in execution, such as the binary not being which will be 255 if an error occurs in execution, such as the binary not being
@ -56,7 +35,8 @@ found.
This is indistinguishable from the executed binary exiting with the same This is indistinguishable from the executed binary exiting with the same
status. status.
Simexec will print a error message and return the proper .BR run (1)
will print a error message and return the proper
.BR sysexits.h (3) .BR sysexits.h (3)
value if invoked in an invalid manner. value if invoked in an invalid manner.
.\" .\"
@ -76,4 +56,5 @@ Copyright \(co 20222024 DTB. License AGPLv3+: GNU AGPL version 3 or later
The C89 standard's draft, section 2.1.2.2: "Hosted environment". The C89 standard's draft, section 2.1.2.2: "Hosted environment".
POSIX.1-2017 System Interfaces: execv. Particularly under the RATIONALE section header. POSIX.1-2017 System Interfaces: execv. Particularly under the RATIONALE section
header.