trinity/overgrown
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

simexec.1: Fix man page

Browse Source
This commit is contained in:
dtb 2024-07-23 18:51:14 -06:00
parent 6bba80e3f9
commit fc33683382
1 changed files with 62 additions and 32 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

94
docs/simexec.1
View File

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