.ig
 Copyright (C) 1993,1994 by the author(s).
 
 This software is published in the hope that it will be useful, but
 WITHOUT ANY WARRANTY for any part of this software to work correctly
 or as described in the manuals. See the ShapeTools Public License
 for details.

 Permission is granted to use, copy, modify, or distribute any part of
 this software but only under the conditions described in the ShapeTools 
 Public License. A copy of this license is supposed to have been given
 to you along with ShapeTools in a file named LICENSE. Among other
 things, this copyright notice and the Public License must be
 preserved on all copies.


Authors: Juergen Nickelsen (Juergen.Nickelsen@cs.tu-berlin.de)
	 Andreas Lampen (Andreas.Lampen@cs.tu-berlin.de)

$Header: stcall.3[4.0] Thu Jun 24 17:43:29 1993 andy@cs.tu-berlin.de frozen $
..
.TH stcall 3 "Thu Jun 24 17:43:29 1993" "sttk-1.7" "ShapeTools Toolkit Library"
.SH NAME
stCallEditor, stCallCmd, stCallCmdErrno, stFindProgram \- call command
processor with command string
.SH SYNOPSIS
#include <config.h>
.br
#include <sttk.h.h>
.sp
.ta 1c
int	stCallEditor (char *editor, char *file, char *contents, char **newcontents);
.sp
int	stCallCmd (char *commandProcessor, char *commandString);
.sp
int	stCallCmdErrno;
.sp
char*	stFindProgram (char *fileName)
.sp
.SH DESCRIPTION
\fIstCallEditor\fP calls editor \fIeditor\fP with file \fIfile\fP and
returns its  contents after the editor session in \fInewcontents\fP.
Return value is the length of the new text. On failure, 0 is returned
to indicate the error. Newcontents is \fInot\fP updated and points to
nowhere. On error the file will be removed.
If \fIcontents\fP 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.
.LP
\fIstCallCmd\fP invokes \fIcommandProcessor\fP as a child process
and writes \fIcommandString\fP 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.
.LP
\fIstFindProgram\fP returns the full pathname of \fIprogramName\fP if
program is found and executable. Otherwise NULL.
.SH ENVIRONMENT
.TP
PATH
List of colon-separated directoriy names where execvp(3) searches for
the program to execute (default /bin:/usr/bin:/usr/ucb).
.SH SEE ALSO
wait(2)
.SH 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:
.TP 3.5c
CMDPROC_EMPTY
An empty or NULL string has been supplied for commandProcessor.
.TP
NO_MORE_CORE
A call to malloc(3) or calloc(3) returned a NULL pointer.
.TP
FORK_FAILED
fork(2) could not create a child process.
.TP
PIPE_FAILED
A call to pipe(2) failed.
.TP
WAIT_ERROR
A call to wait(2) failed.
.TP
EXEC_FAILED
execvp(3) could not execute commandProcessor.
.TP
CHILD_KILLED
The child process was killed by an uncaught signal.
.TP
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.
.TP
NO_PROGRAM
commandProcessor could not be found.
.LP
For the most error conditions the integer variable
\fIstCallCmdErrno\fP (declared in sttk.h) contains additional
information about the error condition, usually the contents of
errno(3) after a failed system call.
.br
In the case of CHILD_KILLED, stCallCmdErrno contains the statßus of
the child process as reported by wait(2).
.SH BUGS
On systems where no usable vfork(2) is available, the value of
stCallCmdErrno does not make sense in case of EXEC_FAILED.
.LP
Under IRIX stCallCmd sometimes (or always?) returns WAIT_ERROR where
it should be EXEC_FAILED, NO_PROGRAM, or WRITE_FAILED.
.SH AUTHORS
Jürgen Nickelsen <nickel@cs.tu-berlin.de> and
Andreas.Lampen@cs.tu-berlin.de