<?xml version="1.0" encoding="iso-8859-1"?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "DTD/xhtml1-strict.dtd">
<html><head><title>QProcess Class Reference</title><style>h3.fn,span.fn { margin-left: 1cm; text-indent: -1cm }
a:link { color: #004faf; text-decoration: none }
a:visited { color: #672967; text-decoration: none }
td.postheader { font-family: sans-serif }
tr.address { font-family: sans-serif }
body { background: #ffffff; color: black; }
</style></head><body><table border="0" cellpadding="0" cellspacing="0" width="100%"><tr /><td align="left" valign="top" width="32"><img align="left" border="0" height="32" src="images/rb-logo.png" width="32" /></td><td width="1">  </td><td class="postheader" valign="center"><a href="index.html"><font color="#004faf">Home</font></a> · <a href="classes.html"><font color="#004faf">All Classes</font></a> · <a href="modules.html"><font color="#004faf">Modules</font></a></td></table><h1 align="center">QProcess Class Reference<br /><sup><sup>[<a href="qtcore.html">QtCore</a> module]</sup></sup></h1><p>The QProcess class is used to start external programs and to
communicate with them. <a href="#details">More...</a></p>
<p>Inherits <a href="qiodevice.html">QIODevice</a>.</p><h3>Types</h3><ul><li><div class="fn" />enum <b><a href="qprocess.html#ExitStatus-enum">ExitStatus</a></b> { NormalExit, CrashExit }</li><li><div class="fn" />enum <b><a href="qprocess.html#ProcessChannel-enum">ProcessChannel</a></b> { StandardOutput, StandardError }</li><li><div class="fn" />enum <b><a href="qprocess.html#ProcessChannelMode-enum">ProcessChannelMode</a></b> { SeparateChannels, MergedChannels, ForwardedChannels }</li><li><div class="fn" />enum <b><a href="qprocess.html#ProcessError-enum">ProcessError</a></b> { FailedToStart, Crashed, Timedout, ReadError, WriteError, UnknownError }</li><li><div class="fn" />enum <b><a href="qprocess.html#ProcessState-enum">ProcessState</a></b> { NotRunning, Starting, Running }</li></ul><h3>Methods</h3><ul><li><div class="fn" /><b><a href="qprocess.html#QProcess">__init__</a></b> (<i>self</i>, QObject <i>parent</i> = None)</li><li><div class="fn" />bool <b><a href="qprocess.html#atEnd">atEnd</a></b> (<i>self</i>)</li><li><div class="fn" />int <b><a href="qprocess.html#bytesAvailable">bytesAvailable</a></b> (<i>self</i>)</li><li><div class="fn" />int <b><a href="qprocess.html#bytesToWrite">bytesToWrite</a></b> (<i>self</i>)</li><li><div class="fn" />bool <b><a href="qprocess.html#canReadLine">canReadLine</a></b> (<i>self</i>)</li><li><div class="fn" /><b><a href="qprocess.html#close">close</a></b> (<i>self</i>)</li><li><div class="fn" /><b><a href="qprocess.html#closeReadChannel">closeReadChannel</a></b> (<i>self</i>, ProcessChannel <i>channel</i>)</li><li><div class="fn" /><b><a href="qprocess.html#closeWriteChannel">closeWriteChannel</a></b> (<i>self</i>)</li><li><div class="fn" />QStringList <b><a href="qprocess.html#environment">environment</a></b> (<i>self</i>)</li><li><div class="fn" />ProcessError <b><a href="qprocess.html#error">error</a></b> (<i>self</i>)</li><li><div class="fn" />int <b><a href="qprocess.html#exitCode">exitCode</a></b> (<i>self</i>)</li><li><div class="fn" />ExitStatus <b><a href="qprocess.html#exitStatus">exitStatus</a></b> (<i>self</i>)</li><li><div class="fn" />bool <b><a href="qprocess.html#isSequential">isSequential</a></b> (<i>self</i>)</li><li><div class="fn" /><b><a href="qprocess.html#kill">kill</a></b> (<i>self</i>)</li><li><div class="fn" />int <b><a href="qprocess.html#pid">pid</a></b> (<i>self</i>)</li><li><div class="fn" />ProcessChannelMode <b><a href="qprocess.html#processChannelMode">processChannelMode</a></b> (<i>self</i>)</li><li><div class="fn" />QProcessEnvironment <b><a href="qprocess.html#processEnvironment">processEnvironment</a></b> (<i>self</i>)</li><li><div class="fn" />QByteArray <b><a href="qprocess.html#readAllStandardError">readAllStandardError</a></b> (<i>self</i>)</li><li><div class="fn" />QByteArray <b><a href="qprocess.html#readAllStandardOutput">readAllStandardOutput</a></b> (<i>self</i>)</li><li><div class="fn" />ProcessChannel <b><a href="qprocess.html#readChannel">readChannel</a></b> (<i>self</i>)</li><li><div class="fn" />ProcessChannelMode <b><a href="qprocess.html#readChannelMode">readChannelMode</a></b> (<i>self</i>)</li><li><div class="fn" />str <b><a href="qprocess.html#readData">readData</a></b> (<i>self</i>, int <i>maxlen</i>)</li><li><div class="fn" /><b><a href="qprocess.html#setEnvironment">setEnvironment</a></b> (<i>self</i>, QStringList <i>environment</i>)</li><li><div class="fn" /><b><a href="qprocess.html#setProcessChannelMode">setProcessChannelMode</a></b> (<i>self</i>, ProcessChannelMode <i>mode</i>)</li><li><div class="fn" /><b><a href="qprocess.html#setProcessEnvironment">setProcessEnvironment</a></b> (<i>self</i>, QProcessEnvironment <i>environment</i>)</li><li><div class="fn" /><b><a href="qprocess.html#setProcessState">setProcessState</a></b> (<i>self</i>, ProcessState <i>state</i>)</li><li><div class="fn" /><b><a href="qprocess.html#setReadChannel">setReadChannel</a></b> (<i>self</i>, ProcessChannel <i>channel</i>)</li><li><div class="fn" /><b><a href="qprocess.html#setReadChannelMode">setReadChannelMode</a></b> (<i>self</i>, ProcessChannelMode <i>mode</i>)</li><li><div class="fn" /><b><a href="qprocess.html#setStandardErrorFile">setStandardErrorFile</a></b> (<i>self</i>, QString <i>fileName</i>, QIODevice.OpenMode <i>mode</i> = QIODevice.Truncate)</li><li><div class="fn" /><b><a href="qprocess.html#setStandardInputFile">setStandardInputFile</a></b> (<i>self</i>, QString <i>fileName</i>)</li><li><div class="fn" /><b><a href="qprocess.html#setStandardOutputFile">setStandardOutputFile</a></b> (<i>self</i>, QString <i>fileName</i>, QIODevice.OpenMode <i>mode</i> = QIODevice.Truncate)</li><li><div class="fn" /><b><a href="qprocess.html#setStandardOutputProcess">setStandardOutputProcess</a></b> (<i>self</i>, QProcess <i>destination</i>)</li><li><div class="fn" /><b><a href="qprocess.html#setupChildProcess">setupChildProcess</a></b> (<i>self</i>)</li><li><div class="fn" /><b><a href="qprocess.html#setWorkingDirectory">setWorkingDirectory</a></b> (<i>self</i>, QString <i>dir</i>)</li><li><div class="fn" /><b><a href="qprocess.html#start">start</a></b> (<i>self</i>, QString <i>program</i>, QStringList <i>arguments</i>, QIODevice.OpenMode <i>mode</i> = QIODevice.ReadWrite)</li><li><div class="fn" /><b><a href="qprocess.html#start-2">start</a></b> (<i>self</i>, QString <i>program</i>, QIODevice.OpenMode <i>mode</i> = QIODevice.ReadWrite)</li><li><div class="fn" />ProcessState <b><a href="qprocess.html#state">state</a></b> (<i>self</i>)</li><li><div class="fn" /><b><a href="qprocess.html#terminate">terminate</a></b> (<i>self</i>)</li><li><div class="fn" />bool <b><a href="qprocess.html#waitForBytesWritten">waitForBytesWritten</a></b> (<i>self</i>, int <i>msecs</i> = 30000)</li><li><div class="fn" />bool <b><a href="qprocess.html#waitForFinished">waitForFinished</a></b> (<i>self</i>, int <i>msecs</i> = 30000)</li><li><div class="fn" />bool <b><a href="qprocess.html#waitForReadyRead">waitForReadyRead</a></b> (<i>self</i>, int <i>msecs</i> = 30000)</li><li><div class="fn" />bool <b><a href="qprocess.html#waitForStarted">waitForStarted</a></b> (<i>self</i>, int <i>msecs</i> = 30000)</li><li><div class="fn" />QString <b><a href="qprocess.html#workingDirectory">workingDirectory</a></b> (<i>self</i>)</li><li><div class="fn" />int <b><a href="qprocess.html#writeData">writeData</a></b> (<i>self</i>, str <i>data</i>)</li></ul><h3>Static Methods</h3><ul><li><div class="fn" />int <b><a href="qprocess.html#execute">execute</a></b> (QString <i>program</i>, QStringList <i>arguments</i>)</li><li><div class="fn" />int <b><a href="qprocess.html#execute-2">execute</a></b> (QString <i>program</i>)</li><li><div class="fn" />(bool, int <i>pid</i>) <b><a href="qprocess.html#startDetached">startDetached</a></b> (QString <i>program</i>, QStringList <i>arguments</i>, QString <i>workingDirectory</i>)</li><li><div class="fn" />bool <b><a href="qprocess.html#startDetached-2">startDetached</a></b> (QString <i>program</i>, QStringList <i>arguments</i>)</li><li><div class="fn" />bool <b><a href="qprocess.html#startDetached-3">startDetached</a></b> (QString <i>program</i>)</li><li><div class="fn" />QStringList <b><a href="qprocess.html#systemEnvironment">systemEnvironment</a></b> ()</li></ul><h3>Qt Signals</h3><ul><li><div class="fn" />void <b><a href="qprocess.html#error-2">error</a></b> (QProcess::ProcessError)</li><li><div class="fn" />void <b><a href="qprocess.html#finished">finished</a></b> (int,QProcess::ExitStatus)</li><li><div class="fn" />void <b><a href="qprocess.html#finished-2">finished</a></b> (int)</li><li><div class="fn" />void <b><a href="qprocess.html#readyReadStandardError">readyReadStandardError</a></b> ()</li><li><div class="fn" />void <b><a href="qprocess.html#readyReadStandardOutput">readyReadStandardOutput</a></b> ()</li><li><div class="fn" />void <b><a href="qprocess.html#started">started</a></b> ()</li><li><div class="fn" />void <b><a href="qprocess.html#stateChanged">stateChanged</a></b> (QProcess::ProcessState)</li></ul><a name="details" /><hr /><h2>Detailed Description</h2><p>The QProcess class is used to start external programs and to
communicate with them.</p>
<a id="running-a-process" name="running-a-process" />
<h3>Running a Process</h3>
<p>To start a process, pass the name and command line arguments of
the program you want to run as arguments to <a href="qprocess.html#start">start</a>(). Arguments are supplied as
individual strings in a <a href="qstringlist.html">QStringList</a>.</p>
<p>For example, the following code snippet runs the analog clock
example in the Motif style on X11 platforms by passing strings
containing "-style" and "motif" as two items in the list of
arguments:</p>
<pre class="cpp">
<span class="type"><a href="qobject.html">QObject</a></span> <span class="operator">*</span>parent;
...
<span class="type"><a href="qstring.html">QString</a></span> program <span class="operator">=</span> <span class="string">"./path/to/Qt/examples/widgets/analogclock"</span>;
<span class="type"><a href="qstringlist.html">QStringList</a></span> arguments;
arguments <span class="operator"><</span><span class="operator"><</span> <span class="string">"-style"</span> <span class="operator"><</span><span class="operator"><</span> <span class="string">"motif"</span>;
<span class="type">QProcess</span> <span class="operator">*</span>myProcess <span class="operator">=</span> <span class="keyword">new</span> <span class="type">QProcess</span>(parent);
myProcess<span class="operator">-</span><span class="operator">></span>start(program<span class="operator">,</span> arguments);
</pre>
<p>QProcess then enters the <a href="qprocess.html#ProcessState-enum">Starting</a> state, and when the
program has started, QProcess enters the <a href="qprocess.html#ProcessState-enum">Running</a> state and emits
<a href="qprocess.html#started">started</a>().</p>
<p>QProcess allows you to treat a process as a sequential I/O
device. You can write to and read from the process just as you
would access a network connection using <a href="qtcpsocket.html">QTcpSocket</a>. You can then write to the
process's standard input by calling <a href="qiodevice.html#write">write</a>(), and read the standard output by
calling <a href="qiodevice.html#read">read</a>(), <a href="qiodevice.html#readLine">readLine</a>(), and <a href="qiodevice.html#getChar">getChar</a>(). Because it inherits
<a href="qiodevice.html">QIODevice</a>, QProcess can also be used
as an input source for <a href="qxmlreader.html">QXmlReader</a>, or
for generating data to be uploaded using <a href="qftp.html">QFtp</a>.</p>
<p><b>Note:</b> On VxWorks, Windows CE and Symbian, reading and
writing to a process is not supported.</p>
<p>When the process exits, QProcess reenters the <a href="qprocess.html#ProcessState-enum">NotRunning</a> state (the initial
state), and emits <a href="qprocess.html#finished">finished</a>().</p>
<p>The <a href="qprocess.html#finished">finished</a>() signal
provides the exit code and exit status of the process as arguments,
and you can also call <a href="qprocess.html#exitCode">exitCode</a>() to obtain the exit code of
the last process that finished, and <a href="qprocess.html#exitStatus">exitStatus</a>() to obtain its exit
status. If an error occurs at any point in time, QProcess will emit
the <a href="qprocess.html#error">error</a>() signal. You can also
call <a href="qprocess.html#error">error</a>() to find the type of
error that occurred last, and <a href="qprocess.html#state">state</a>() to find the current process
state.</p>
<a id="communicating-via-channels" name="communicating-via-channels" />
<h3>Communicating via Channels</h3>
<p>Processes have two predefined output channels: The standard
output channel (<tt>stdout</tt>) supplies regular console output,
and the standard error channel (<tt>stderr</tt>) usually supplies
the errors that are printed by the process. These channels
represent two separate streams of data. You can toggle between them
by calling <a href="qprocess.html#setReadChannel">setReadChannel</a>(). QProcess emits
<a href="qiodevice.html#readyRead">readyRead</a>() when data is
available on the current read channel. It also emits <a href="qprocess.html#readyReadStandardOutput">readyReadStandardOutput</a>()
when new standard output data is available, and when new standard
error data is available, <a href="qprocess.html#readyReadStandardError">readyReadStandardError</a>()
is emitted. Instead of calling <a href="qiodevice.html#read">read</a>(), <a href="qiodevice.html#readLine">readLine</a>(), or <a href="qiodevice.html#getChar">getChar</a>(), you can explicitly read all
data from either of the two channels by calling <a href="qprocess.html#readAllStandardOutput">readAllStandardOutput</a>()
or <a href="qprocess.html#readAllStandardError">readAllStandardError</a>().</p>
<p>The terminology for the channels can be misleading. Be aware
that the process's output channels correspond to QProcess's
<i>read</i> channels, whereas the process's input channels
correspond to QProcess's <i>write</i> channels. This is because
what we read using QProcess is the process's output, and what we
write becomes the process's input.</p>
<p>QProcess can merge the two output channels, so that standard
output and standard error data from the running process both use
the standard output channel. Call <a href="qprocess.html#setProcessChannelMode">setProcessChannelMode</a>()
with <a href="qprocess.html#ProcessChannelMode-enum">MergedChannels</a> before
starting the process to activative this feature. You also have the
option of forwarding the output of the running process to the
calling, main process, by passing <a href="qprocess.html#ProcessChannelMode-enum">ForwardedChannels</a> as
the argument.</p>
<p>Certain processes need special environment settings in order to
operate. You can set environment variables for your process by
calling <a href="qprocess.html#setEnvironment">setEnvironment</a>(). To set a
working directory, call <a href="qprocess.html#setWorkingDirectory">setWorkingDirectory</a>(). By
default, processes are run in the current working directory of the
calling process.</p>
<p><b>Note:</b> On VxWorks, communicating via channels with a
process is not supported.</p>
<p><b>Note:</b> On Symbian, setting environment or working
directory is not supported. The working directory will always be
the private directory of the running process.</p>
<p><b>Note:</b> On QNX, setting the working directory may cause all
application threads, with the exception of the QProcess caller
thread, to temporarily freeze, owing to a limitation in the
operating system.</p>
<a id="synchronous-process-api" name="synchronous-process-api" />
<h3>Synchronous Process API</h3>
<p>QProcess provides a set of functions which allow it to be used
without an event loop, by suspending the calling thread until
certain signals are emitted:</p>
<ul>
<li><a href="qprocess.html#waitForStarted">waitForStarted</a>()
blocks until the process has started.</li>
<li><a href="qprocess.html#waitForReadyRead">waitForReadyRead</a>()
blocks until new data is available for reading on the current read
channel.</li>
<li><a href="qprocess.html#waitForBytesWritten">waitForBytesWritten</a>()
blocks until one payload of data has been written to the
process.</li>
<li><a href="qprocess.html#waitForFinished">waitForFinished</a>()
blocks until the process has finished.</li>
</ul>
<p>Calling these functions from the main thread (the thread that
calls <a href="qapplication.html#exec">QApplication.exec</a>())
may cause your user interface to freeze.</p>
<p>The following example runs <tt>gzip</tt> to compress the string
"Qt rocks!", without an event loop:</p>
<pre class="cpp">
<span class="type">QProcess</span> gzip;
gzip<span class="operator">.</span>start(<span class="string">"gzip"</span><span class="operator">,</span> <span class="type"><a href="qstringlist.html">QStringList</a></span>() <span class="operator"><</span><span class="operator"><</span> <span class="string">"-c"</span>);
<span class="keyword">if</span> (<span class="operator">!</span>gzip<span class="operator">.</span>waitForStarted())
<span class="keyword">return</span> <span class="keyword">false</span>;
gzip<span class="operator">.</span>write(<span class="string">"Qt rocks!"</span>);
gzip<span class="operator">.</span>closeWriteChannel();
<span class="keyword">if</span> (<span class="operator">!</span>gzip<span class="operator">.</span>waitForFinished())
<span class="keyword">return</span> <span class="keyword">false</span>;
<span class="type"><a href="qbytearray.html">QByteArray</a></span> result <span class="operator">=</span> gzip<span class="operator">.</span>readAll();
</pre>
<a id="notes-for-windows-users" name="notes-for-windows-users" />
<h3>Notes for Windows Users</h3>
<p>Some Windows commands (for example, <tt>dir</tt>) are not
provided by separate applications, but by the command interpreter
itself. If you attempt to use QProcess to execute these commands
directly, it won't work. One possible solution is to execute the
command interpreter itself (<tt>cmd.exe</tt> on some Windows
systems), and ask the interpreter to execute the desired
command.</p>
<a id="notes-for-vxworks-users" name="notes-for-vxworks-users" />
<h3>Notes for VxWorks Users</h3>
<p>QProcess support is only available on RTP mode, and only a
limited functionality is provided. When using QProcess to launch Qt
applications, the launched application has to have the following
code:</p>
<pre class="cpp">
</pre><hr /><h2>Type Documentation</h2><h3 class="fn"><a name="ExitStatus-enum" />QProcess.ExitStatus</h3><p>This enum describes the different exit statuses of <a href="qprocess.html">QProcess</a>.</p>
<table class="valuelist">
<tr class="odd" valign="top">
<th class="tblConst">Constant</th>
<th class="tblval">Value</th>
<th class="tbldscr">Description</th>
</tr>
<tr>
<td class="topAlign"><tt>QProcess.NormalExit</tt></td>
<td class="topAlign"><tt>0</tt></td>
<td class="topAlign">The process exited normally.</td>
</tr>
<tr>
<td class="topAlign"><tt>QProcess.CrashExit</tt></td>
<td class="topAlign"><tt>1</tt></td>
<td class="topAlign">The process crashed.</td>
</tr>
</table>
<p><b>See also</b> <a href="qprocess.html#exitStatus">exitStatus</a>().</p>
<h3 class="fn"><a name="ProcessChannel-enum" />QProcess.ProcessChannel</h3><p>This enum describes the process channels used by the running
process. Pass one of these values to <a href="qprocess.html#setReadChannel">setReadChannel</a>() to set the
current read channel of <a href="qprocess.html">QProcess</a>.</p>
<table class="valuelist">
<tr class="odd" valign="top">
<th class="tblConst">Constant</th>
<th class="tblval">Value</th>
<th class="tbldscr">Description</th>
</tr>
<tr>
<td class="topAlign"><tt>QProcess.StandardOutput</tt></td>
<td class="topAlign"><tt>0</tt></td>
<td class="topAlign">The standard output (stdout) of the running
process.</td>
</tr>
<tr>
<td class="topAlign"><tt>QProcess.StandardError</tt></td>
<td class="topAlign"><tt>1</tt></td>
<td class="topAlign">The standard error (stderr) of the running
process.</td>
</tr>
</table>
<p><b>See also</b> <a href="qprocess.html#setReadChannel">setReadChannel</a>().</p>
<h3 class="fn"><a name="ProcessChannelMode-enum" />QProcess.ProcessChannelMode</h3><p>This enum describes the process channel modes of <a href="qprocess.html">QProcess</a>. Pass one of these values to <a href="qprocess.html#setProcessChannelMode">setProcessChannelMode</a>()
to set the current read channel mode.</p>
<table class="valuelist">
<tr class="odd" valign="top">
<th class="tblConst">Constant</th>
<th class="tblval">Value</th>
<th class="tbldscr">Description</th>
</tr>
<tr>
<td class="topAlign"><tt>QProcess.SeparateChannels</tt></td>
<td class="topAlign"><tt>0</tt></td>
<td class="topAlign"><a href="qprocess.html">QProcess</a> manages
the output of the running process, keeping standard output and
standard error data in separate internal buffers. You can select
the <a href="qprocess.html">QProcess</a>'s current read channel by
calling <a href="qprocess.html#setReadChannel">setReadChannel</a>(). This is the
default channel mode of <a href="qprocess.html">QProcess</a>.</td>
</tr>
<tr>
<td class="topAlign"><tt>QProcess.MergedChannels</tt></td>
<td class="topAlign"><tt>1</tt></td>
<td class="topAlign"><a href="qprocess.html">QProcess</a> merges
the output of the running process into the standard output channel
(<tt>stdout</tt>). The standard error channel (<tt>stderr</tt>)
will not receive any data. The standard output and standard error
data of the running process are interleaved.</td>
</tr>
<tr>
<td class="topAlign"><tt>QProcess.ForwardedChannels</tt></td>
<td class="topAlign"><tt>2</tt></td>
<td class="topAlign"><a href="qprocess.html">QProcess</a> forwards
the output of the running process onto the main process. Anything
the child process writes to its standard output and standard error
will be written to the standard output and standard error of the
main process.</td>
</tr>
</table>
<p><b>See also</b> <a href="qprocess.html#setProcessChannelMode">setProcessChannelMode</a>().</p>
<h3 class="fn"><a name="ProcessError-enum" />QProcess.ProcessError</h3><p>This enum describes the different types of errors that are
reported by <a href="qprocess.html">QProcess</a>.</p>
<table class="valuelist">
<tr class="odd" valign="top">
<th class="tblConst">Constant</th>
<th class="tblval">Value</th>
<th class="tbldscr">Description</th>
</tr>
<tr>
<td class="topAlign"><tt>QProcess.FailedToStart</tt></td>
<td class="topAlign"><tt>0</tt></td>
<td class="topAlign">The process failed to start. Either the
invoked program is missing, or you may have insufficient
permissions to invoke the program.</td>
</tr>
<tr>
<td class="topAlign"><tt>QProcess.Crashed</tt></td>
<td class="topAlign"><tt>1</tt></td>
<td class="topAlign">The process crashed some time after starting
successfully.</td>
</tr>
<tr>
<td class="topAlign"><tt>QProcess.Timedout</tt></td>
<td class="topAlign"><tt>2</tt></td>
<td class="topAlign">The last waitFor...() function timed out. The
state of <a href="qprocess.html">QProcess</a> is unchanged, and you
can try calling waitFor...() again.</td>
</tr>
<tr>
<td class="topAlign"><tt>QProcess.WriteError</tt></td>
<td class="topAlign"><tt>4</tt></td>
<td class="topAlign">An error occurred when attempting to write to
the process. For example, the process may not be running, or it may
have closed its input channel.</td>
</tr>
<tr>
<td class="topAlign"><tt>QProcess.ReadError</tt></td>
<td class="topAlign"><tt>3</tt></td>
<td class="topAlign">An error occurred when attempting to read from
the process. For example, the process may not be running.</td>
</tr>
<tr>
<td class="topAlign"><tt>QProcess.UnknownError</tt></td>
<td class="topAlign"><tt>5</tt></td>
<td class="topAlign">An unknown error occurred. This is the default
return value of <a href="qprocess.html#error">error</a>().</td>
</tr>
</table>
<p><b>See also</b> <a href="qprocess.html#error">error</a>().</p>
<h3 class="fn"><a name="ProcessState-enum" />QProcess.ProcessState</h3><p>This enum describes the different states of <a href="qprocess.html">QProcess</a>.</p>
<table class="valuelist">
<tr class="odd" valign="top">
<th class="tblConst">Constant</th>
<th class="tblval">Value</th>
<th class="tbldscr">Description</th>
</tr>
<tr>
<td class="topAlign"><tt>QProcess.NotRunning</tt></td>
<td class="topAlign"><tt>0</tt></td>
<td class="topAlign">The process is not running.</td>
</tr>
<tr>
<td class="topAlign"><tt>QProcess.Starting</tt></td>
<td class="topAlign"><tt>1</tt></td>
<td class="topAlign">The process is starting, but the program has
not yet been invoked.</td>
</tr>
<tr>
<td class="topAlign"><tt>QProcess.Running</tt></td>
<td class="topAlign"><tt>2</tt></td>
<td class="topAlign">The process is running and is ready for
reading and writing.</td>
</tr>
</table>
<p><b>See also</b> <a href="qprocess.html#state">state</a>().</p>
<hr /><h2>Method Documentation</h2><h3 class="fn"><a name="QProcess" />QProcess.__init__ (<i>self</i>, <a href="qobject.html">QObject</a> <i>parent</i> = None)</h3><p>The <i>parent</i> argument, if not None, causes <i>self</i> to be owned by Qt instead of PyQt.</p><p>Constructs a <a href="qprocess.html">QProcess</a> object with
the given <i>parent</i>.</p>
<h3 class="fn"><a name="atEnd" />bool QProcess.atEnd (<i>self</i>)</h3><p>Reimplemented from <a href="qiodevice.html#atEnd">QIODevice.atEnd</a>().</p>
<p>Returns true if the process is not running, and no more data is
available for reading; otherwise returns false.</p>
<h3 class="fn"><a name="bytesAvailable" />int QProcess.bytesAvailable (<i>self</i>)</h3><p>Reimplemented from <a href="qiodevice.html#bytesAvailable">QIODevice.bytesAvailable</a>().</p>
<h3 class="fn"><a name="bytesToWrite" />int QProcess.bytesToWrite (<i>self</i>)</h3><p>Reimplemented from <a href="qiodevice.html#bytesToWrite">QIODevice.bytesToWrite</a>().</p>
<h3 class="fn"><a name="canReadLine" />bool QProcess.canReadLine (<i>self</i>)</h3><p>Reimplemented from <a href="qiodevice.html#canReadLine">QIODevice.canReadLine</a>().</p>
<p>This function operates on the current read channel.</p>
<p><b>See also</b> <a href="qprocess.html#readChannel">readChannel</a>() and <a href="qprocess.html#setReadChannel">setReadChannel</a>().</p>
<h3 class="fn"><a name="close" />QProcess.close (<i>self</i>)</h3><p>Reimplemented from <a href="qiodevice.html#close">QIODevice.close</a>().</p>
<p>Closes all communication with the process and kills it. After
calling this function, <a href="qprocess.html">QProcess</a> will no
longer emit <a href="qiodevice.html#readyRead">readyRead</a>(), and
data can no longer be read or written.</p>
<h3 class="fn"><a name="closeReadChannel" />QProcess.closeReadChannel (<i>self</i>, <a href="qprocess.html#ProcessChannel-enum">ProcessChannel</a> <i>channel</i>)</h3><p>Closes the read channel <i>channel</i>. After calling this
function, <a href="qprocess.html">QProcess</a> will no longer
receive data on the channel. Any data that has already been
received is still available for reading.</p>
<p>Call this function to save memory, if you are not interested in
the output of the process.</p>
<p><b>See also</b> <a href="qprocess.html#closeWriteChannel">closeWriteChannel</a>() and
<a href="qprocess.html#setReadChannel">setReadChannel</a>().</p>
<h3 class="fn"><a name="closeWriteChannel" />QProcess.closeWriteChannel (<i>self</i>)</h3><p>Schedules the write channel of <a href="qprocess.html">QProcess</a> to be closed. The channel will close
once all data has been written to the process. After calling this
function, any attempts to write to the process will fail.</p>
<p>Closing the write channel is necessary for programs that read
input data until the channel has been closed. For example, the
program "more" is used to display text data in a console on both
Unix and Windows. But it will not display the text data until
<a href="qprocess.html">QProcess</a>'s write channel has been
closed. Example:</p>
<pre class="cpp">
<span class="type"><a href="qprocess.html">QProcess</a></span> more;
more<span class="operator">.</span>start(<span class="string">"more"</span>);
more<span class="operator">.</span>write(<span class="string">"Text to display"</span>);
more<span class="operator">.</span>closeWriteChannel();
<span class="comment">// QProcess will emit readyRead() once "more" starts printing</span>
</pre>
<p>The write channel is implicitly opened when <a href="qprocess.html#start">start</a>() is called.</p>
<p><b>See also</b> <a href="qprocess.html#closeReadChannel">closeReadChannel</a>().</p>
<h3 class="fn"><a name="environment" />QStringList QProcess.environment (<i>self</i>)</h3><p>This function is deprecated.</p>
<p>Returns the environment that <a href="qprocess.html">QProcess</a> will use when starting a process, or
an empty <a href="qstringlist.html">QStringList</a> if no
environment has been set using <a href="qprocess.html#setEnvironment">setEnvironment</a>() or
setEnvironmentHash(). If no environment has been set, the
environment of the calling process will be used.</p>
<p><b>Note:</b> The environment settings are ignored on Windows CE
and Symbian, as there is no concept of an environment.</p>
<p><b>See also</b> <a href="qprocess.html#processEnvironment">processEnvironment</a>(),
<a href="qprocess.html#setEnvironment">setEnvironment</a>(), and
<a href="qprocess.html#systemEnvironment">systemEnvironment</a>().</p>
<h3 class="fn"><a name="error" /><a href="qprocess.html#ProcessError-enum">ProcessError</a> QProcess.error (<i>self</i>)</h3><p>Returns the type of error that occurred last.</p>
<p><b>See also</b> <a href="qprocess.html#state">state</a>().</p>
<h3 class="fn"><a name="execute" />int QProcess.execute (QString <i>program</i>, QStringList <i>arguments</i>)</h3><p>Starts the program <i>program</i> with the arguments
<i>arguments</i> in a new process, waits for it to finish, and then
returns the exit code of the process. Any data the new process
writes to the console is forwarded to the calling process.</p>
<p>The environment and working directory are inherited from the
calling process.</p>
<p>On Windows, arguments that contain spaces are wrapped in
quotes.</p>
<p>If the process cannot be started, -2 is returned. If the process
crashes, -1 is returned. Otherwise, the process' exit code is
returned.</p>
<h3 class="fn"><a name="execute-2" />int QProcess.execute (QString <i>program</i>)</h3><p>This is an overloaded function.</p>
<p>Starts the program <i>program</i> in a new process.
<i>program</i> is a single string of text containing both the
program name and its arguments. The arguments are separated by one
or more spaces.</p>
<h3 class="fn"><a name="exitCode" />int QProcess.exitCode (<i>self</i>)</h3><p>Returns the exit code of the last process that finished.</p>
<h3 class="fn"><a name="exitStatus" /><a href="qprocess.html#ExitStatus-enum">ExitStatus</a> QProcess.exitStatus (<i>self</i>)</h3><p>Returns the exit status of the last process that finished.</p>
<p>On Windows, if the process was terminated with
TerminateProcess() from another application this function will
still return <a href="qprocess.html#ExitStatus-enum">NormalExit</a>
unless the exit code is less than 0.</p>
<p>This function was introduced in Qt 4.1.</p>
<h3 class="fn"><a name="isSequential" />bool QProcess.isSequential (<i>self</i>)</h3><p>Reimplemented from <a href="qiodevice.html#isSequential">QIODevice.isSequential</a>().</p>
<h3 class="fn"><a name="kill" />QProcess.kill (<i>self</i>)</h3><p>This method is also a Qt slot with the C++ signature <tt>void kill()</tt>.</p><p>Kills the current process, causing it to exit immediately.</p>
<p>On Windows, kill() uses TerminateProcess, and on Unix and Mac OS
X, the SIGKILL signal is sent to the process.</p>
<p>On Symbian, this function requires platform security capability
<tt>PowerMgmt</tt>. If absent, the process will panic with
KERN-EXEC 46.</p>
<p><b>Note:</b> Killing running processes from other processes will
typically cause a panic in Symbian due to platform security.</p>
<p><b>See also</b> <a href="symbian-platform-security-requirements.html">Symbian Platform
Security Requirements</a> and <a href="qprocess.html#terminate">terminate</a>().</p>
<h3 class="fn"><a name="pid" />int QProcess.pid (<i>self</i>)</h3><p>Returns the native process identifier for the running process,
if available. If no process is currently running, 0 is
returned.</p>
<h3 class="fn"><a name="processChannelMode" /><a href="qprocess.html#ProcessChannelMode-enum">ProcessChannelMode</a> QProcess.processChannelMode (<i>self</i>)</h3><p>Returns the channel mode of the <a href="qprocess.html">QProcess</a> standard output and standard error
channels.</p>
<p>This function was introduced in Qt 4.2.</p>
<p><b>See also</b> <a href="qprocess.html#setProcessChannelMode">setProcessChannelMode</a>(),
<a href="qprocess.html#ProcessChannelMode-enum">ProcessChannelMode</a>, and
<a href="qprocess.html#setReadChannel">setReadChannel</a>().</p>
<h3 class="fn"><a name="processEnvironment" /><a href="qprocessenvironment.html">QProcessEnvironment</a> QProcess.processEnvironment (<i>self</i>)</h3><p>Returns the environment that <a href="qprocess.html">QProcess</a> will use when starting a process, or
an empty object if no environment has been set using <a href="qprocess.html#setEnvironment">setEnvironment</a>() or <a href="qprocess.html#setProcessEnvironment">setProcessEnvironment</a>().
If no environment has been set, the environment of the calling
process will be used.</p>
<p><b>Note:</b> The environment settings are ignored on Windows CE,
as there is no concept of an environment.</p>
<p>This function was introduced in Qt 4.6.</p>
<p><b>See also</b> <a href="qprocess.html#setProcessEnvironment">setProcessEnvironment</a>(),
<a href="qprocess.html#setEnvironment">setEnvironment</a>(), and
<a href="qprocessenvironment.html#isEmpty">QProcessEnvironment.isEmpty</a>().</p>
<h3 class="fn"><a name="readAllStandardError" /><a href="qbytearray.html">QByteArray</a> QProcess.readAllStandardError (<i>self</i>)</h3><p>Regardless of the current read channel, this function returns
all data available from the standard error of the process as a
<a href="qbytearray.html">QByteArray</a>.</p>
<p><b>See also</b> <a href="qprocess.html#readyReadStandardError">readyReadStandardError</a>(),
<a href="qprocess.html#readAllStandardOutput">readAllStandardOutput</a>(),
<a href="qprocess.html#readChannel">readChannel</a>(), and <a href="qprocess.html#setReadChannel">setReadChannel</a>().</p>
<h3 class="fn"><a name="readAllStandardOutput" /><a href="qbytearray.html">QByteArray</a> QProcess.readAllStandardOutput (<i>self</i>)</h3><p>Regardless of the current read channel, this function returns
all data available from the standard output of the process as a
<a href="qbytearray.html">QByteArray</a>.</p>
<p><b>See also</b> <a href="qprocess.html#readyReadStandardOutput">readyReadStandardOutput</a>(),
<a href="qprocess.html#readAllStandardError">readAllStandardError</a>(),
<a href="qprocess.html#readChannel">readChannel</a>(), and <a href="qprocess.html#setReadChannel">setReadChannel</a>().</p>
<h3 class="fn"><a name="readChannel" /><a href="qprocess.html#ProcessChannel-enum">ProcessChannel</a> QProcess.readChannel (<i>self</i>)</h3><p>Returns the current read channel of the <a href="qprocess.html">QProcess</a>.</p>
<p><b>See also</b> <a href="qprocess.html#setReadChannel">setReadChannel</a>().</p>
<h3 class="fn"><a name="readChannelMode" /><a href="qprocess.html#ProcessChannelMode-enum">ProcessChannelMode</a> QProcess.readChannelMode (<i>self</i>)</h3><h3 class="fn"><a name="readData" />str QProcess.readData (<i>self</i>, int <i>maxlen</i>)</h3><p>Reimplemented from <a href="qiodevice.html#readData">QIODevice.readData</a>().</p>
<h3 class="fn"><a name="setEnvironment" />QProcess.setEnvironment (<i>self</i>, QStringList <i>environment</i>)</h3><p>This function is deprecated.</p>
<p>Sets the environment that <a href="qprocess.html">QProcess</a>
will use when starting a process to the <i>environment</i>
specified which consists of a list of key=value pairs.</p>
<p>For example, the following code adds the <tt>C:\\BIN</tt>
directory to the list of executable paths (<tt>PATHS</tt>) on
Windows:</p>
<pre class="cpp">
<span class="type"><a href="qprocess.html">QProcess</a></span> process;
<span class="type"><a href="qstringlist.html">QStringList</a></span> env <span class="operator">=</span> <span class="type"><a href="qprocess.html">QProcess</a></span><span class="operator">.</span>systemEnvironment();
env <span class="operator"><</span><span class="operator"><</span> <span class="string">"TMPDIR=C:\\MyApp\\temp"</span>; <span class="comment">// Add an environment variable</span>
env<span class="operator">.</span>replaceInStrings(<span class="type"><a href="qregexp.html">QRegExp</a></span>(<span class="string">"^PATH=(.*)"</span><span class="operator">,</span> <span class="type"><a href="qt.html">Qt</a></span><span class="operator">.</span>CaseInsensitive)<span class="operator">,</span> <span class="string">"PATH=\\1;C:\\Bin"</span>);
process<span class="operator">.</span>setEnvironment(env);
process<span class="operator">.</span>start(<span class="string">"myapp"</span>);
</pre>
<p><b>Note:</b> This function is less efficient than the <a href="qprocess.html#setProcessEnvironment">setProcessEnvironment</a>()
function.</p>
<p><b>See also</b> <a href="qprocess.html#environment">environment</a>(), <a href="qprocess.html#setProcessEnvironment">setProcessEnvironment</a>(),
and <a href="qprocess.html#systemEnvironment">systemEnvironment</a>().</p>
<h3 class="fn"><a name="setProcessChannelMode" />QProcess.setProcessChannelMode (<i>self</i>, <a href="qprocess.html#ProcessChannelMode-enum">ProcessChannelMode</a> <i>mode</i>)</h3><p>Sets the channel mode of the <a href="qprocess.html">QProcess</a> standard output and standard error
channels to the <i>mode</i> specified. This mode will be used the
next time <a href="qprocess.html#start">start</a>() is called. For
example:</p>
<pre class="cpp">
<span class="type"><a href="qprocess.html">QProcess</a></span> builder;
builder<span class="operator">.</span>setProcessChannelMode(<span class="type"><a href="qprocess.html">QProcess</a></span><span class="operator">.</span>MergedChannels);
builder<span class="operator">.</span>start(<span class="string">"make"</span><span class="operator">,</span> <span class="type"><a href="qstringlist.html">QStringList</a></span>() <span class="operator"><</span><span class="operator"><</span> <span class="string">"-j2"</span>);
<span class="keyword">if</span> (<span class="operator">!</span>builder<span class="operator">.</span>waitForFinished())
<a href="qtcore.html#qDebug">qDebug</a>() <span class="operator"><</span><span class="operator"><</span> <span class="string">"Make failed:"</span> <span class="operator"><</span><span class="operator"><</span> builder<span class="operator">.</span>errorString();
<span class="keyword">else</span>
<a href="qtcore.html#qDebug">qDebug</a>() <span class="operator"><</span><span class="operator"><</span> <span class="string">"Make output:"</span> <span class="operator"><</span><span class="operator"><</span> builder<span class="operator">.</span>readAll();
</pre>
<p>This function was introduced in Qt 4.2.</p>
<p><b>See also</b> <a href="qprocess.html#processChannelMode">processChannelMode</a>(),
<a href="qprocess.html#ProcessChannelMode-enum">ProcessChannelMode</a>, and
<a href="qprocess.html#setReadChannel">setReadChannel</a>().</p>
<h3 class="fn"><a name="setProcessEnvironment" />QProcess.setProcessEnvironment (<i>self</i>, <a href="qprocessenvironment.html">QProcessEnvironment</a> <i>environment</i>)</h3><p>Sets the environment that <a href="qprocess.html">QProcess</a>
will use when starting a process to the <i>environment</i>
object.</p>
<p>For example, the following code adds the <tt>C:\\BIN</tt>
directory to the list of executable paths (<tt>PATHS</tt>) on
Windows and sets <tt>TMPDIR</tt>:</p>
<pre class="cpp">
<span class="type"><a href="qprocess.html">QProcess</a></span> process;
<span class="type"><a href="qprocessenvironment.html">QProcessEnvironment</a></span> env <span class="operator">=</span> <span class="type"><a href="qprocessenvironment.html">QProcessEnvironment</a></span><span class="operator">.</span>systemEnvironment();
env<span class="operator">.</span>insert(<span class="string">"TMPDIR"</span><span class="operator">,</span> <span class="string">"C:\\MyApp\\temp"</span>); <span class="comment">// Add an environment variable</span>
env<span class="operator">.</span>insert(<span class="string">"PATH"</span><span class="operator">,</span> env<span class="operator">.</span>value(<span class="string">"Path"</span>) <span class="operator">+</span> <span class="string">";C:\\Bin"</span>);
process<span class="operator">.</span>setProcessEnvironment(env);
process<span class="operator">.</span>start(<span class="string">"myapp"</span>);
</pre>
<p>Note how, on Windows, environment variable names are
case-insensitive.</p>
<p>This function was introduced in Qt 4.6.</p>
<p><b>See also</b> <a href="qprocess.html#processEnvironment">processEnvironment</a>(),
<a href="qprocessenvironment.html#systemEnvironment">QProcessEnvironment.systemEnvironment</a>(),
and <a href="qprocess.html#setEnvironment">setEnvironment</a>().</p>
<h3 class="fn"><a name="setProcessState" />QProcess.setProcessState (<i>self</i>, <a href="qprocess.html#ProcessState-enum">ProcessState</a> <i>state</i>)</h3><p>Sets the current state of the <a href="qprocess.html">QProcess</a> to the <i>state</i> specified.</p>
<p><b>See also</b> <a href="qprocess.html#state">state</a>().</p>
<h3 class="fn"><a name="setReadChannel" />QProcess.setReadChannel (<i>self</i>, <a href="qprocess.html#ProcessChannel-enum">ProcessChannel</a> <i>channel</i>)</h3><p>Sets the current read channel of the <a href="qprocess.html">QProcess</a> to the given <i>channel</i>. The
current input channel is used by the functions <a href="qiodevice.html#read">read</a>(), <a href="qiodevice.html#readAll">readAll</a>(), <a href="qiodevice.html#readLine">readLine</a>(), and <a href="qiodevice.html#getChar">getChar</a>(). It also determines which
channel triggers <a href="qprocess.html">QProcess</a> to emit
<a href="qiodevice.html#readyRead">readyRead</a>().</p>
<p><b>See also</b> <a href="qprocess.html#readChannel">readChannel</a>().</p>
<h3 class="fn"><a name="setReadChannelMode" />QProcess.setReadChannelMode (<i>self</i>, <a href="qprocess.html#ProcessChannelMode-enum">ProcessChannelMode</a> <i>mode</i>)</h3><h3 class="fn"><a name="setStandardErrorFile" />QProcess.setStandardErrorFile (<i>self</i>, QString <i>fileName</i>, <a href="qiodevice-openmode.html">QIODevice.OpenMode</a> <i>mode</i> = QIODevice.Truncate)</h3><p>Redirects the process' standard error to the file
<i>fileName</i>. When the redirection is in place, the standard
error read channel is closed: reading from it using <a href="qiodevice.html#read">read</a>() will always fail, as will <a href="qprocess.html#readAllStandardError">readAllStandardError</a>().
The file will be appended to if <i>mode</i> is Append, otherwise,
it will be truncated.</p>
<p>See <a href="qprocess.html#setStandardOutputFile">setStandardOutputFile</a>()
for more information on how the file is opened.</p>
<p>Note: if <a href="qprocess.html#setProcessChannelMode">setProcessChannelMode</a>()
was called with an argument of <a href="qprocess.html#ProcessChannelMode-enum">QProcess.MergedChannels</a>,
this function has no effect.</p>
<p>This function was introduced in Qt 4.2.</p>
<p><b>See also</b> <a href="qprocess.html#setStandardInputFile">setStandardInputFile</a>(),
<a href="qprocess.html#setStandardOutputFile">setStandardOutputFile</a>(),
and <a href="qprocess.html#setStandardOutputProcess">setStandardOutputProcess</a>().</p>
<h3 class="fn"><a name="setStandardInputFile" />QProcess.setStandardInputFile (<i>self</i>, QString <i>fileName</i>)</h3><p>Redirects the process' standard input to the file indicated by
<i>fileName</i>. When an input redirection is in place, the
<a href="qprocess.html">QProcess</a> object will be in read-only
mode (calling <a href="qiodevice.html#write">write</a>() will
result in error).</p>
<p>If the file <i>fileName</i> does not exist at the moment
<a href="qprocess.html#start">start</a>() is called or is not
readable, starting the process will fail.</p>
<p>Calling setStandardInputFile() after the process has started has
no effect.</p>
<p>This function was introduced in Qt 4.2.</p>
<p><b>See also</b> <a href="qprocess.html#setStandardOutputFile">setStandardOutputFile</a>(),
<a href="qprocess.html#setStandardErrorFile">setStandardErrorFile</a>(),
and <a href="qprocess.html#setStandardOutputProcess">setStandardOutputProcess</a>().</p>
<h3 class="fn"><a name="setStandardOutputFile" />QProcess.setStandardOutputFile (<i>self</i>, QString <i>fileName</i>, <a href="qiodevice-openmode.html">QIODevice.OpenMode</a> <i>mode</i> = QIODevice.Truncate)</h3><p>Redirects the process' standard output to the file
<i>fileName</i>. When the redirection is in place, the standard
output read channel is closed: reading from it using <a href="qiodevice.html#read">read</a>() will always fail, as will <a href="qprocess.html#readAllStandardOutput">readAllStandardOutput</a>().</p>
<p>If the file <i>fileName</i> doesn't exist at the moment <a href="qprocess.html#start">start</a>() is called, it will be created. If
it cannot be created, the starting will fail.</p>
<p>If the file exists and <i>mode</i> is <a href="qiodevice.html#OpenModeFlag-enum">QIODevice.Truncate</a>, the
file will be truncated. Otherwise (if <i>mode</i> is <a href="qiodevice.html#OpenModeFlag-enum">QIODevice.Append</a>), the file
will be appended to.</p>
<p>Calling setStandardOutputFile() after the process has started
has no effect.</p>
<p>This function was introduced in Qt 4.2.</p>
<p><b>See also</b> <a href="qprocess.html#setStandardInputFile">setStandardInputFile</a>(),
<a href="qprocess.html#setStandardErrorFile">setStandardErrorFile</a>(),
and <a href="qprocess.html#setStandardOutputProcess">setStandardOutputProcess</a>().</p>
<h3 class="fn"><a name="setStandardOutputProcess" />QProcess.setStandardOutputProcess (<i>self</i>, <a href="qprocess.html">QProcess</a> <i>destination</i>)</h3><p>Pipes the standard output stream of this process to the
<i>destination</i> process' standard input.</p>
<p>The following shell command:</p>
<pre class="cpp">
command1 <span class="operator">|</span> command2
</pre>
<p>Can be accomplished with QProcesses with the following code:</p>
<pre class="cpp">
<span class="type"><a href="qprocess.html">QProcess</a></span> process1;
<span class="type"><a href="qprocess.html">QProcess</a></span> process2;
process1<span class="operator">.</span>setStandardOutputProcess(<span class="operator">&</span>process2);
process1<span class="operator">.</span>start(<span class="string">"command1"</span>);
process2<span class="operator">.</span>start(<span class="string">"command2"</span>);
</pre>
<p>This function was introduced in Qt 4.2.</p>
<h3 class="fn"><a name="setupChildProcess" />QProcess.setupChildProcess (<i>self</i>)</h3><p>This function is called in the child process context just before
the program is executed on Unix or Mac OS X (i.e., after
<i>fork()</i>, but before <i>execve()</i>). Reimplement this
function to do last minute initialization of the child process.
Example:</p>
<pre class="cpp">
<span class="keyword">class</span> SandboxProcess : <span class="keyword">public</span> <span class="type"><a href="qprocess.html">QProcess</a></span>
{
<span class="operator">.</span><span class="operator">.</span><span class="operator">.</span>
<span class="keyword">protected</span>:
<span class="type">void</span> setupChildProcess();
<span class="operator">.</span><span class="operator">.</span><span class="operator">.</span>
};
<span class="type">void</span> SandboxProcess<span class="operator">.</span>setupChildProcess()
{
<span class="comment">// Drop all privileges in the child process, and enter</span>
<span class="comment">// a chroot jail.</span>
<span class="preprocessor">#if defined Q_OS_UNIX</span>
<span class="operator">.</span>setgroups(<span class="number">0</span><span class="operator">,</span> <span class="number">0</span>);
<span class="operator">.</span>chroot(<span class="string">"/etc/safe"</span>);
<span class="operator">.</span>chdir(<span class="string">"/"</span>);
<span class="operator">.</span>setgid(safeGid);
<span class="operator">.</span>setuid(safeUid);
<span class="operator">.</span>umask(<span class="number">0</span>);
<span class="preprocessor">#endif</span>
}
</pre>
<p>You cannot exit the process (by calling exit(), for instance)
from this function. If you need to stop the program before it
starts execution, your workaround is to emit <a href="qprocess.html#finished">finished</a>() and then call exit().</p>
<p><b>Warning:</b> This function is called by <a href="qprocess.html">QProcess</a> on Unix and Mac OS X only. On Windows
and QNX, it is not called.</p>
<h3 class="fn"><a name="setWorkingDirectory" />QProcess.setWorkingDirectory (<i>self</i>, QString <i>dir</i>)</h3><p>Sets the working directory to <i>dir</i>. <a href="qprocess.html">QProcess</a> will start the process in this
directory. The default behavior is to start the process in the
working directory of the calling process.</p>
<p><b>Note:</b> The working directory setting is ignored on
Symbian; the private directory of the process is considered its
working directory.</p>
<p><b>Note:</b> On QNX, this may cause all application threads to
temporarily freeze.</p>
<p><b>See also</b> <a href="qprocess.html#workingDirectory">workingDirectory</a>() and
<a href="qprocess.html#start">start</a>().</p>
<h3 class="fn"><a name="start" />QProcess.start (<i>self</i>, QString <i>program</i>, QStringList <i>arguments</i>, <a href="qiodevice-openmode.html">QIODevice.OpenMode</a> <i>mode</i> = QIODevice.ReadWrite)</h3><p>Starts the given <i>program</i> in a new process, if none is
already running, passing the command line arguments in
<i>arguments</i>. The <a href="qiodevice.html#OpenModeFlag-enum">OpenMode</a> is set to
<i>mode</i>.</p>
<p>The <a href="qprocess.html">QProcess</a> object will immediately
enter the Starting state. If the process starts successfully,
<a href="qprocess.html">QProcess</a> will emit <a href="qprocess.html#started">started</a>(); otherwise, <a href="qprocess.html#error">error</a>() will be emitted. If the <a href="qprocess.html">QProcess</a> object is already running a process, a
warning may be printed at the console, and the existing process
will continue running.</p>
<p><b>Note:</b> Processes are started asynchronously, which means
the <a href="qprocess.html#started">started</a>() and <a href="qprocess.html#error">error</a>() signals may be delayed. Call
<a href="qprocess.html#waitForStarted">waitForStarted</a>() to make
sure the process has started (or has failed to start) and those
signals have been emitted.</p>
<p><b>Note:</b> No further splitting of the arguments is
performed.</p>
<p><b>Windows:</b> Arguments that contain spaces are wrapped in
quotes.</p>
<p><b>See also</b> <a href="qprocess.html#pid">pid</a>(), <a href="qprocess.html#started">started</a>(), and <a href="qprocess.html#waitForStarted">waitForStarted</a>().</p>
<h3 class="fn"><a name="start-2" />QProcess.start (<i>self</i>, QString <i>program</i>, <a href="qiodevice-openmode.html">QIODevice.OpenMode</a> <i>mode</i> = QIODevice.ReadWrite)</h3><p>This is an overloaded function.</p>
<p>Starts the program <i>program</i> in a new process, if one is
not already running. <i>program</i> is a single string of text
containing both the program name and its arguments. The arguments
are separated by one or more spaces. For example:</p>
<pre class="cpp">
<span class="type"><a href="qprocess.html">QProcess</a></span> process;
process<span class="operator">.</span>start(<span class="string">"del /s *.txt"</span>);
<span class="comment">// same as process.start("del", QStringList() << "/s" << "*.txt");</span>
<span class="operator">.</span><span class="operator">.</span><span class="operator">.</span>
</pre>
<p>The <i>program</i> string can also contain quotes, to ensure
that arguments containing spaces are correctly supplied to the new
process. For example:</p>
<pre class="cpp">
<span class="type"><a href="qprocess.html">QProcess</a></span> process;
process<span class="operator">.</span>start(<span class="string">"dir \"My Documents\""</span>);
</pre>
<p>If the <a href="qprocess.html">QProcess</a> object is already
running a process, a warning may be printed at the console, and the
existing process will continue running.</p>
<p>Note that, on Windows, quotes need to be both escaped and
quoted. For example, the above code would be specified in the
following way to ensure that <tt>"My Documents"</tt> is used as the
argument to the <tt>dir</tt> executable:</p>
<pre class="cpp">
<span class="type"><a href="qprocess.html">QProcess</a></span> process;
process<span class="operator">.</span>start(<span class="string">"dir \"\"\"My Documents\"\"\""</span>);
</pre>
<p>The <a href="qiodevice.html#OpenModeFlag-enum">OpenMode</a> is
set to <i>mode</i>.</p>
<h3 class="fn"><a name="startDetached" />(bool, int <i>pid</i>) QProcess.startDetached (QString <i>program</i>, QStringList <i>arguments</i>, QString <i>workingDirectory</i>)</h3><p>Starts the program <i>program</i> with the arguments
<i>arguments</i> in a new process, and detaches from it. Returns
true on success; otherwise returns false. If the calling process
exits, the detached process will continue to live.</p>
<p>Note that arguments that contain spaces are not passed to the
process as separate arguments.</p>
<p><b>Unix:</b> The started process will run in its own session and
act like a daemon.</p>
<p><b>Windows:</b> Arguments that contain spaces are wrapped in
quotes. The started process will run as a regular standalone
process.</p>
<p>The process will be started in the directory
<i>workingDirectory</i>.</p>
<p><b>Note:</b> On QNX, this may cause all application threads to
temporarily freeze.</p>
<p><b>Note:</b> On VxWorks, this will start RTP process always with
priority set to 220.</p>
<p>If the function is successful then *<i>pid</i> is set to the
process identifier of the started process.</p>
<h3 class="fn"><a name="startDetached-2" />bool QProcess.startDetached (QString <i>program</i>, QStringList <i>arguments</i>)</h3><p>Starts the program <i>program</i> with the given
<i>arguments</i> in a new process, and detaches from it. Returns
true on success; otherwise returns false. If the calling process
exits, the detached process will continue to live.</p>
<p><b>Note:</b> Arguments that contain spaces are not passed to the
process as separate arguments.</p>
<p><b>Unix:</b> The started process will run in its own session and
act like a daemon.</p>
<p><b>Windows:</b> Arguments that contain spaces are wrapped in
quotes. The started process will run as a regular standalone
process.</p>
<h3 class="fn"><a name="startDetached-3" />bool QProcess.startDetached (QString <i>program</i>)</h3><p>This is an overloaded function.</p>
<p>Starts the program <i>program</i> in a new process.
<i>program</i> is a single string of text containing both the
program name and its arguments. The arguments are separated by one
or more spaces.</p>
<p>The <i>program</i> string can also contain quotes, to ensure
that arguments containing spaces are correctly supplied to the new
process.</p>
<h3 class="fn"><a name="state" /><a href="qprocess.html#ProcessState-enum">ProcessState</a> QProcess.state (<i>self</i>)</h3><p>Returns the current state of the process.</p>
<p><b>See also</b> <a href="qprocess.html#stateChanged">stateChanged</a>() and <a href="qprocess.html#error">error</a>().</p>
<h3 class="fn"><a name="systemEnvironment" />QStringList QProcess.systemEnvironment ()</h3><p>Returns the environment of the calling process as a list of
key=value pairs. Example:</p>
<pre class="cpp">
<span class="type"><a href="qstringlist.html">QStringList</a></span> environment <span class="operator">=</span> <span class="type"><a href="qprocess.html">QProcess</a></span><span class="operator">.</span>systemEnvironment();
<span class="comment">// environment = {"PATH=/usr/bin:/usr/local/bin",</span>
<span class="comment">// "USER=greg", "HOME=/home/greg"}</span>
</pre>
<p>This function does not cache the system environment. Therefore,
it's possible to obtain an updated version of the environment if
low-level C library functions like <tt>setenv</tt> ot
<tt>putenv</tt> have been called.</p>
<p>However, note that repeated calls to this function will recreate
the list of environment variables, which is a non-trivial
operation.</p>
<p><b>Note:</b> For new code, it is recommended to use <a href="qprocessenvironment.html#systemEnvironment">QProcessEnvironment.systemEnvironment</a>()</p>
<p>This function was introduced in Qt 4.1.</p>
<p><b>See also</b> <a href="qprocessenvironment.html#systemEnvironment">QProcessEnvironment.systemEnvironment</a>(),
<a href="qprocess.html#environment">environment</a>(), and <a href="qprocess.html#setEnvironment">setEnvironment</a>().</p>
<h3 class="fn"><a name="terminate" />QProcess.terminate (<i>self</i>)</h3><p>This method is also a Qt slot with the C++ signature <tt>void terminate()</tt>.</p><p>Attempts to terminate the process.</p>
<p>The process may not exit as a result of calling this function
(it is given the chance to prompt the user for any unsaved files,
etc).</p>
<p>On Windows, terminate() posts a WM_CLOSE message to all toplevel
windows of the process and then to the main thread of the process
itself. On Unix and Mac OS X the SIGTERM signal is sent.</p>
<p>Console applications on Windows that do not run an event loop,
or whose event loop does not handle the WM_CLOSE message, can only
be terminated by calling <a href="qprocess.html#kill">kill</a>().</p>
<p>On Symbian, this function requires platform security capability
<tt>PowerMgmt</tt>. If absent, the process will panic with
KERN-EXEC 46.</p>
<p><b>Note:</b> Terminating running processes from other processes
will typically cause a panic in Symbian due to platform
security.</p>
<p><b>See also</b> <a href="symbian-platform-security-requirements.html">Symbian Platform
Security Requirements</a> and <a href="qprocess.html#kill">kill</a>().</p>
<h3 class="fn"><a name="waitForBytesWritten" />bool QProcess.waitForBytesWritten (<i>self</i>, int <i>msecs</i> = 30000)</h3><p>Reimplemented from <a href="qiodevice.html#waitForBytesWritten">QIODevice.waitForBytesWritten</a>().</p>
<h3 class="fn"><a name="waitForFinished" />bool QProcess.waitForFinished (<i>self</i>, int <i>msecs</i> = 30000)</h3><p>Blocks until the process has finished and the <a href="qprocess.html#finished">finished</a>() signal has been emitted, or
until <i>msecs</i> milliseconds have passed.</p>
<p>Returns true if the process finished; otherwise returns false
(if the operation timed out, if an error occurred, or if this
<a href="qprocess.html">QProcess</a> is already finished).</p>
<p>This function can operate without an event loop. It is useful
when writing non-GUI applications and when performing I/O
operations in a non-GUI thread.</p>
<p><b>Warning:</b> Calling this function from the main (GUI) thread
might cause your user interface to freeze.</p>
<p>If msecs is -1, this function will not time out.</p>
<p><b>See also</b> <a href="qprocess.html#finished">finished</a>(),
<a href="qprocess.html#waitForStarted">waitForStarted</a>(),
<a href="qprocess.html#waitForReadyRead">waitForReadyRead</a>(),
and <a href="qprocess.html#waitForBytesWritten">waitForBytesWritten</a>().</p>
<h3 class="fn"><a name="waitForReadyRead" />bool QProcess.waitForReadyRead (<i>self</i>, int <i>msecs</i> = 30000)</h3><p>Reimplemented from <a href="qiodevice.html#waitForReadyRead">QIODevice.waitForReadyRead</a>().</p>
<h3 class="fn"><a name="waitForStarted" />bool QProcess.waitForStarted (<i>self</i>, int <i>msecs</i> = 30000)</h3><p>Blocks until the process has started and the <a href="qprocess.html#started">started</a>() signal has been emitted, or
until <i>msecs</i> milliseconds have passed.</p>
<p>Returns true if the process was started successfully; otherwise
returns false (if the operation timed out or if an error
occurred).</p>
<p>This function can operate without an event loop. It is useful
when writing non-GUI applications and when performing I/O
operations in a non-GUI thread.</p>
<p><b>Warning:</b> Calling this function from the main (GUI) thread
might cause your user interface to freeze.</p>
<p>If msecs is -1, this function will not time out.</p>
<p><b>See also</b> <a href="qprocess.html#started">started</a>(),
<a href="qprocess.html#waitForReadyRead">waitForReadyRead</a>(),
<a href="qprocess.html#waitForBytesWritten">waitForBytesWritten</a>(), and
<a href="qprocess.html#waitForFinished">waitForFinished</a>().</p>
<h3 class="fn"><a name="workingDirectory" />QString QProcess.workingDirectory (<i>self</i>)</h3><p>If <a href="qprocess.html">QProcess</a> has been assigned a
working directory, this function returns the working directory that
the <a href="qprocess.html">QProcess</a> will enter before the
program has started. Otherwise, (i.e., no directory has been
assigned,) an empty string is returned, and <a href="qprocess.html">QProcess</a> will use the application's current
working directory instead.</p>
<p><b>See also</b> <a href="qprocess.html#setWorkingDirectory">setWorkingDirectory</a>().</p>
<h3 class="fn"><a name="writeData" />int QProcess.writeData (<i>self</i>, str <i>data</i>)</h3><p>Reimplemented from <a href="qiodevice.html#writeData">QIODevice.writeData</a>().</p>
<hr /><h2>Qt Signal Documentation</h2><h3 class="fn"><a name="error-2" />void error (QProcess::ProcessError)</h3><p>This is the default overload of this signal.</p><p>This signal is emitted when an error occurs with the process.
The specified <i>error</i> describes the type of error that
occurred.</p>
<h3 class="fn"><a name="finished" />void finished (int,QProcess::ExitStatus)</h3><p>This is the default overload of this signal.</p><p>This signal is emitted when the process finishes.
<i>exitCode</i> is the exit code of the process, and
<i>exitStatus</i> is the exit status. After the process has
finished, the buffers in <a href="qprocess.html">QProcess</a> are
still intact. You can still read any data that the process may have
written before it finished.</p>
<p><b>See also</b> <a href="qprocess.html#exitStatus">exitStatus</a>().</p>
<h3 class="fn"><a name="finished-2" />void finished (int)</h3><h3 class="fn"><a name="readyReadStandardError" />void readyReadStandardError ()</h3><p>This is the default overload of this signal.</p><p>This signal is emitted when the process has made new data
available through its standard error channel (<tt>stderr</tt>). It
is emitted regardless of the current <a href="qprocess.html#readChannel">read channel</a>.</p>
<p><b>See also</b> <a href="qprocess.html#readAllStandardError">readAllStandardError</a>() and
<a href="qprocess.html#readChannel">readChannel</a>().</p>
<h3 class="fn"><a name="readyReadStandardOutput" />void readyReadStandardOutput ()</h3><p>This is the default overload of this signal.</p><p>This signal is emitted when the process has made new data
available through its standard output channel (<tt>stdout</tt>). It
is emitted regardless of the current <a href="qprocess.html#readChannel">read channel</a>.</p>
<p><b>See also</b> <a href="qprocess.html#readAllStandardOutput">readAllStandardOutput</a>()
and <a href="qprocess.html#readChannel">readChannel</a>().</p>
<h3 class="fn"><a name="started" />void started ()</h3><p>This is the default overload of this signal.</p><p>This signal is emitted by <a href="qprocess.html">QProcess</a>
when the process has started, and <a href="qprocess.html#state">state</a>() returns <a href="qprocess.html#ProcessState-enum">Running</a>.</p>
<h3 class="fn"><a name="stateChanged" />void stateChanged (QProcess::ProcessState)</h3><p>This is the default overload of this signal.</p><p>This signal is emitted whenever the state of <a href="qprocess.html">QProcess</a> changes. The <i>newState</i> argument
is the state <a href="qprocess.html">QProcess</a> changed to.</p>
<address><hr /><div align="center"><table border="0" cellspacing="0" width="100%"><tr class="address"><td align="left" width="25%">PyQt 4.10.3 for X11</td><td align="center" width="50%">Copyright © <a href="http://www.riverbankcomputing.com">Riverbank Computing Ltd</a> and <a href="http://www.qtsoftware.com">Nokia</a> 2012</td><td align="right" width="25%">Qt 4.8.5</td></tr></table></div></address></body></html>
