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
