diff --git a/docs/simexec.1 b/docs/run.1 similarity index 59% rename from docs/simexec.1 rename to docs/run.1 index 794b972..75b4154 100644 --- a/docs/simexec.1 +++ b/docs/run.1 @@ -3,52 +3,31 @@ .\" This work is licensed under CC BY-SA 4.0. To see a copy of this license, .\" visit . .\" -.TH SIMEXEC 1 2024-07-23 "Harakit-overgrown X.X.X" +.TH SIMEXEC 1 2024-07-24 "Harakit-overgrown X.X.X" .SH NAME -simexec \(en execute a program with argv +run \(en execute a program .\" .SH SYNOPSIS -simexec -.B binary argv... +run +.B binary argument... +.\" .SH DESCRIPTION -Execute a binary with a certain argv. +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. -.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) +.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 @@ -56,7 +35,8 @@ found. This is indistinguishable from the executed binary exiting with the same 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) value if invoked in an invalid manner. .\" @@ -76,4 +56,5 @@ Copyright \(co 2022–2024 DTB. License AGPLv3+: GNU AGPL version 3 or later 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.