|
|
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
|
|
|
<!-- /home/espenr/tmp/qt-3.3.8-espenr-2499/qt-x11-free-3.3.8/src/kernel/qprocess.cpp:52 -->
|
|
|
<html>
|
|
|
<head>
|
|
|
<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
|
|
|
<title>TQProcess Class</title>
|
|
|
<style type="text/css"><!--
|
|
|
fn { margin-left: 1cm; text-indent: -1cm; }
|
|
|
a:link { color: #004faf; text-decoration: none }
|
|
|
a:visited { color: #672967; text-decoration: none }
|
|
|
body { background: #ffffff; color: black; }
|
|
|
--></style>
|
|
|
</head>
|
|
|
<body>
|
|
|
|
|
|
<table border="0" cellpadding="0" cellspacing="0" width="100%">
|
|
|
<tr bgcolor="#E5E5E5">
|
|
|
<td 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="mainclasses.html">
|
|
|
<font color="#004faf">Main Classes</font></a>
|
|
|
| <a href="annotated.html">
|
|
|
<font color="#004faf">Annotated</font></a>
|
|
|
| <a href="groups.html">
|
|
|
<font color="#004faf">Grouped Classes</font></a>
|
|
|
| <a href="functions.html">
|
|
|
<font color="#004faf">Functions</font></a>
|
|
|
</td>
|
|
|
<td align="right" valign="center"><img src="logo32.png" align="right" width="64" height="32" border="0"></td></tr></table><h1 align=center>TQProcess Class Reference</h1>
|
|
|
|
|
|
<p>The TQProcess class is used to start external programs and
|
|
|
to communicate with them.
|
|
|
<a href="#details">More...</a>
|
|
|
<p><tt>#include <<a href="qprocess-h.html">ntqprocess.h</a>></tt>
|
|
|
<p>Inherits <a href="ntqobject.html">TQObject</a>.
|
|
|
<p><a href="qprocess-members.html">List of all member functions.</a>
|
|
|
<h2>Public Members</h2>
|
|
|
<ul>
|
|
|
<li class=fn><a href="#TQProcess"><b>TQProcess</b></a> ( TQObject * parent = 0, const char * name = 0 )</li>
|
|
|
<li class=fn><a href="#TQProcess-2"><b>TQProcess</b></a> ( const TQString & arg0, TQObject * parent = 0, const char * name = 0 )</li>
|
|
|
<li class=fn><a href="#TQProcess-3"><b>TQProcess</b></a> ( const TQStringList & args, TQObject * parent = 0, const char * name = 0 )</li>
|
|
|
<li class=fn><a href="#~TQProcess"><b>~TQProcess</b></a> ()</li>
|
|
|
<li class=fn>TQStringList <a href="#arguments"><b>arguments</b></a> () const</li>
|
|
|
<li class=fn>void <a href="#clearArguments"><b>clearArguments</b></a> ()</li>
|
|
|
<li class=fn>virtual void <a href="#setArguments"><b>setArguments</b></a> ( const TQStringList & args )</li>
|
|
|
<li class=fn>virtual void <a href="#addArgument"><b>addArgument</b></a> ( const TQString & arg )</li>
|
|
|
<li class=fn>TQDir <a href="#workingDirectory"><b>workingDirectory</b></a> () const</li>
|
|
|
<li class=fn>virtual void <a href="#setWorkingDirectory"><b>setWorkingDirectory</b></a> ( const TQDir & dir )</li>
|
|
|
<li class=fn>enum <a href="#Communication-enum"><b>Communication</b></a> { Stdin = 0x01, Stdout = 0x02, Stderr = 0x04, DupStderr = 0x08 }</li>
|
|
|
<li class=fn>void <a href="#setCommunication"><b>setCommunication</b></a> ( int commFlags )</li>
|
|
|
<li class=fn>int <a href="#communication"><b>communication</b></a> () const</li>
|
|
|
<li class=fn>virtual bool <a href="#start"><b>start</b></a> ( TQStringList * env = 0 )</li>
|
|
|
<li class=fn>virtual bool <a href="#launch-2"><b>launch</b></a> ( const TQString & buf, TQStringList * env = 0 )</li>
|
|
|
<li class=fn>virtual bool <a href="#launch"><b>launch</b></a> ( const TQByteArray & buf, TQStringList * env = 0 )</li>
|
|
|
<li class=fn>bool <a href="#isRunning"><b>isRunning</b></a> () const</li>
|
|
|
<li class=fn>bool <a href="#normalExit"><b>normalExit</b></a> () const</li>
|
|
|
<li class=fn>int <a href="#exitStatus"><b>exitStatus</b></a> () const</li>
|
|
|
<li class=fn>virtual TQByteArray <a href="#readStdout"><b>readStdout</b></a> ()</li>
|
|
|
<li class=fn>virtual TQByteArray <a href="#readStderr"><b>readStderr</b></a> ()</li>
|
|
|
<li class=fn>bool <a href="#canReadLineStdout"><b>canReadLineStdout</b></a> () const</li>
|
|
|
<li class=fn>bool <a href="#canReadLineStderr"><b>canReadLineStderr</b></a> () const</li>
|
|
|
<li class=fn>virtual TQString <a href="#readLineStdout"><b>readLineStdout</b></a> ()</li>
|
|
|
<li class=fn>virtual TQString <a href="#readLineStderr"><b>readLineStderr</b></a> ()</li>
|
|
|
<li class=fn>PID <a href="#processIdentifier"><b>processIdentifier</b></a> ()</li>
|
|
|
</ul>
|
|
|
<h2>Public Slots</h2>
|
|
|
<ul>
|
|
|
<li class=fn>void <a href="#tryTerminate"><b>tryTerminate</b></a> () const</li>
|
|
|
<li class=fn>void <a href="#kill"><b>kill</b></a> () const</li>
|
|
|
<li class=fn>virtual void <a href="#writeToStdin"><b>writeToStdin</b></a> ( const TQByteArray & buf )</li>
|
|
|
<li class=fn>virtual void <a href="#writeToStdin-2"><b>writeToStdin</b></a> ( const TQString & buf )</li>
|
|
|
<li class=fn>virtual void <a href="#closeStdin"><b>closeStdin</b></a> ()</li>
|
|
|
</ul>
|
|
|
<h2>Signals</h2>
|
|
|
<ul>
|
|
|
<li class=fn>void <a href="#readyReadStdout"><b>readyReadStdout</b></a> ()</li>
|
|
|
<li class=fn>void <a href="#readyReadStderr"><b>readyReadStderr</b></a> ()</li>
|
|
|
<li class=fn>void <a href="#processExited"><b>processExited</b></a> ()</li>
|
|
|
<li class=fn>void <a href="#wroteToStdin"><b>wroteToStdin</b></a> ()</li>
|
|
|
<li class=fn>void <a href="#launchFinished"><b>launchFinished</b></a> ()</li>
|
|
|
</ul>
|
|
|
<hr><a name="details"></a><h2>Detailed Description</h2>
|
|
|
|
|
|
|
|
|
<p> The TQProcess class is used to start external programs and
|
|
|
to communicate with them.
|
|
|
<p>
|
|
|
|
|
|
|
|
|
<p> You can write to the started program's standard input, and can
|
|
|
read the program's standard output and standard error. You can
|
|
|
pass command line arguments to the program either in the
|
|
|
constructor or with <a href="#setArguments">setArguments</a>() or <a href="#addArgument">addArgument</a>(). The program's
|
|
|
working directory can be set with <a href="#setWorkingDirectory">setWorkingDirectory</a>(). If you
|
|
|
need to set up environment variables pass them to the <a href="#start">start</a>() or
|
|
|
<a href="#launch">launch</a>() functions (see below). The <a href="#processExited">processExited</a>() signal is
|
|
|
emitted if the program exits. The program's exit status is
|
|
|
available from <a href="#exitStatus">exitStatus</a>(), although you could simply call
|
|
|
<a href="#normalExit">normalExit</a>() to see if the program terminated normally.
|
|
|
<p> There are two different ways to start a process. If you just want
|
|
|
to run a program, optionally passing data to its standard input at
|
|
|
the beginning, use one of the launch() functions. If you want full
|
|
|
control of the program's standard input (especially if you don't
|
|
|
know all the data you want to send to standard input at the
|
|
|
beginning), use the start() function.
|
|
|
<p> If you use start() you can write to the program's standard input
|
|
|
using <a href="#writeToStdin">writeToStdin</a>() and you can close the standard input with
|
|
|
<a href="#closeStdin">closeStdin</a>(). The <a href="#wroteToStdin">wroteToStdin</a>() signal is emitted if the data
|
|
|
sent to standard input has been written. You can read from the
|
|
|
program's standard output using <a href="#readStdout">readStdout</a>() or <a href="#readLineStdout">readLineStdout</a>().
|
|
|
These functions return an empty <a href="qbytearray.html">TQByteArray</a> if there is no data to
|
|
|
read. The <a href="#readyReadStdout">readyReadStdout</a>() signal is emitted when there is data
|
|
|
available to be read from standard output. Standard error has a
|
|
|
set of functions that correspond to the standard output functions,
|
|
|
i.e. <a href="#readStderr">readStderr</a>(), <a href="#readLineStderr">readLineStderr</a>() and <a href="#readyReadStderr">readyReadStderr</a>().
|
|
|
<p> If you use one of the <a href="#launch">launch</a>() functions the data you pass will be
|
|
|
sent to the program's standard input which will be closed once all
|
|
|
the data has been written. You should <em>not</em> use <a href="#writeToStdin">writeToStdin</a>() or
|
|
|
<a href="#closeStdin">closeStdin</a>() if you use launch(). If you need to send data to the
|
|
|
program's standard input after it has started running use <a href="#start">start</a>()
|
|
|
instead of launch().
|
|
|
<p> Both start() and launch() can accept a string list of strings each
|
|
|
of which has the format, key=value, where the keys are the names
|
|
|
of environment variables.
|
|
|
<p> You can test to see if a program is running with <a href="#isRunning">isRunning</a>(). The
|
|
|
program's process identifier is available from
|
|
|
<a href="#processIdentifier">processIdentifier</a>(). If you want to terminate a running program
|
|
|
use <a href="#tryTerminate">tryTerminate</a>(), but note that the program may ignore this. If
|
|
|
you <em>really</em> want to terminate the program, without it having any
|
|
|
chance to clean up, you can use <a href="#kill">kill</a>().
|
|
|
<p> As an example, suppose we want to start the <tt>uic</tt> command (a TQt
|
|
|
command line tool used with <em>TQt Designer</em>) and perform some
|
|
|
operations on the output (the <tt>uic</tt> outputs the code it generates
|
|
|
to standard output by default). Suppose further that we want to
|
|
|
run the program on the file "small_dialog.ui" with the command
|
|
|
line options "-tr <a href="i18n.html#i18n">i18n</a>". On the command line we would write:
|
|
|
<pre>
|
|
|
uic -tr i18n small_dialog.ui
|
|
|
</pre>
|
|
|
|
|
|
<p>
|
|
|
|
|
|
<p> A code snippet for this with the TQProcess class might look like
|
|
|
this:
|
|
|
<p> <pre> UicManager::UicManager()
|
|
|
{
|
|
|
</pre><pre> proc = new TQProcess( this );
|
|
|
</pre><pre> <a name="x2122"></a> proc-><a href="#addArgument">addArgument</a>( "uic" );
|
|
|
proc-><a href="#addArgument">addArgument</a>( "-tr" );
|
|
|
proc-><a href="#addArgument">addArgument</a>( "i18n" );
|
|
|
proc-><a href="#addArgument">addArgument</a>( "small_dialog.ui" );
|
|
|
|
|
|
<a name="x2123"></a> <a href="ntqobject.html#connect">connect</a>( proc, SIGNAL(<a href="#readyReadStdout">readyReadStdout</a>()),
|
|
|
this, SLOT(readFromStdout()) );
|
|
|
</pre><pre> <a name="x2124"></a> if ( !proc-><a href="#start">start</a>() ) {
|
|
|
// error handling
|
|
|
</pre><pre> }
|
|
|
}
|
|
|
</pre>
|
|
|
<p> <pre> void UicManager::readFromStdout()
|
|
|
{
|
|
|
// Read and process the data.
|
|
|
// Bear in mind that the data might be output in chunks.
|
|
|
</pre><pre> }
|
|
|
</pre>
|
|
|
<p> Although you may need quotes for a file named on the command line
|
|
|
(e.g. if it contains spaces) you shouldn't use extra quotes for
|
|
|
arguments passed to <a href="#addArgument">addArgument</a>() or <a href="#setArguments">setArguments</a>().
|
|
|
<p> The <a href="#readyReadStdout">readyReadStdout</a>() signal is emitted when there is new data on
|
|
|
standard output. This happens asynchronously: you don't know if
|
|
|
more data will arrive later.
|
|
|
<p> In the above example you could connect the <a href="#processExited">processExited</a>() signal
|
|
|
to the slot UicManager::readFromStdout() instead. If you do so,
|
|
|
you will be certain that all the data is available when the slot
|
|
|
is called. On the other hand, you must wait until the process has
|
|
|
finished before doing any processing.
|
|
|
<p> Note that if you are expecting a lot of output from the process,
|
|
|
you may hit platform-dependent limits to the pipe buffer size. The
|
|
|
solution is to make sure you connect to the output, e.g. the
|
|
|
readyReadStdout() and <a href="#readyReadStderr">readyReadStderr</a>() signals and read the data
|
|
|
as soon as it becomes available.
|
|
|
<p> Please note that TQProcess does not emulate a shell. This means that
|
|
|
TQProcess does not do any expansion of arguments: a '*' is passed as a '*'
|
|
|
to the program and is <em>not</em> replaced by all the files, a '$HOME' is also
|
|
|
passed literally and is <em>not</em> replaced by the environment variable HOME
|
|
|
and the special characters for IO redirection ('>', '|', etc.) are also
|
|
|
passed literally and do <em>not</em> have the special meaning as they have in a
|
|
|
shell.
|
|
|
<p> Also note that TQProcess does not emulate a terminal. This means that
|
|
|
certain programs which need direct terminal control, do not work as
|
|
|
expected with TQProcess. Such programs include console email programs (like
|
|
|
pine and mutt) but also programs which require the user to enter a password
|
|
|
(like su and ssh).
|
|
|
<p> <h3> Notes for Windows users
|
|
|
</h3>
|
|
|
<a name="1"></a><p> Some Windows commands, for example, <tt>dir</tt>, are not provided by
|
|
|
separate applications, but by the command interpreter.
|
|
|
If you attempt to use TQProcess 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> Under Windows there are certain problems starting 16-bit applications
|
|
|
and capturing their output. Microsoft recommends using an intermediate
|
|
|
application to start 16-bit applications.
|
|
|
<p> <p>See also <a href="ntqsocket.html">TQSocket</a>, <a href="io.html">Input/Output and Networking</a>, and <a href="misc.html">Miscellaneous Classes</a>.
|
|
|
|
|
|
<hr><h2>Member Type Documentation</h2>
|
|
|
<h3 class=fn><a name="Communication-enum"></a>TQProcess::Communication</h3>
|
|
|
|
|
|
<p> This enum type defines the communication channels connected to the
|
|
|
process.
|
|
|
<ul>
|
|
|
<li><tt>TQProcess::Stdin</tt> - Data can be written to the process's standard input.
|
|
|
<li><tt>TQProcess::Stdout</tt> - Data can be read from the process's standard
|
|
|
output.
|
|
|
<li><tt>TQProcess::Stderr</tt> - Data can be read from the process's standard error.
|
|
|
<li><tt>TQProcess::DupStderr</tt> - Both the process's standard error output <em>and</em>
|
|
|
its standard output are written to its standard output. (Like
|
|
|
Unix's dup2().) This means that nothing is sent to the standard
|
|
|
error output. This is especially useful if your application
|
|
|
requires that the output on standard output and on standard error
|
|
|
must be read in the same order that they are produced. This is a
|
|
|
flag, so to activate it you must pass <tt>Stdout|Stderr|DupStderr</tt>,
|
|
|
or <tt>Stdin|Stdout|Stderr|DupStderr</tt> if you want to provide input,
|
|
|
to the <a href="#setCommunication">setCommunication</a>() call.
|
|
|
</ul><p> <p>See also <a href="#setCommunication">setCommunication</a>() and <a href="#communication">communication</a>().
|
|
|
|
|
|
<hr><h2>Member Function Documentation</h2>
|
|
|
<h3 class=fn><a name="TQProcess"></a>TQProcess::TQProcess ( <a href="ntqobject.html">TQObject</a> * parent = 0, const char * name = 0 )
|
|
|
</h3>
|
|
|
Constructs a TQProcess object. The <em>parent</em> and <em>name</em> parameters
|
|
|
are passed to the <a href="ntqobject.html">TQObject</a> constructor.
|
|
|
<p> <p>See also <a href="#setArguments">setArguments</a>(), <a href="#addArgument">addArgument</a>(), and <a href="#start">start</a>().
|
|
|
|
|
|
<h3 class=fn><a name="TQProcess-2"></a>TQProcess::TQProcess ( const <a href="ntqstring.html">TQString</a> & arg0, <a href="ntqobject.html">TQObject</a> * parent = 0, const char * name = 0 )
|
|
|
</h3>
|
|
|
Constructs a TQProcess with <em>arg0</em> as the command to be executed.
|
|
|
The <em>parent</em> and <em>name</em> parameters are passed to the <a href="ntqobject.html">TQObject</a>
|
|
|
constructor.
|
|
|
<p> The process is not started. You must call <a href="#start">start</a>() or <a href="#launch">launch</a>() to
|
|
|
start the process.
|
|
|
<p> <p>See also <a href="#setArguments">setArguments</a>(), <a href="#addArgument">addArgument</a>(), and <a href="#start">start</a>().
|
|
|
|
|
|
<h3 class=fn><a name="TQProcess-3"></a>TQProcess::TQProcess ( const <a href="ntqstringlist.html">TQStringList</a> & args, <a href="ntqobject.html">TQObject</a> * parent = 0, const char * name = 0 )
|
|
|
</h3>
|
|
|
Constructs a TQProcess with <em>args</em> as the arguments of the
|
|
|
process. The first element in the list is the command to be
|
|
|
executed. The other elements in the list are the arguments to this
|
|
|
command. The <em>parent</em> and <em>name</em> parameters are passed to the
|
|
|
<a href="ntqobject.html">TQObject</a> constructor.
|
|
|
<p> The process is not started. You must call <a href="#start">start</a>() or <a href="#launch">launch</a>() to
|
|
|
start the process.
|
|
|
<p> <p>See also <a href="#setArguments">setArguments</a>(), <a href="#addArgument">addArgument</a>(), and <a href="#start">start</a>().
|
|
|
|
|
|
<h3 class=fn><a name="~TQProcess"></a>TQProcess::~TQProcess ()
|
|
|
</h3>
|
|
|
Destroys the instance.
|
|
|
<p> If the process is running, it is <b>not</b> terminated! The
|
|
|
standard input, standard output and standard error of the process
|
|
|
are closed.
|
|
|
<p> You can connect the <a href="ntqobject.html#destroyed">destroyed</a>() signal to the <a href="#kill">kill</a>() slot, if you
|
|
|
want the process to be terminated automatically when the instance
|
|
|
is destroyed.
|
|
|
<p> <p>See also <a href="#tryTerminate">tryTerminate</a>() and <a href="#kill">kill</a>().
|
|
|
|
|
|
<h3 class=fn>void <a name="addArgument"></a>TQProcess::addArgument ( const <a href="ntqstring.html">TQString</a> & arg )<tt> [virtual]</tt>
|
|
|
</h3>
|
|
|
Adds <em>arg</em> to the end of the list of arguments.
|
|
|
<p> The first element in the list of arguments is the command to be
|
|
|
executed; the following elements are the command's arguments.
|
|
|
<p> <p>See also <a href="#arguments">arguments</a>() and <a href="#setArguments">setArguments</a>().
|
|
|
|
|
|
<p>Example: <a href="ntqprocess.html#x2122">process/process.cpp</a>.
|
|
|
<h3 class=fn><a href="ntqstringlist.html">TQStringList</a> <a name="arguments"></a>TQProcess::arguments () const
|
|
|
</h3>
|
|
|
Returns the list of arguments that are set for the process.
|
|
|
Arguments can be specified with the constructor or with the
|
|
|
functions <a href="#setArguments">setArguments</a>() and <a href="#addArgument">addArgument</a>().
|
|
|
<p> Note that if you want to iterate over the list, you should iterate
|
|
|
over a copy, e.g.
|
|
|
<pre>
|
|
|
<a href="ntqstringlist.html">TQStringList</a> list = myProcess.arguments();
|
|
|
TQStringList::Iterator it = list.<a href="ntqvaluelist.html#begin">begin</a>();
|
|
|
while( it != list.<a href="ntqvaluelist.html#end">end</a>() ) {
|
|
|
myProcessing( *it );
|
|
|
++it;
|
|
|
}
|
|
|
</pre>
|
|
|
|
|
|
<p> <p>See also <a href="#setArguments">setArguments</a>() and <a href="#addArgument">addArgument</a>().
|
|
|
|
|
|
<h3 class=fn>bool <a name="canReadLineStderr"></a>TQProcess::canReadLineStderr () const
|
|
|
</h3>
|
|
|
Returns TRUE if it's possible to read an entire line of text from
|
|
|
standard error at this time; otherwise returns FALSE.
|
|
|
<p> <p>See also <a href="#readLineStderr">readLineStderr</a>() and <a href="#canReadLineStdout">canReadLineStdout</a>().
|
|
|
|
|
|
<h3 class=fn>bool <a name="canReadLineStdout"></a>TQProcess::canReadLineStdout () const
|
|
|
</h3>
|
|
|
Returns TRUE if it's possible to read an entire line of text from
|
|
|
standard output at this time; otherwise returns FALSE.
|
|
|
<p> <p>See also <a href="#readLineStdout">readLineStdout</a>() and <a href="#canReadLineStderr">canReadLineStderr</a>().
|
|
|
|
|
|
<h3 class=fn>void <a name="clearArguments"></a>TQProcess::clearArguments ()
|
|
|
</h3>
|
|
|
Clears the list of arguments that are set for the process.
|
|
|
<p> <p>See also <a href="#setArguments">setArguments</a>() and <a href="#addArgument">addArgument</a>().
|
|
|
|
|
|
<h3 class=fn>void <a name="closeStdin"></a>TQProcess::closeStdin ()<tt> [virtual slot]</tt>
|
|
|
</h3>
|
|
|
Closes the process's standard input.
|
|
|
<p> This function also deletes any pending data that has not been
|
|
|
written to standard input.
|
|
|
<p> <p>See also <a href="#wroteToStdin">wroteToStdin</a>().
|
|
|
|
|
|
<h3 class=fn>int <a name="communication"></a>TQProcess::communication () const
|
|
|
</h3>
|
|
|
Returns the communication required with the process, i.e. some
|
|
|
combination of the <a href="#Communication-enum">Communication</a> flags.
|
|
|
<p> <p>See also <a href="#setCommunication">setCommunication</a>().
|
|
|
|
|
|
<h3 class=fn>int <a name="exitStatus"></a>TQProcess::exitStatus () const
|
|
|
</h3>
|
|
|
Returns the exit status of the process or 0 if the process is
|
|
|
still running. This function returns immediately and does not wait
|
|
|
until the process is finished.
|
|
|
<p> If <a href="#normalExit">normalExit</a>() is FALSE (e.g. if the program was killed or
|
|
|
crashed), this function returns 0, so you should check the return
|
|
|
value of normalExit() before relying on this value.
|
|
|
<p> <p>See also <a href="#normalExit">normalExit</a>() and <a href="#processExited">processExited</a>().
|
|
|
|
|
|
<h3 class=fn>bool <a name="isRunning"></a>TQProcess::isRunning () const
|
|
|
</h3>
|
|
|
Returns TRUE if the process is running; otherwise returns FALSE.
|
|
|
<p> <p>See also <a href="#normalExit">normalExit</a>(), <a href="#exitStatus">exitStatus</a>(), and <a href="#processExited">processExited</a>().
|
|
|
|
|
|
<h3 class=fn>void <a name="kill"></a>TQProcess::kill () const<tt> [slot]</tt>
|
|
|
</h3>
|
|
|
Terminates the process. This is not a safe way to end a process
|
|
|
since the process will not be able to do any cleanup.
|
|
|
<a href="#tryTerminate">tryTerminate</a>() is safer, but processes can ignore a
|
|
|
tryTerminate().
|
|
|
<p> The nice way to end a process and to be sure that it is finished,
|
|
|
is to do something like this:
|
|
|
<pre>
|
|
|
process->tryTerminate();
|
|
|
TQTimer::<a href="ntqtimer.html#singleShot">singleShot</a>( 5000, process, SLOT( <a href="#kill">kill</a>() ) );
|
|
|
</pre>
|
|
|
|
|
|
<p> This tries to terminate the process the nice way. If the process
|
|
|
is still running after 5 seconds, it terminates the process the
|
|
|
hard way. The timeout should be chosen depending on the time the
|
|
|
process needs to do all its cleanup: use a higher value if the
|
|
|
process is likely to do a lot of computation or I/O on cleanup.
|
|
|
<p> The slot returns immediately: it does not wait until the process
|
|
|
has finished. When the process terminates, the <a href="#processExited">processExited</a>()
|
|
|
signal is emitted.
|
|
|
<p> <p>See also <a href="#tryTerminate">tryTerminate</a>() and <a href="#processExited">processExited</a>().
|
|
|
|
|
|
<h3 class=fn>bool <a name="launch"></a>TQProcess::launch ( const <a href="qbytearray.html">TQByteArray</a> & buf, <a href="ntqstringlist.html">TQStringList</a> * env = 0 )<tt> [virtual]</tt>
|
|
|
</h3>
|
|
|
Runs the process and writes the data <em>buf</em> to the process's
|
|
|
standard input. If all the data is written to standard input,
|
|
|
standard input is closed. The command is searched for in the path
|
|
|
for executable programs; you can also use an absolute path in the
|
|
|
command itself.
|
|
|
<p> If <em>env</em> is null, then the process is started with the same
|
|
|
environment as the starting process. If <em>env</em> is non-null, then
|
|
|
the values in the string list are interpreted as environment
|
|
|
setttings of the form <tt>key=value</tt> and the process is started
|
|
|
with these environment settings. For convenience, there is a small
|
|
|
exception to this rule under Unix: if <em>env</em> does not contain any
|
|
|
settings for the environment variable <tt>LD_LIBRARY_PATH</tt>, then
|
|
|
this variable is inherited from the starting process.
|
|
|
<p> Returns TRUE if the process could be started; otherwise returns
|
|
|
FALSE.
|
|
|
<p> Note that you should not use the slots <a href="#writeToStdin">writeToStdin</a>() and
|
|
|
<a href="#closeStdin">closeStdin</a>() on processes started with <a href="#launch">launch</a>(), since the result
|
|
|
is not well-defined. If you need these slots, use <a href="#start">start</a>() instead.
|
|
|
<p> The process may or may not read the <em>buf</em> data sent to its
|
|
|
standard input.
|
|
|
<p> You can call this function even when a process that was started
|
|
|
with this instance is still running. Be aware that if you do this
|
|
|
the standard input of the process that was launched first will be
|
|
|
closed, with any pending data being deleted, and the process will
|
|
|
be left to run out of your control. Similarly, if the process
|
|
|
could not be started the standard input will be closed and the
|
|
|
pending data deleted. (On operating systems that have zombie
|
|
|
processes, TQt will also wait() on the old process.)
|
|
|
<p> The object emits the signal <a href="#launchFinished">launchFinished</a>() when this function
|
|
|
call is finished. If the start was successful, this signal is
|
|
|
emitted after all the data has been written to standard input. If
|
|
|
the start failed, then this signal is emitted immediately.
|
|
|
<p> <p>See also <a href="#start">start</a>() and <a href="#launchFinished">launchFinished</a>().
|
|
|
|
|
|
<h3 class=fn>bool <a name="launch-2"></a>TQProcess::launch ( const <a href="ntqstring.html">TQString</a> & buf, <a href="ntqstringlist.html">TQStringList</a> * env = 0 )<tt> [virtual]</tt>
|
|
|
</h3>
|
|
|
This is an overloaded member function, provided for convenience. It behaves essentially like the above function.
|
|
|
<p> The data <em>buf</em> is written to standard input with <a href="#writeToStdin">writeToStdin</a>()
|
|
|
using the <a href="ntqstring.html#local8Bit">TQString::local8Bit</a>() representation of the strings.
|
|
|
|
|
|
<h3 class=fn>void <a name="launchFinished"></a>TQProcess::launchFinished ()<tt> [signal]</tt>
|
|
|
</h3>
|
|
|
|
|
|
<p> This signal is emitted when the process was started with <a href="#launch">launch</a>().
|
|
|
If the start was successful, this signal is emitted after all the
|
|
|
data has been written to standard input. If the start failed, then
|
|
|
this signal is emitted immediately.
|
|
|
<p> This signal is especially useful if you want to know when you can
|
|
|
safely delete the TQProcess object when you are not interested in
|
|
|
reading from standard output or standard error.
|
|
|
<p> <p>See also <a href="#launch">launch</a>() and <a href="ntqobject.html#deleteLater">TQObject::deleteLater</a>().
|
|
|
|
|
|
<h3 class=fn>bool <a name="normalExit"></a>TQProcess::normalExit () const
|
|
|
</h3>
|
|
|
Returns TRUE if the process has exited normally; otherwise returns
|
|
|
FALSE. This implies that this function returns FALSE if the
|
|
|
process is still running.
|
|
|
<p> <p>See also <a href="#isRunning">isRunning</a>(), <a href="#exitStatus">exitStatus</a>(), and <a href="#processExited">processExited</a>().
|
|
|
|
|
|
<h3 class=fn>void <a name="processExited"></a>TQProcess::processExited ()<tt> [signal]</tt>
|
|
|
</h3>
|
|
|
|
|
|
<p> This signal is emitted when the process has exited.
|
|
|
<p> <p>See also <a href="#isRunning">isRunning</a>(), <a href="#normalExit">normalExit</a>(), <a href="#exitStatus">exitStatus</a>(), <a href="#start">start</a>(), and <a href="#launch">launch</a>().
|
|
|
|
|
|
<p>Example: <a href="process-example.html#x98">process/process.cpp</a>.
|
|
|
<h3 class=fn>PID <a name="processIdentifier"></a>TQProcess::processIdentifier ()
|
|
|
</h3>
|
|
|
Returns platform dependent information about the process. This can
|
|
|
be used together with platform specific system calls.
|
|
|
<p> Under Unix the return value is the PID of the process, or -1 if no
|
|
|
process belongs to this object.
|
|
|
<p> Under Windows it is a pointer to the <tt>PROCESS_INFORMATION</tt>
|
|
|
struct, or 0 if no process is belongs to this object.
|
|
|
<p> Use of this function's return value is likely to be non-portable.
|
|
|
|
|
|
<h3 class=fn><a href="ntqstring.html">TQString</a> <a name="readLineStderr"></a>TQProcess::readLineStderr ()<tt> [virtual]</tt>
|
|
|
</h3>
|
|
|
Reads a line of text from standard error, excluding any trailing
|
|
|
newline or carriage return characters and returns it. Returns
|
|
|
<a href="ntqstring.html#TQString-null">TQString::null</a> if <a href="#canReadLineStderr">canReadLineStderr</a>() returns FALSE.
|
|
|
<p> By default, the text is interpreted to be in Latin-1 encoding. If you need
|
|
|
other codecs, you can set a different codec with
|
|
|
<a href="ntqtextcodec.html#setCodecForCStrings">TQTextCodec::setCodecForCStrings</a>().
|
|
|
<p> <p>See also <a href="#canReadLineStderr">canReadLineStderr</a>(), <a href="#readyReadStderr">readyReadStderr</a>(), <a href="#readStderr">readStderr</a>(), and <a href="#readLineStdout">readLineStdout</a>().
|
|
|
|
|
|
<h3 class=fn><a href="ntqstring.html">TQString</a> <a name="readLineStdout"></a>TQProcess::readLineStdout ()<tt> [virtual]</tt>
|
|
|
</h3>
|
|
|
Reads a line of text from standard output, excluding any trailing
|
|
|
newline or carriage return characters, and returns it. Returns
|
|
|
<a href="ntqstring.html#TQString-null">TQString::null</a> if <a href="#canReadLineStdout">canReadLineStdout</a>() returns FALSE.
|
|
|
<p> By default, the text is interpreted to be in Latin-1 encoding. If you need
|
|
|
other codecs, you can set a different codec with
|
|
|
<a href="ntqtextcodec.html#setCodecForCStrings">TQTextCodec::setCodecForCStrings</a>().
|
|
|
<p> <p>See also <a href="#canReadLineStdout">canReadLineStdout</a>(), <a href="#readyReadStdout">readyReadStdout</a>(), <a href="#readStdout">readStdout</a>(), and <a href="#readLineStderr">readLineStderr</a>().
|
|
|
|
|
|
<h3 class=fn><a href="qbytearray.html">TQByteArray</a> <a name="readStderr"></a>TQProcess::readStderr ()<tt> [virtual]</tt>
|
|
|
</h3>
|
|
|
Reads the data that the process has written to standard error.
|
|
|
When new data is written to standard error, the class emits the
|
|
|
signal <a href="#readyReadStderr">readyReadStderr</a>().
|
|
|
<p> If there is no data to read, this function returns a <a href="qbytearray.html">TQByteArray</a> of
|
|
|
size 0: it does not wait until there is something to read.
|
|
|
<p> <p>See also <a href="#readyReadStderr">readyReadStderr</a>(), <a href="#readLineStderr">readLineStderr</a>(), <a href="#readStdout">readStdout</a>(), and <a href="#writeToStdin">writeToStdin</a>().
|
|
|
|
|
|
<h3 class=fn><a href="qbytearray.html">TQByteArray</a> <a name="readStdout"></a>TQProcess::readStdout ()<tt> [virtual]</tt>
|
|
|
</h3>
|
|
|
Reads the data that the process has written to standard output.
|
|
|
When new data is written to standard output, the class emits the
|
|
|
signal <a href="#readyReadStdout">readyReadStdout</a>().
|
|
|
<p> If there is no data to read, this function returns a <a href="qbytearray.html">TQByteArray</a> of
|
|
|
size 0: it does not wait until there is something to read.
|
|
|
<p> <p>See also <a href="#readyReadStdout">readyReadStdout</a>(), <a href="#readLineStdout">readLineStdout</a>(), <a href="#readStderr">readStderr</a>(), and <a href="#writeToStdin">writeToStdin</a>().
|
|
|
|
|
|
<p>Example: <a href="process-example.html#x99">process/process.cpp</a>.
|
|
|
<h3 class=fn>void <a name="readyReadStderr"></a>TQProcess::readyReadStderr ()<tt> [signal]</tt>
|
|
|
</h3>
|
|
|
|
|
|
<p> This signal is emitted when the process has written data to
|
|
|
standard error. You can read the data with <a href="#readStderr">readStderr</a>().
|
|
|
<p> Note that this signal is only emitted when there is new data and
|
|
|
not when there is old, but unread data. In the slot connected to
|
|
|
this signal, you should always read everything that is available
|
|
|
at that moment to make sure that you don't lose any data.
|
|
|
<p> <p>See also <a href="#readStderr">readStderr</a>(), <a href="#readLineStderr">readLineStderr</a>(), and <a href="#readyReadStdout">readyReadStdout</a>().
|
|
|
|
|
|
<h3 class=fn>void <a name="readyReadStdout"></a>TQProcess::readyReadStdout ()<tt> [signal]</tt>
|
|
|
</h3>
|
|
|
|
|
|
<p> This signal is emitted when the process has written data to
|
|
|
standard output. You can read the data with <a href="#readStdout">readStdout</a>().
|
|
|
<p> Note that this signal is only emitted when there is new data and
|
|
|
not when there is old, but unread data. In the slot connected to
|
|
|
this signal, you should always read everything that is available
|
|
|
at that moment to make sure that you don't lose any data.
|
|
|
<p> <p>See also <a href="#readStdout">readStdout</a>(), <a href="#readLineStdout">readLineStdout</a>(), and <a href="#readyReadStderr">readyReadStderr</a>().
|
|
|
|
|
|
<p>Example: <a href="ntqprocess.html#x2123">process/process.cpp</a>.
|
|
|
<h3 class=fn>void <a name="setArguments"></a>TQProcess::setArguments ( const <a href="ntqstringlist.html">TQStringList</a> & args )<tt> [virtual]</tt>
|
|
|
</h3>
|
|
|
Sets <em>args</em> as the arguments for the process. The first element
|
|
|
in the list is the command to be executed. The other elements in
|
|
|
the list are the arguments to the command. Any previous arguments
|
|
|
are deleted.
|
|
|
<p> TQProcess does not perform argument substitutions; for example, if you
|
|
|
specify "*" or "$DISPLAY", these values are passed to the process
|
|
|
literally. If you want to have the same behavior as the shell
|
|
|
provides, you must do the substitutions yourself; i.e. instead of
|
|
|
specifying a "*" you must specify the list of all the filenames in
|
|
|
the current directory, and instead of "$DISPLAY" you must specify
|
|
|
the value of the environment variable <tt>DISPLAY</tt>.
|
|
|
<p> Note for Windows users. The standard Windows shells, e.g. <tt>command.com</tt> and <tt>cmd.exe</tt>, do not perform file globbing, i.e.
|
|
|
they do not convert a "*" on the command line into a list of files
|
|
|
in the current directory. For this reason most Windows
|
|
|
applications implement their own file globbing, and as a result of
|
|
|
this, specifying an argument of "*" for a Windows application is
|
|
|
likely to result in the application performing a file glob and
|
|
|
ending up with a list of filenames.
|
|
|
<p> <p>See also <a href="#arguments">arguments</a>() and <a href="#addArgument">addArgument</a>().
|
|
|
|
|
|
<h3 class=fn>void <a name="setCommunication"></a>TQProcess::setCommunication ( int commFlags )
|
|
|
</h3>
|
|
|
Sets <em>commFlags</em> as the communication required with the process.
|
|
|
<p> <em>commFlags</em> is a bitwise OR of the flags defined by the <a href="#Communication-enum">Communication</a> enum.
|
|
|
<p> The default is <tt>Stdin|Stdout|Stderr</tt>.
|
|
|
<p> <p>See also <a href="#communication">communication</a>().
|
|
|
|
|
|
<h3 class=fn>void <a name="setWorkingDirectory"></a>TQProcess::setWorkingDirectory ( const <a href="ntqdir.html">TQDir</a> & dir )<tt> [virtual]</tt>
|
|
|
</h3>
|
|
|
Sets <em>dir</em> as the working directory for processes. This does not
|
|
|
affect running processes; only processes that are started
|
|
|
afterwards are affected.
|
|
|
<p> Setting the working directory is especially useful for processes
|
|
|
that try to access files with relative paths.
|
|
|
<p> <p>See also <a href="#workingDirectory">workingDirectory</a>() and <a href="#start">start</a>().
|
|
|
|
|
|
<h3 class=fn>bool <a name="start"></a>TQProcess::start ( <a href="ntqstringlist.html">TQStringList</a> * env = 0 )<tt> [virtual]</tt>
|
|
|
</h3>
|
|
|
Tries to run a process for the command and arguments that were
|
|
|
specified with <a href="#setArguments">setArguments</a>(), <a href="#addArgument">addArgument</a>() or that were
|
|
|
specified in the constructor. The command is searched for in the
|
|
|
path for executable programs; you can also use an absolute path in
|
|
|
the command itself.
|
|
|
<p> If <em>env</em> is null, then the process is started with the same
|
|
|
environment as the starting process. If <em>env</em> is non-null, then
|
|
|
the values in the stringlist are interpreted as environment
|
|
|
setttings of the form <tt>key=value</tt> and the process is started in
|
|
|
these environment settings. For convenience, there is a small
|
|
|
exception to this rule: under Unix, if <em>env</em> does not contain any
|
|
|
settings for the environment variable <tt>LD_LIBRARY_PATH</tt>, then
|
|
|
this variable is inherited from the starting process; under
|
|
|
Windows the same applies for the environment variable <tt>PATH</tt>.
|
|
|
<p> Returns TRUE if the process could be started; otherwise returns
|
|
|
FALSE.
|
|
|
<p> You can write data to the process's standard input with
|
|
|
<a href="#writeToStdin">writeToStdin</a>(). You can close standard input with <a href="#closeStdin">closeStdin</a>() and
|
|
|
you can terminate the process with <a href="#tryTerminate">tryTerminate</a>(), or with <a href="#kill">kill</a>().
|
|
|
<p> You can call this function even if you've used this instance to
|
|
|
create a another process which is still running. In such cases,
|
|
|
TQProcess closes the old process's standard input and deletes
|
|
|
pending data, i.e., you lose all control over the old process, but
|
|
|
the old process is not terminated. This applies also if the
|
|
|
process could not be started. (On operating systems that have
|
|
|
zombie processes, TQt will also wait() on the old process.)
|
|
|
<p> <p>See also <a href="#launch">launch</a>() and <a href="#closeStdin">closeStdin</a>().
|
|
|
|
|
|
<p>Example: <a href="ntqprocess.html#x2124">process/process.cpp</a>.
|
|
|
<h3 class=fn>void <a name="tryTerminate"></a>TQProcess::tryTerminate () const<tt> [slot]</tt>
|
|
|
</h3>
|
|
|
Asks the process to terminate. Processes can ignore this if they
|
|
|
wish. If you want to be certain that the process really
|
|
|
terminates, you can use <a href="#kill">kill</a>() instead.
|
|
|
<p> The slot returns immediately: it does not wait until the process
|
|
|
has finished. When the process terminates, the <a href="#processExited">processExited</a>()
|
|
|
signal is emitted.
|
|
|
<p> <p>See also <a href="#kill">kill</a>() and <a href="#processExited">processExited</a>().
|
|
|
|
|
|
<h3 class=fn><a href="ntqdir.html">TQDir</a> <a name="workingDirectory"></a>TQProcess::workingDirectory () const
|
|
|
</h3>
|
|
|
Returns the working directory that was set with
|
|
|
<a href="#setWorkingDirectory">setWorkingDirectory</a>(), or the current directory if none has been
|
|
|
explicitly set.
|
|
|
<p> <p>See also <a href="#setWorkingDirectory">setWorkingDirectory</a>() and <a href="ntqdir.html#current">TQDir::current</a>().
|
|
|
|
|
|
<h3 class=fn>void <a name="writeToStdin"></a>TQProcess::writeToStdin ( const <a href="qbytearray.html">TQByteArray</a> & buf )<tt> [virtual slot]</tt>
|
|
|
</h3>
|
|
|
Writes the data <em>buf</em> to the process's standard input. The
|
|
|
process may or may not read this data.
|
|
|
<p> This function always returns immediately. The data you
|
|
|
pass to <a href="#writeToStdin">writeToStdin</a>() is copied into an internal memory buffer in
|
|
|
TQProcess, and when control goes back to the event loop, TQProcess will
|
|
|
starting transferring data from this buffer to the running process. <20>
|
|
|
Sometimes the data will be transferred in several payloads, depending on
|
|
|
how much data is read at a time by the process itself. When TQProcess has
|
|
|
transferred all the data from its memory buffer to the running process, it
|
|
|
emits <a href="#wroteToStdin">wroteToStdin</a>().
|
|
|
<p> Note that some operating systems use a buffer to transfer
|
|
|
the data. As a result, wroteToStdin() may be emitted before the
|
|
|
running process has actually read all the data.
|
|
|
<p> <p>See also <a href="#wroteToStdin">wroteToStdin</a>(), <a href="#closeStdin">closeStdin</a>(), <a href="#readStdout">readStdout</a>(), and <a href="#readStderr">readStderr</a>().
|
|
|
|
|
|
<h3 class=fn>void <a name="writeToStdin-2"></a>TQProcess::writeToStdin ( const <a href="ntqstring.html">TQString</a> & buf )<tt> [virtual slot]</tt>
|
|
|
</h3>
|
|
|
This is an overloaded member function, provided for convenience. It behaves essentially like the above function.
|
|
|
<p> The string <em>buf</em> is handled as text using the
|
|
|
<a href="ntqstring.html#local8Bit">TQString::local8Bit</a>() representation.
|
|
|
|
|
|
<h3 class=fn>void <a name="wroteToStdin"></a>TQProcess::wroteToStdin ()<tt> [signal]</tt>
|
|
|
</h3>
|
|
|
|
|
|
<p> This signal is emitted if the data sent to standard input (via
|
|
|
<a href="#writeToStdin">writeToStdin</a>()) was actually written to the process. This does not
|
|
|
imply that the process really read the data, since this class only
|
|
|
detects when it was able to write the data to the operating
|
|
|
system. But it is now safe to close standard input without losing
|
|
|
pending data.
|
|
|
<p> <p>See also <a href="#writeToStdin">writeToStdin</a>() and <a href="#closeStdin">closeStdin</a>().
|
|
|
|
|
|
<!-- eof -->
|
|
|
<hr><p>
|
|
|
This file is part of the <a href="index.html">TQt toolkit</a>.
|
|
|
Copyright © 1995-2007
|
|
|
<a href="http://www.trolltech.com/">Trolltech</a>. All Rights Reserved.<p><address><hr><div align=center>
|
|
|
<table width=100% cellspacing=0 border=0><tr>
|
|
|
<td>Copyright © 2007
|
|
|
<a href="troll.html">Trolltech</a><td align=center><a href="trademarks.html">Trademarks</a>
|
|
|
<td align=right><div align=right>TQt 3.3.8</div>
|
|
|
</table></div></address></body>
|
|
|
</html>
|
