From ea318d1431c89e647598c510c4245c6571aa5f46 Mon Sep 17 00:00:00 2001 From: Timothy Pearson Date: Thu, 26 Jan 2012 23:32:43 -0600 Subject: Update to latest tqt3 automated conversion --- doc/html/ntqprocess.html | 633 +++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 633 insertions(+) create mode 100644 doc/html/ntqprocess.html (limited to 'doc/html/ntqprocess.html') diff --git a/doc/html/ntqprocess.html b/doc/html/ntqprocess.html new file mode 100644 index 000000000..22afc994b --- /dev/null +++ b/doc/html/ntqprocess.html @@ -0,0 +1,633 @@ + + + + + +TQProcess Class + + + + + + + +
+ +Home + | +All Classes + | +Main Classes + | +Annotated + | +Grouped Classes + | +Functions +

TQProcess Class Reference

+ +

The TQProcess class is used to start external programs and +to communicate with them. +More... +

#include <ntqprocess.h> +

Inherits TQObject. +

List of all member functions. +

Public Members

+ +

Public Slots

+ +

Signals

+ +

Detailed Description

+ + +

The TQProcess class is used to start external programs and +to communicate with them. +

+ + +

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 setArguments() or addArgument(). The program's +working directory can be set with setWorkingDirectory(). If you +need to set up environment variables pass them to the start() or +launch() functions (see below). The processExited() signal is +emitted if the program exits. The program's exit status is +available from exitStatus(), although you could simply call +normalExit() to see if the program terminated normally. +

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. +

If you use start() you can write to the program's standard input +using writeToStdin() and you can close the standard input with +closeStdin(). The wroteToStdin() signal is emitted if the data +sent to standard input has been written. You can read from the +program's standard output using readStdout() or readLineStdout(). +These functions return an empty TQByteArray if there is no data to +read. The readyReadStdout() 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. readStderr(), readLineStderr() and readyReadStderr(). +

If you use one of the launch() 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 not use writeToStdin() or +closeStdin() if you use launch(). If you need to send data to the +program's standard input after it has started running use start() +instead of launch(). +

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. +

You can test to see if a program is running with isRunning(). The +program's process identifier is available from +processIdentifier(). If you want to terminate a running program +use tryTerminate(), but note that the program may ignore this. If +you really want to terminate the program, without it having any +chance to clean up, you can use kill(). +

As an example, suppose we want to start the uic command (a TQt +command line tool used with TQt Designer) and perform some +operations on the output (the uic 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 i18n". On the command line we would write: +

+    uic -tr i18n small_dialog.ui
+
+ +

+ +

A code snippet for this with the TQProcess class might look like +this: +

    UicManager::UicManager()
+    {
+
        proc = new TQProcess( this );
+
        proc->addArgument( "uic" );
+        proc->addArgument( "-tr" );
+        proc->addArgument( "i18n" );
+        proc->addArgument( "small_dialog.ui" );
+
+        connect( proc, SIGNAL(readyReadStdout()),
+                this, SLOT(readFromStdout()) );
+
        if ( !proc->start() ) {
+            // error handling
+
        }
+    }
+
+

    void UicManager::readFromStdout()
+    {
+        // Read and process the data.
+        // Bear in mind that the data might be output in chunks.
+
    }
+
+

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 addArgument() or setArguments(). +

The readyReadStdout() signal is emitted when there is new data on +standard output. This happens asynchronously: you don't know if +more data will arrive later. +

In the above example you could connect the processExited() 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. +

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 readyReadStderr() signals and read the data +as soon as it becomes available. +

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 not replaced by all the files, a '$HOME' is also +passed literally and is not replaced by the environment variable HOME +and the special characters for IO redirection ('>', '|', etc.) are also +passed literally and do not have the special meaning as they have in a +shell. +

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). +

Notes for Windows users +

+

