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