overgrown/docs/run.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-24 "Harakit-overgrown X.X.X"
.SH NAME
run \(en execute a program
.\"
.SH SYNOPSIS

run
.B binary argument...
.\"
.SH DESCRIPTION
Execute a binary with arguments.
.\"
.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.

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.
.\"
.SH DIAGNOSTICS

.BR run (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.

.BR run (1)
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.