Some Windows commands, for example, dir, 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 (cmd.exe on some Windows systems), and ask +the interpreter to execute the desired command. +

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. +

See also TQSocket, Input/Output and Networking, and Miscellaneous Classes. + +

Member Type Documentation

+

TQProcess::Communication

+ +

This enum type defines the communication channels connected to the +process. +

See also setCommunication() and communication(). + +

Member Function Documentation

+

TQProcess::TQProcess ( TQObject * parent = 0, const char * name = 0 ) +

+Constructs a TQProcess object. The parent and name parameters +are passed to the TQObject constructor. +

See also setArguments(), addArgument(), and start(). + +

TQProcess::TQProcess ( const TQString & arg0, TQObject * parent = 0, const char * name = 0 ) +

+Constructs a TQProcess with arg0 as the command to be executed. +The parent and name parameters are passed to the TQObject +constructor. +

The process is not started. You must call start() or launch() to +start the process. +

See also setArguments(), addArgument(), and start(). + +

TQProcess::TQProcess ( const TQStringList & args, TQObject * parent = 0, const char * name = 0 ) +

+Constructs a TQProcess with args 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 parent and name parameters are passed to the +TQObject constructor. +

The process is not started. You must call start() or launch() to +start the process. +

See also setArguments(), addArgument(), and start(). + +

TQProcess::~TQProcess () +

+Destroys the instance. +

If the process is running, it is not terminated! The +standard input, standard output and standard error of the process +are closed. +

You can connect the destroyed() signal to the kill() slot, if you +want the process to be terminated automatically when the instance +is destroyed. +

See also tryTerminate() and kill(). + +

void TQProcess::addArgument ( const TQString & arg ) [virtual] +

+Adds arg to the end of the list of arguments. +

The first element in the list of arguments is the command to be +executed; the following elements are the command's arguments. +

See also arguments() and setArguments(). + +

Example: process/process.cpp. +

TQStringList TQProcess::arguments () const +

+Returns the list of arguments that are set for the process. +Arguments can be specified with the constructor or with the +functions setArguments() and addArgument(). +

Note that if you want to iterate over the list, you should iterate +over a copy, e.g. +

+    TQStringList list = myProcess.arguments();
+    TQStringList::Iterator it = list.begin();
+    while( it != list.end() ) {
+        myProcessing( *it );
+        ++it;
+    }
+
+ +

See also setArguments() and addArgument(). + +

bool TQProcess::canReadLineStderr () const +

+Returns TRUE if it's possible to read an entire line of text from +standard error at this time; otherwise returns FALSE. +

See also readLineStderr() and canReadLineStdout(). + +

bool TQProcess::canReadLineStdout () const +

+Returns TRUE if it's possible to read an entire line of text from +standard output at this time; otherwise returns FALSE. +

See also readLineStdout() and canReadLineStderr(). + +

void TQProcess::clearArguments () +

+Clears the list of arguments that are set for the process. +

See also setArguments() and addArgument(). + +

void TQProcess::closeStdin () [virtual slot] +

+Closes the process's standard input. +

This function also deletes any pending data that has not been +written to standard input. +

See also wroteToStdin(). + +

int TQProcess::communication () const +

+Returns the communication required with the process, i.e. some +combination of the Communication flags. +

See also setCommunication(). + +

int TQProcess::exitStatus () const +

+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. +

If normalExit() 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. +

See also normalExit() and processExited(). + +

bool TQProcess::isRunning () const +

+Returns TRUE if the process is running; otherwise returns FALSE. +

See also normalExit(), exitStatus(), and processExited(). + +

void TQProcess::kill () const [slot] +

+Terminates the process. This is not a safe way to end a process +since the process will not be able to do any cleanup. +tryTerminate() is safer, but processes can ignore a +tryTerminate(). +

The nice way to end a process and to be sure that it is finished, +is to do something like this: +

