stcall(3)

💖 stcall(3) — the "call a command processor with a command string" page 💖

okay bestie, welcome to stcall, part of the ShapeTools Toolkit Library. this is the page for stCallEditor, stCallCmd, stCallCmdErrno and stFindProgram — yes it's giving "four functions, one manpage, one chaotic group chat" and honestly? iconic. grab a snack, we're doing this. 🍓

---

✨ NAME ✨

stCallEditor, stCallCmd, stCallCmdErrno, stFindProgram — call command processor with command string. that's the whole vibe. 💅

---

🌸 SYNOPSIS 🌸

#include <config.h>
#include <sttk.h.h>

int stCallEditor (char *editor, char *file, char *contents, char
**newcontents);

int stCallCmd (char *commandProcessor, char *commandString);

int stCallCmdErrno;

char*stFindProgram (char *fileName)

lowkey note that the include is literally sttk.h.h and the stFindProgram line has no space before the *. i am not touching a single character of that, that's the original's whole aesthetic. 🎀

---

🦋 DESCRIPTION 🦋

stCallEditor 💖

so stCallEditor calls up editor editor on file file, and then hands you back its contents after the editor session in newcontents. the return value? the length of the new text. periodt.

if it fails, 0 is returned to signal the error. on failure newcontents is not updated and points to nowhere (rip). and on error, the file will be removed — yes, gone, deleted, evaporated. 😭

if contents points to a valid text, that text gets put (not appended!! we're replacing, not stacking) into the temporary file before the editor starts.

🚨 contents must be NULL terminated, otherwise strange things will happen. and when the manpage says strange things, bestie, it means strange things. don't test it. 💀

stCallCmd ✨

stCallCmd invokes commandProcessor as a child process and writes commandString to its standard input. the current process then waits for the child process to terminate — no multitasking, no cutting the line, we're waiting. 🫶

stCallCmd returns the exit status of the child process as reported by wait(2).

the commandProcessor string may contain command line arguments to the command processor, separated by whitespace. (this is necessary for some programs to make them read commands from standard input — iykyk.)

the command processor program is searched for in the directories given in the environment variable PATH.

and if commandString doesn't end with a newline, a newline is added. we're polite like that. 🌈

stFindProgram 🔍

stFindProgram returns the full pathname of programName if the program is found and executable. otherwise it returns NULL. simple as that, no notes. 💅

---

🌟 ENVIRONMENT 🌟

• PATH — list of colon-separated directoriy names where execvp(3) searches for the program to execute (default /bin:/usr/bin:/usr/ucb).

yes it says "directoriy". we're keeping it. it's part of the family now. 🙈

---

👀 SEE ALSO 👀

• wait(2)

---

🩺 DIAGNOSTICS 🩺

on a successful call, stCallCmd returns the exit status of the child process. if an error occurred, stCallCmd returns a negative number as defined in sttk.h:

• CMDPROC_EMPTY — an empty or NULL string has been supplied for commandProcessor. (you gave it nothing, bestie, it's giving nothing back.)
• NO_MORE_CORE — a call to malloc(3) or calloc(3) returned a NULL pointer. 💀
• FORK_FAILED — fork(2) could not create a child process.
• PIPE_FAILED — a call to pipe(2) failed.
• WAIT_ERROR — a call to wait(2) failed.
• EXEC_FAILED — execvp(3) could not execute commandProcessor.
• CHILD_KILLED — the child process was killed by an uncaught signal. 😭
• WRITE_FAILED — write(2) could not write commandString to the pipe. this usually happens when commandProcessor does not read its standard input and terminates before commandString is written.
• NO_PROGRAM — commandProcessor could not be found.

for the most error conditions, the integer variable stCallCmdErrno (declared in sttk.h) contains additional information about the error condition — usually the contents of errno(3) after a failed system call.

in the case of CHILD_KILLED, stCallCmdErrno contains the status of the child process as reported by wait(2).

---

💀 BUGS 💀

• on systems where no usable vfork(2) is available, the value of stCallCmdErrno does not make sense in case of EXEC_FAILED. like, it's there, it's just lying to you. 🙈
• under IRIX, stCallCmd sometimes (or always?) returns WAIT_ERROR where it should be EXEC_FAILED, NO_PROGRAM, or WRITE_FAILED. IRIX really said "mystery box" and we're all just living with it. 😭

---

👑 AUTHORS 👑

Jürgen Nickelsen <nickel@cs.tu-berlin.de> and Andreas.Lampen@cs.tu-berlin.de

---

and that's the page, bestie! 🎀 this whole thing came from sttk-1.7, dated Thu Jun 24 17:43:29 1993 — yes, 1993, it's vintage, it's archival, it's main character energy from another era. mwah. 💋 ✨🦋🌸