diff options
Diffstat (limited to 'doc/html/ntqprocess.html')
| -rw-r--r-- | doc/html/ntqprocess.html | 633 |
1 files changed, 633 insertions, 0 deletions
diff --git a/doc/html/ntqprocess.html b/doc/html/ntqprocess.html new file mode 100644 index 00000000..22afc994 --- /dev/null +++ b/doc/html/ntqprocess.html @@ -0,0 +1,633 @@ +<!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. +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> |