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). 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)
searches for the program to execute (default
/bin:/usr/bin:/usr/ucb).
SEE ALSO
wait(2)
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) 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 statßus 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.
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