+        process->tryTerminate();
+        TQTimer::singleShot( 5000, process, SLOT( kill() ) );
+
+ +

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. +

The slot returns immediately: it does not wait until the process +has finished. When the process terminates, the processExited() +signal is emitted. +

See also tryTerminate() and processExited(). + +

bool TQProcess::launch ( const TQByteArray & buf, TQStringList * env = 0 ) [virtual] +

+Runs the process and writes the data buf 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. +

If env is null, then the process is started with the same +environment as the starting process. If env is non-null, then +the values in the string list are interpreted as environment +setttings of the form key=value and the process is started +with these environment settings. For convenience, there is a small +exception to this rule under Unix: if env does not contain any +settings for the environment variable LD_LIBRARY_PATH, then +this variable is inherited from the starting process. +

Returns TRUE if the process could be started; otherwise returns +FALSE. +

Note that you should not use the slots writeToStdin() and +closeStdin() on processes started with launch(), since the result +is not well-defined. If you need these slots, use start() instead. +

The process may or may not read the buf data sent to its +standard input. +

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.) +

The object emits the signal launchFinished() 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. +

See also start() and launchFinished(). + +

bool TQProcess::launch ( const TQString & buf, TQStringList * env = 0 ) [virtual] +

+This is an overloaded member function, provided for convenience. It behaves essentially like the above function. +

The data buf is written to standard input with writeToStdin() +using the TQString::local8Bit() representation of the strings. + +

void TQProcess::launchFinished () [signal] +

+ +

This signal is emitted when the process was started with launch(). +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. +

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. +

See also launch() and TQObject::deleteLater(). + +

bool TQProcess::normalExit () const +

+Returns TRUE if the process has exited normally; otherwise returns +FALSE. This implies that this function returns FALSE if the +process is still running. +

See also isRunning(), exitStatus(), and processExited(). + +

void TQProcess::processExited () [signal] +

+ +

This signal is emitted when the process has exited. +

See also isRunning(), normalExit(), exitStatus(), start(), and launch(). + +

Example: process/process.cpp. +

PID TQProcess::processIdentifier () +

+Returns platform dependent information about the process. This can +be used together with platform specific system calls. +

Under Unix the return value is the PID of the process, or -1 if no +process belongs to this object. +

Under Windows it is a pointer to the PROCESS_INFORMATION +struct, or 0 if no process is belongs to this object. +

Use of this function's return value is likely to be non-portable. + +

TQString TQProcess::readLineStderr () [virtual] +

+Reads a line of text from standard error, excluding any trailing +newline or carriage return characters and returns it. Returns +TQString::null if canReadLineStderr() returns FALSE. +

By default, the text is interpreted to be in Latin-1 encoding. If you need +other codecs, you can set a different codec with +TQTextCodec::setCodecForCStrings(). +

See also canReadLineStderr(), readyReadStderr(), readStderr(), and readLineStdout(). + +

TQString TQProcess::readLineStdout () [virtual] +

+Reads a line of text from standard output, excluding any trailing +newline or carriage return characters, and returns it. Returns +TQString::null if canReadLineStdout() returns FALSE. +

By default, the text is interpreted to be in Latin-1 encoding. If you need +other codecs, you can set a different codec with +TQTextCodec::setCodecForCStrings(). +

See also canReadLineStdout(), readyReadStdout(), readStdout(), and readLineStderr(). + +

TQByteArray TQProcess::readStderr () [virtual] +

+Reads the data that the process has written to standard error. +When new data is written to standard error, the class emits the +signal readyReadStderr(). +

If there is no data to read, this function returns a TQByteArray of +size 0: it does not wait until there is something to read. +

See also readyReadStderr(), readLineStderr(), readStdout(), and writeToStdin(). + +

TQByteArray TQProcess::readStdout () [virtual] +

+Reads the data that the process has written to standard output. +When new data is written to standard output, the class emits the +signal readyReadStdout(). +

