docs/latex/wx/process.tex

   1 \section{\class{wxProcess}}\label{wxprocess}
   2
   3 The objects of this class are used in conjunction with the
   4 \helpref{wxExecute}{wxexecute} function. When a wxProcess object is passed to
   5 wxExecute(), its \helpref{OnTerminate()}{wxprocessonterminate} virtual method
   6 is called when the process terminates. This allows the program to be
   7 (asynchronously) notified about the process termination and also retrieve its
   8 exit status which is unavailable from wxExecute() in the case of
   9 asynchronous execution.
  10
  11 Please note that if the process termination notification is processed by the
  12 parent, it is responsible for deleting the wxProcess object which sent it.
  13 However, if it is not processed, the object will delete itself and so the
  14 library users should only delete those objects whose notifications have been
  15 processed (and call \helpref{Detach()}{wxprocessdetach} for others).
  16
  17 wxProcess also supports IO redirection of the child process. For this, you have
  18 to call its \helpref{Redirect}{wxprocessredirect} method before passing it to
  19 \helpref{wxExecute}{wxexecute}. If the child process was launched successfully,
  20 \helpref{GetInputStream}{wxprocessgetinputstream},
  21 \helpref{GetOutputStream}{wxprocessgetoutputstream} and
  22 \helpref{GetErrorStream}{wxprocessgeterrorstream} can then be used to retrieve
  23 the streams corresponding to the child process standard output, input and
  24 error output respectively.
  25
  26 \perlnote{In wxPerl this class has an additional {\tt Destroy} method,
  27 for explicit destruction.}
  28
  29 \wxheading{Derived from}
  30
  31 \helpref{wxEvtHandler}{wxevthandler}\\
  32 \helpref{wxObject}{wxobject}
  33
  34 \wxheading{Include files}
  35
  36 <wx/process.h>
  37
  38 \wxheading{Library}
  39
  40 \helpref{wxBase}{librarieslist}
  41
  42 \wxheading{See also}
  43
  44 \helpref{wxExecute}{wxexecute}\\
  45 \helpref{exec sample}{sampleexec}
  46
  47 \latexignore{\rtfignore{\wxheading{Members}}}
  48
  49 \membersection{wxProcess::wxProcess}\label{wxprocessctor}
  50
  51 \func{}{wxProcess}{\param{wxEvtHandler *}{ parent = NULL}, \param{int}{ id = -1}}
  52
  53 \func{}{wxProcess}{\param{int }{flags}}
  54
  55 Constructs a process object. {\it id} is only used in the case you want to
  56 use wxWidgets events. It identifies this object, or another window that will
  57 receive the event.
  58
  59 If the {\it parent} parameter is different from NULL, it will receive
  60 a wxEVT\_END\_PROCESS notification event (you should insert EVT\_END\_PROCESS
  61 macro in the event table of the parent to handle it) with the given {\it id}.
  62
  63 The second constructor creates an object without any associated parent (and
  64 hence no id neither) but allows to specify the {\it flags} which can have the
  65 value of {\tt wxPROCESS\_DEFAULT} or {\tt wxPROCESS\_REDIRECT}. Specifying the
  66 former value has no particular effect while using the latter one is equivalent
  67 to calling \helpref{Redirect}{wxprocessredirect}.
  68
  69 \wxheading{Parameters}
  70
  71 \docparam{parent}{The event handler parent.}
  72
  73 \docparam{id}{id of an event.}
  74
  75 \docparam{flags}{either {\tt wxPROCESS\_DEFAULT} or {\tt wxPROCESS\_REDIRECT}}
  76
  77 \membersection{wxProcess::\destruct{wxProcess}}\label{wxprocessdtor}
  78
  79 \func{}{\destruct{wxProcess}}{\void}
  80
  81 Destroys the wxProcess object.
  82
  83 \membersection{wxProcess::CloseOutput}\label{wxprocesscloseoutput}
  84
  85 \func{void}{CloseOutput}{\void}
  86
  87 Closes the output stream (the one connected to the stdin of the child
  88 process). This function can be used to indicate to the child process that
  89 there is no more data to be read - usually, a filter program will only
  90 terminate when the input stream is closed.
  91
  92 \membersection{wxProcess::Detach}\label{wxprocessdetach}
  93
  94 \func{void}{Detach}{\void}
  95
  96 Normally, a wxProcess object is deleted by its parent when it receives the
  97 notification about the process termination. However, it might happen that the
  98 parent object is destroyed before the external process is terminated (e.g. a
  99 window from which this external process was launched is closed by the user)
 100 and in this case it {\bf should not delete} the wxProcess object, but
 101 {\bf should call Detach()} instead. After the wxProcess object is detached
 102 from its parent, no notification events will be sent to the parent and the
 103 object will delete itself upon reception of the process termination
 104 notification.
 105
 106 \membersection{wxProcess::GetErrorStream}\label{wxprocessgeterrorstream}
 107
 108 \constfunc{wxInputStream* }{GetErrorStream}{\void}
 109
 110 Returns an input stream which corresponds to the standard error output (stderr)
 111 of the child process.
 112
 113 \membersection{wxProcess::GetInputStream}\label{wxprocessgetinputstream}
 114
 115 \constfunc{wxInputStream* }{GetInputStream}{\void}
 116
 117 It returns an input stream corresponding to the standard output stream of the
 118 subprocess. If it is NULL, you have not turned on the redirection.
 119 See \helpref{wxProcess::Redirect}{wxprocessredirect}.
 120
 121 \membersection{wxProcess::GetOutputStream}\label{wxprocessgetoutputstream}
 122
 123 \constfunc{wxOutputStream* }{GetOutputStream}{\void}
 124
 125 It returns an output stream correspoding to the input stream of the subprocess.
 126 If it is NULL, you have not turned on the redirection.
 127 See \helpref{wxProcess::Redirect}{wxprocessredirect}.
 128
 129 \membersection{wxProcess::IsErrorAvailable}\label{wxprocessiserroravailable}
 130
 131 \constfunc{bool}{IsErrorAvailable}{\void}
 132
 133 Returns {\tt true} if there is data to be read on the child process standard
 134 error stream.
 135
 136 \wxheading{See also}
 137
 138 \helpref{IsInputAvailable}{wxprocessisinputavailable}
 139
 140 \membersection{wxProcess::IsInputAvailable}\label{wxprocessisinputavailable}
 141
 142 \constfunc{bool}{IsInputAvailable}{\void}
 143
 144 Returns {\tt true} if there is data to be read on the child process standard
 145 output stream. This allows to write simple (and extremely inefficient)
 146 polling-based code waiting for a better mechanism in future wxWidgets versions.
 147
 148 See the \helpref{exec sample}{sampleexec} for an example of using this
 149 function.
 150
 151 \wxheading{See also}
 152
 153 \helpref{IsInputOpened}{wxprocessisinputopened}
 154
 155 \membersection{wxProcess::IsInputOpened}\label{wxprocessisinputopened}
 156
 157 \constfunc{bool}{IsInputOpened}{\void}
 158
 159 Returns {\tt true} if the child process standard output stream is opened.
 160
 161 \membersection{wxProcess::Kill}\label{wxprocesskill}
 162
 163 \func{static wxKillError}{Kill}{\param{int}{ pid}, \param{wxSignal}{ signal = wxSIGNONE}, \param{int }{flags = wxKILL\_NOCHILDREN}}
 164
 165 Send the specified signal to the given process. Possible signal values are:
 166
 167 \begin{verbatim}
 168 enum wxSignal
 169 {
 170     wxSIGNONE = 0,  // verify if the process exists under Unix
 171     wxSIGHUP,
 172     wxSIGINT,
 173     wxSIGQUIT,
 174     wxSIGILL,
 175     wxSIGTRAP,
 176     wxSIGABRT,
 177     wxSIGEMT,
 178     wxSIGFPE,
 179     wxSIGKILL,      // forcefully kill, dangerous!
 180     wxSIGBUS,
 181     wxSIGSEGV,
 182     wxSIGSYS,
 183     wxSIGPIPE,
 184     wxSIGALRM,
 185     wxSIGTERM       // terminate the process gently
 186 };
 187 \end{verbatim}
 188
 189 {\tt wxSIGNONE}, {\tt wxSIGKILL} and {\tt wxSIGTERM} have the same meaning
 190 under both Unix and Windows but all the other signals are equivalent to
 191 {\tt wxSIGTERM} under Windows.
 192
 193 The {\it flags} parameter can be wxKILL\_NOCHILDREN (the default),
 194 or wxKILL\_CHILDREN, in which case the child processes of this
 195 process will be killed too. Note that under Unix, for wxKILL\_CHILDREN
 196 to work you should have created the process passing wxEXEC\_MAKE\_GROUP\_LEADER.
 197
 198 Returns the element of {\tt wxKillError} enum:
 199
 200 \begin{verbatim}
 201 enum wxKillError
 202 {
 203     wxKILL_OK,              // no error
 204     wxKILL_BAD_SIGNAL,      // no such signal
 205     wxKILL_ACCESS_DENIED,   // permission denied
 206     wxKILL_NO_PROCESS,      // no such process
 207     wxKILL_ERROR            // another, unspecified error
 208 };
 209 \end{verbatim}
 210
 211 \wxheading{See also}
 212
 213 \helpref{wxProcess::Exists}{wxprocessexists},\rtfsp
 214 \helpref{wxKill}{wxkill},\rtfsp
 215 \helpref{Exec sample}{sampleexec}
 216
 217 \membersection{wxProcess::Exists}\label{wxprocessexists}
 218
 219 \func{static bool}{Exists}{\param{int}{ pid}}
 220
 221 Returns {\tt true} if the given process exists in the system.
 222
 223 \wxheading{See also}
 224
 225 \helpref{wxProcess::Kill}{wxprocesskill},\rtfsp
 226 \helpref{Exec sample}{sampleexec}
 227
 228 \membersection{wxProcess::OnTerminate}\label{wxprocessonterminate}
 229
 230 \func{void}{OnTerminate}{\param{int}{ pid}, \param{int}{ status}}
 231
 232 It is called when the process with the pid {\it pid} finishes.
 233 It raises a wxWidgets event when it isn't overridden.
 234
 235 \docparam{pid}{The pid of the process which has just terminated.}
 236
 237 \docparam{status}{The exit code of the process.}
 238
 239 \membersection{wxProcess::Open}\label{wxprocessopen}
 240
 241 \func{static wxProcess *}{Open}{\param{const wxString\& }{cmd}, \param{int }{flags = wxEXEC\_ASYNC}}
 242
 243 This static method replaces the standard {\tt popen()} function: it launches
 244 the process specified by the {\it cmd} parameter and returns the wxProcess
 245 object which can be used to retrieve the streams connected to the standard
 246 input, output and error output of the child process.
 247
 248 If the process couldn't be launched, {\tt NULL} is returned. Note that in any
 249 case the returned pointer should {\bf not} be deleted, rather the process
 250 object will be destroyed automatically when the child process terminates. This
 251 does mean that the child process should be told to quit before the main program
 252 exits to avoid memory leaks.
 253
 254 \wxheading{Parameters}
 255
 256 \docparam{cmd}{The command to execute, including optional arguments.}
 257 \docparam{flags}{The flags to pass to \helpref{wxExecute}{wxexecute}.
 258   NOTE: wxEXEC\_SYNC should not be used.}
 259
 260 \wxheading{Return value}
 261
 262 A pointer to new wxProcess object or {\tt NULL} on error.
 263
 264 \wxheading{See also}
 265
 266 \helpref{wxExecute}{wxexecute}
 267
 268 \membersection{wxProcess::GetPid}\label{wxprocessgetpid}
 269
 270 \constfunc{long}{GetPid}{\void}
 271
 272 Returns the process ID of the process launched by \helpref{Open}{wxprocessopen}.
 273
 274 \membersection{wxProcess::Redirect}\label{wxprocessredirect}
 275
 276 \func{void}{Redirect}{\void}
 277
 278 Turns on redirection. wxExecute will try to open a couple of pipes
 279 to catch the subprocess stdio. The caught input stream is returned by
 280 GetOutputStream() as a non-seekable stream. The caught output stream is returned
 281 by GetInputStream() as a non-seekable stream.
 282