X-Git-Url: https://git.saurik.com/wxWidgets.git/blobdiff_plain/e8482f24cfc00645607f8526fde38d39e0dcaa63..9e3229b777e8c4b97daa4402f76591fe3dea0dc0:/docs/latex/wx/process.tex diff --git a/docs/latex/wx/process.tex b/docs/latex/wx/process.tex index 8a15c8f363..2994063100 100644 --- a/docs/latex/wx/process.tex +++ b/docs/latex/wx/process.tex @@ -1,6 +1,6 @@ \section{\class{wxProcess}}\label{wxprocess} -The objects of this class are used in conjunction with +The objects of this class are used in conjunction with the \helpref{wxExecute}{wxexecute} function. When a wxProcess object is passed to wxExecute(), its \helpref{OnTerminate()}{wxprocessonterminate} virtual method is called when the process terminates. This allows the program to be @@ -14,6 +14,15 @@ However, if it is not processed, the object will delete itself and so the library users should only delete those objects whose notifications have been processed (and call \helpref{Detach()}{wxprocessdetach} for others). +wxProcess also supports IO redirection of the child process. For this, you have +to call its \helpref{Redirect}{wxprocessredirect} method before passing it to +\helpref{wxExecute}{wxexecute}. If the child process was launched successfully, +\helpref{GetInputStream}{wxprocessgetinputstream}, +\helpref{GetOutputStream}{wxprocessgetoutputstream} and +\helpref{GetErrorStream}{wxprocessgeterrorstream} can then be used to retrieve +the streams corresponding to the child process stdandard output, input and +error output respectively. + \wxheading{Derived from} \helpref{wxEvtHandler}{wxevthandler} @@ -22,6 +31,11 @@ processed (and call \helpref{Detach()}{wxprocessdetach} for others). +\wxheading{See also} + +\helpref{wxExecute}{wxexecute}\\ +\helpref{exec sample}{sampleexec} + \latexignore{\rtfignore{\wxheading{Members}}} \membersection{wxProcess::wxProcess}\label{wxprocessconstr} @@ -48,6 +62,15 @@ macro in the event table of the parent to handle it) with the given {\it id}. Destroys the wxProcess object. +\membersection{wxProcess::CloseOutput}\label{wxprocesscloseoutput} + +\func{void}{CloseOutput}{\void} + +Closes the output stream (the one connected to the stdin of the child +process). This function can be used to indicate to the child process that +there is no more data to be read - usually, a filter program will only +terminate when the input stream is closed. + \membersection{wxProcess::Detach}\label{wxprocessdetach} \func{void}{Detach}{\void} @@ -62,28 +85,97 @@ from its parent, no notification events will be sent to the parent and the object will delete itself upon reception of the process termination notification. +\membersection{wxProcess::GetErrorStream}\label{wxprocessgeterrorstream} + +\constfunc{wxInputStream* }{GetErrorStream}{\void} + +Returns an input stream which corresponds to the standard error output (stderr) +of the child process. + \membersection{wxProcess::GetInputStream}\label{wxprocessgetinputstream} \constfunc{wxInputStream* }{GetInputStream}{\void} -It returns a input stream correspoding to the output stream of the subprocess. -If it is NULL, you have not turned on the redirection. +It returns an input stream corresponding to the standard output stream of the +subprocess. If it is NULL, you have not turned on the redirection. See \helpref{wxProcess::Redirect}{wxprocessredirect}. -\membersection{wxProcess::GetInputStream}\label{wxprocessgetinputstream} +\membersection{wxProcess::GetOutputStream}\label{wxprocessgetoutputstream} -\constfunc{wxInputStream* }{GetInputStream}{\void} +\constfunc{wxOutputStream* }{GetOutputStream}{\void} -It returns a output stream corresponding to the input stream of the subprocess. +It returns an output stream correspoding to the input stream of the subprocess. If it is NULL, you have not turned on the redirection. See \helpref{wxProcess::Redirect}{wxprocessredirect}. +\membersection{wxProcess::Kill}\label{wxprocesskill} + +\func{static wxKillError}{Kill}{\param{int}{ pid}, \param{wxSignal}{ signal = wxSIGNONE}} + +Send the specified signal to the given process. Possible signal values are: + +\begin{verbatim} +enum wxSignal +{ + wxSIGNONE = 0, // verify if the process exists under Unix + wxSIGHUP, + wxSIGINT, + wxSIGQUIT, + wxSIGILL, + wxSIGTRAP, + wxSIGABRT, + wxSIGEMT, + wxSIGFPE, + wxSIGKILL, // forcefully kill, dangerous! + wxSIGBUS, + wxSIGSEGV, + wxSIGSYS, + wxSIGPIPE, + wxSIGALRM, + wxSIGTERM // terminate the process gently +}; +\end{verbatim} + +{\tt wxSIGNONE}, {\tt wxSIGKILL} and {\tt wxSIGTERM} have the same meaning +under both Unix and Windows but all the other signals are equivalent to +{\tt wxSIGTERM} under Windows. + +Returns the element of {\tt wxKillError} enum: + +\begin{verbatim} +enum wxKillError +{ + wxKILL_OK, // no error + wxKILL_BAD_SIGNAL, // no such signal + wxKILL_ACCESS_DENIED, // permission denied + wxKILL_NO_PROCESS, // no such process + wxKILL_ERROR // another, unspecified error +}; +\end{verbatim} + +\wxheading{See also} + +\helpref{wxProcess::Exists}{wxprocessexists},\rtfsp +\helpref{wxKill}{wxkill},\rtfsp +\helpref{Exec sample}{sampleexec} + +\membersection{wxProcess::Kill}\label{wxprocessexists} + +\func{static bool}{Exists}{\param{int}{ pid}} + +Returns {\tt TRUE} if the given process exists in the system. + +\wxheading{See also} + +\helpref{wxProcess::Kill}{wxprocesskill},\rtfsp +\helpref{Exec sample}{sampleexec} + \membersection{wxProcess::OnTerminate}\label{wxprocessonterminate} \constfunc{void}{OnTerminate}{\param{int}{ pid}, \param{int}{ status}} It is called when the process with the pid {\it pid} finishes. -It raises a wxWindows event when it isn't overriden. +It raises a wxWindows event when it isn't overridden. \docparam{pid}{The pid of the process which has just terminated.} @@ -93,7 +185,8 @@ It raises a wxWindows event when it isn't overriden. \func{void}{Redirect}{\void} -It turns on the redirection, wxExecute will try to open a couple of pipes +Turns on redirection. wxExecute will try to open a couple of pipes to catch the subprocess stdio. The caught input stream is returned by GetOutputStream() as a non-seekable stream. The caught output stream is returned by GetInputStream() as a non-seekable stream. +