diff --git a/docs/simexec.1 b/docs/simexec.1 index 5d79338..794b972 100644 --- a/docs/simexec.1 +++ b/docs/simexec.1 @@ -1,49 +1,79 @@ -.TH SIMEXEC 1 - +.\" Copyright (c) 2022–2024 DTB +.\" +.\" 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" .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 +. +.\" .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.