stcall(3)						    ShapeTools Toolkit Library							 stcall(3)

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 termi-
       nation  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 con-
       dition, usually the contents of errno(3) after a failed system call.
       In the case of CHILD_KILLED, stCallCmdErrno contains the statBus 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

       Jurgen Nickelsen <nickel@cs.tu-berlin.de> and Andreas.Lampen@cs.tu-berlin.de

sttk-1.7						     Thu Jun 24 17:43:29 1993							 stcall(3)