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