diff --git a/docs/simexec.1 b/docs/simexec.1 new file mode 100644 index 0000000..5d79338 --- /dev/null +++ b/docs/simexec.1 @@ -0,0 +1,49 @@ +.TH SIMEXEC 1 + +.SH NAME + +simexec \(en execute a program with the given argv + +.SH SYNOPSIS + +simexec +.RB [ pathname ] +.RB [ argv... ] + +.SH DESCRIPTION + +Simexec executes a given program with the given argv. + +.SH PITFALLS + +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. + +.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. + +.SH COPYRIGHT + +Public domain. + +.SH SEE ALSO + +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. diff --git a/src/simexec.c b/src/simexec.c new file mode 100644 index 0000000..54f087b --- /dev/null +++ b/src/simexec.c @@ -0,0 +1,35 @@ +/* + * Copyright (c) 2023 DTB + * SPDX-License-Identifier: AGPL-3.0-or-later + * + * This program is free software: you can redistribute it and/or modify it under + * the terms of the GNU Affero General Public License as published by the Free + * Software Foundation, either version 3 of the License, or (at your option) any + * later version. + * + * This program is distributed in the hope that it will be useful, but WITHOUT + * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS + * FOR A PARTICULAR PURPOSE. See the GNU Affero General Public License for more + * details. + * + * You should have received a copy of the GNU Affero General Public License + * along with this program. If not, see https://www.gnu.org/licenses/. + */ + +#include /* fprintf(3), NULL */ +#include /* execv(3), */ +#include /* EX_USAGE */ + +char *program_name = "simexec"; + +int main(int argc, char *argv[]){ + + if(argc < 2){ + fprintf(stderr, "Usage: %s binary argv...\n", + argv[0] == NULL ? program_name : argv[0] + ); + return EX_USAGE; + } + + execv(argv[1], &argv[2]); +}