---
name: "stcall"
section: "3"
platform: "linux"
package: "atfs-dev"
version: "1.4pl6-15+b1"
release: "Debian 12 (Bookworm)"
platforms: ["linux"]
url: "https://new.carta.tech/stcall"
---

# stcall(3)

call command processor with command string

## NAME

stCallEditor, stCallCmd, stCallCmdErrno, stFindProgram - call command processor with command string

## 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)

## DESCRIPTION

*stCallEditor* calls editor *editor* with file *file* and returns its  contents after the editor session in *newcontents*. Return value is the length of the new text. On failure, 0 is returned to indicate the error. Newcontents is *not* updated and points to nowhere. On error the file will be removed. If *contents* points to a valid text, this text is put (not appended) into the temporary file before editor starts. Contents must be NULL terminated, otherwise strange things will happen.

*stCallCmd* invokes *commandProcessor* as a child process and writes *commandString* to its standard input. The current process waits for termination of the child process. stCallCmd returns the exit status of the child process reported by [wait(2)](/wait/2.md). 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.) The command processor program is searched for in the directories given in the environment variable PATH. If commandString does not end with a newline, a newline is added.

*stFindProgram* returns the full pathname of *programName* if program is found and executable. Otherwise NULL.

## ENVIRONMENT

- PATH

  List of colon-separated directoriy names where [execvp(3)](/execvp/3.md) searches for the program to execute (default /bin:/usr/bin:/usr/ucb).

## SEE ALSO

[wait(2)](/wait/2.md)

## DIAGNOSTICS

On a successful call stCallCmd returns the exit status of the child process. If an error occured, stCallCmd returns a negative number as defined in sttk.h:

- CMDPROC\_EMPTY

  An empty or NULL string has been supplied for commandProcessor.

- NO\_MORE\_CORE

  A call to [malloc(3)](/malloc/3.md) or [calloc(3)](/calloc/3.md) returned a NULL pointer.

- FORK\_FAILED

  [fork(2)](/fork/2.md) could not create a child process.

- PIPE\_FAILED

  A call to [pipe(2)](/pipe/2.md) failed.

- WAIT\_ERROR

  A call to [wait(2)](/wait/2.md) failed.

- EXEC\_FAILED

  [execvp(3)](/execvp/3.md) could not execute commandProcessor.

- CHILD\_KILLED

  The child process was killed by an uncaught signal.

- WRITE\_FAILED

  [write(2)](/write/2.md) 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)](/errno/3.md) after a failed system call.\
 In the case of CHILD\_KILLED, stCallCmdErrno contains the statßus of the child process as reported by [wait(2)](/wait/2.md).

## BUGS

On systems where no usable [vfork(2)](/vfork/2.md) is available, the value of stCallCmdErrno does not make sense in case of EXEC\_FAILED.

Under IRIX stCallCmd sometimes (or always?) returns WAIT\_ERROR where it should be EXEC\_FAILED, NO\_PROGRAM, or WRITE\_FAILED.

## AUTHORS

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