|  | Home · Overviews · Examples |

# QProcess Class Reference
[com.trolltech.qt.core module]

The `QProcess` class is used to start external programs and to communicate with them. More...

Inherits `QIODevice`.

## Detailed Description

The `QProcess` class is used to start external programs and to communicate with them.

To start a process, pass the name and command line arguments of the program you want to run as arguments to `start`. For example:

            QObject *parent;
            ...
            QString program = "./path/to/Qt/examples/widgets/analogclock";
            QStringList arguments;
            arguments << "-style" << "motif";

            QProcess *myProcess = new QProcess(parent);
            myProcess->start(program, arguments);

`QProcess` then enters the Starting state, and when the program has started, `QProcess` enters the Running state and emits `started`.

`QProcess` allows you to treat a process as a sequential I/O device. You can write to and read from the process just as you would access a network connection using `QTcpSocket`. You can then write to the process's standard input by calling `write`, and read the standard output by calling `read`, `readLine`, and getChar(). Because it inherits `QIODevice`, `QProcess` can also be used as an input source for `QXmlReader`, or for generating data to be uploaded using `QFtp`.

When the process exits, `QProcess` reenters the `NotRunning` state (the initial state), and emits `finished`.

The `finished` signal provides the exit code and exit status of the process as arguments, and you can also call `exitCode` to obtain the exit code of the last process that finished, and `exitStatus` to obtain its exit status. If an error occurs at any point in time, `QProcess` will emit the `error` signal. You can also call `error` to find the type of error that occurred last, and `state` to find the current process state.

Processes have two predefined output channels: The standard output channel (`stdout`) supplies regular console output, and the standard error channel (`stderr`) usually supplies the errors that are printed by the process. These channels represent two separate streams of data. You can toggle between them by calling `setReadChannel`. `QProcess` emits `readyRead` when data is available on the current read channel. It also emits `readyReadStandardOutput` when new standard output data is available, and when new standard error data is available, `readyReadStandardError` is emitted. Instead of calling `read`, `readLine`, or getChar(), you can explicitly read all data from either of the two channels by calling `readAllStandardOutput` or `readAllStandardError`.

The terminology for the channels can be misleading. Be aware that the process's output channels correspond to `QProcess`'s read channels, whereas the process's input channels correspond to `QProcess`'s write channels. This is because what we read using `QProcess` is the process's output, and what we write becomes the process's input.

`QProcess` can merge the two output channels, so that standard output and standard error data from the running process both use the standard output channel. Call `setProcessChannelMode` with `MergedChannels` before starting the process to activative this feature. You also have the option of forwarding the output of the running process to the calling, main process, by passing `ForwardedChannels` as the argument.

Certain processes need special environment settings in order to operate. You can set environment variables for your process by calling `setEnvironment`. To set a working directory, call `setWorkingDirectory`. By default, processes are run in the current working directory of the calling process.

`QProcess` provides a set of functions which allow it to be used without an event loop, by suspending the calling thread until certain signals are emitted:

- `waitForStarted` blocks until the process has started.
- `waitForReadyRead` blocks until new data is available for reading on the current read channel.
- `waitForBytesWritten` blocks until one payload of data has been written to the process.
- `waitForFinished` blocks until the process has finished.

Calling these functions from the main thread (the thread that calls QApplication::exec()) may cause your user interface to freeze.

The following example runs `gzip` to compress the string "Qt rocks!", without an event loop:

            QProcess gzip;
            gzip.start("gzip", QStringList() << "-c");
            if (!gzip.waitForStarted())
                return false;

            gzip.write("Qt rocks!");
            gzip.closeWriteChannel();

            if (!gzip.waitForFinished())
                return false;

            QByteArray result = gzip.readAll();

See also `QBuffer`, `QFile`, and `QTcpSocket`.