If there is no data to read, this function returns a TQByteArray of +size 0: it does not wait until there is something to read. +

See also readyReadStdout(), readLineStdout(), readStderr(), and writeToStdin(). + +

Example: process/process.cpp. +

void TQProcess::readyReadStderr () [signal] +

+ +

This signal is emitted when the process has written data to +standard error. You can read the data with readStderr(). +

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. +

See also readStderr(), readLineStderr(), and readyReadStdout(). + +

void TQProcess::readyReadStdout () [signal] +

+ +

This signal is emitted when the process has written data to +standard output. You can read the data with readStdout(). +

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. +

See also readStdout(), readLineStdout(), and readyReadStderr(). + +

Example: process/process.cpp. +

void TQProcess::setArguments ( const TQStringList & args ) [virtual] +

+Sets args 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. +

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 DISPLAY. +

Note for Windows users. The standard Windows shells, e.g. command.com and cmd.exe, 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. +

See also arguments() and addArgument(). + +

void TQProcess::setCommunication ( int commFlags ) +

+Sets commFlags as the communication required with the process. +

commFlags is a bitwise OR of the flags defined by the Communication enum. +

The default is Stdin|Stdout|Stderr. +

See also communication(). + +

void TQProcess::setWorkingDirectory ( const TQDir & dir ) [virtual] +

+Sets dir as the working directory for processes. This does not +affect running processes; only processes that are started +afterwards are affected. +

Setting the working directory is especially useful for processes +that try to access files with relative paths. +

See also workingDirectory() and start(). + +

bool TQProcess::start ( TQStringList * env = 0 ) [virtual] +

+Tries to run a process for the command and arguments that were +specified with setArguments(), addArgument() 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. +

If env is null, then the process is started with the same +environment as the starting process. If env is non-null, then +the values in the stringlist are interpreted as environment +setttings of the form key=value and the process is started in +these environment settings. For convenience, there is a small +exception to this rule: under Unix, if env does not contain any +settings for the environment variable LD_LIBRARY_PATH, then +this variable is inherited from the starting process; under +Windows the same applies for the environment variable PATH. +

Returns TRUE if the process could be started; otherwise returns +FALSE. +

You can write data to the process's standard input with +writeToStdin(). You can close standard input with closeStdin() and +you can terminate the process with tryTerminate(), or with kill(). +

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.) +

See also launch() and closeStdin(). + +

Example: process/process.cpp. +

void TQProcess::tryTerminate () const [slot] +

+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 kill() instead. +

The slot returns immediately: it does not wait until the process +has finished. When the process terminates, the processExited() +signal is emitted. +

See also kill() and processExited(). + +

TQDir TQProcess::workingDirectory () const +

+Returns the working directory that was set with +setWorkingDirectory(), or the current directory if none has been +explicitly set. +

See also setWorkingDirectory() and TQDir::current(). + +

void TQProcess::writeToStdin ( const TQByteArray & buf ) [virtual slot] +

+Writes the data buf to the process's standard input. The +process may or may not read this data. +

This function always returns immediately. The data you +pass to writeToStdin() 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 wroteToStdin(). +

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. +

See also wroteToStdin(), closeStdin(), readStdout(), and readStderr(). + +

void TQProcess::writeToStdin ( const TQString & buf ) [virtual slot] +

+This is an overloaded member function, provided for convenience. It behaves essentially like the above function. +

The string buf is handled as text using the +TQString::local8Bit() representation. + +

void TQProcess::wroteToStdin () [signal] +

+ +

This signal is emitted if the data sent to standard input (via +writeToStdin()) 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. +

See also writeToStdin() and closeStdin(). + + +

+This file is part of the TQt toolkit. +Copyright © 1995-2007 +Trolltech. All Rights Reserved.

+ +
Copyright © 2007 +TrolltechTrademarks +
TQt 3.3.8
+
+ -- cgit v1.2.1