Home | All Classes | Main Classes | Annotated | Grouped Classes | Functions |

# QProcess Class Reference

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

    #include <QProcess>

Inherits QIODevice.

- List of all members, including inherited members

### Public Types

- enum ProcessChannel { StandardOutput, StandardError }
- enum ProcessError { FailedToStart, Crashed, Timedout, ReadError, WriteError, UnknownError }
- enum ProcessState { NotRunning, Starting, Running, Finishing }

### Writable Properties

- 1 writable property inherited from QObject

### Public Functions

- QProcess ( QObject * parent = 0 )
- virtual ~QProcess ()
- virtual void close ()
- QStringList environment () const
- int exitCode () const
- ProcessChannel inputChannel () const
- Q_PID pid () const
- QProcess::ProcessError processError () const
- QProcess::ProcessState processState () const
- QByteArray readAllStandardError ()
- QByteArray readAllStandardOutput ()
- void setEnvironment ( const QStringList & environment )
- void setInputChannel ( ProcessChannel channel )
- void setWorkingDirectory ( const QString & dir )
- void start ( const QString & program, const QStringList & arguments = QStringList() )
- void terminate ()
- bool waitForFinished ( int msecs = 30000 )
- bool waitForStarted ( int msecs = 30000 )
- QString workingDirectory () const

- 29 public functions inherited from QIODevice
- 26 public functions inherited from QObject

### Public Slots

- 1 public slot inherited from QObject

### Signals

- void error ( QProcess::ProcessError error )
- void finished ( int exitCode )
- void finishing ()
- void readyReadStandardError ()
- void readyReadStandardOutput ()
- void started ()
- void stateChanged ( QProcess::ProcessState state )

- 2 signals inherited from QIODevice
- 1 signal inherited from QObject

### Static Public Members

- 4 static public members inherited from QObject

### Protected Functions

- void setProcessState ( QProcess::ProcessState state )

- 4 protected functions inherited from QIODevice
- 7 protected functions inherited from QObject

## 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(). 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.

Just before the process exits, QProcess enters the Finishing state and emits finishing(), allowing you to read any pending output from the process before the process dies. Finally, QProcess reenters the NotRunning state (the initial state) and emits finished().

The finished() signal provides the exit code of the process as an argument, and you can also call exitCode(), which returns the exit code of the last process that finished. At an error occurs at any point in time, QProcess will emit the error() signal. You can also call processError() to find the type of error that occurred last, and processState() to find the current process state.

Processes have two predefined output channels: the standard output channel (for regular console output) and the standard error channel (where errors are usually printed). These channels represent two separate streams of data. You can toggle between the two channels by calling setInputChannel(). QProcess emits readyRead() when data is available on the current input 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 readChar(), you can explicitly read all data from either of the two channels by calling readAllStandardOutput() or readAllStandardError().

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 input 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:

See also QBuffer, QFile, and QTcpSocket.

## Member Type Documentation

### enum QProcess::ProcessChannel

### enum QProcess::ProcessError

### enum QProcess::ProcessState

## Member Function Documentation

### QProcess::QProcess ( QObject * parent = 0 )

Constructs a QProcess object with the given parent.

### QProcess::~QProcess () `[virtual]`

Destructs the QProcess object.

### void QProcess::close () `[virtual]`

Closes all communication with the process. After calling this function, QProcess will no longer emit readyRead(), and data can no longer be read or written.

Reimplemented from QIODevice.

### QStringList QProcess::environment () const

Returns the environment that QProcess will use when starting a process, or an empty QStringList if no environment has been set. It no environment has been set, the environment of the calling process will be used.

See also setEnvironment().

### void QProcess::error ( QProcess::ProcessError error ) `[signal]`

### int QProcess::exitCode () const

Returns the exit code of the last process that finished.

### void QProcess::finished ( int exitCode ) `[signal]`

### void QProcess::finishing () `[signal]`

### ProcessChannel QProcess::inputChannel () const

Returns the current input channel of QProcess.

See also setInputChannel().

### Q_PID QProcess::pid () const

Returns the native process identifier for the running process, if available. If no process is currently running, 0 is returned.

### QProcess::ProcessError QProcess::processError () const

Returns the type of error that occurred last.

See also error().

### QProcess::ProcessState QProcess::processState () const

Returns the current state of the process.

See also stateChanged().

### QByteArray QProcess::readAllStandardError ()

Regardless of the current input channel, this function returns all data available from the standard error of the process as a QByteArray.

See also readyReadStandardError(), readAllStandardOutput(), inputChannel(), and setInputChannel().

### QByteArray QProcess::readAllStandardOutput ()

Regardless of the current input channel, this function returns all data available from the standard output of the process as a QByteArray.

See also readyReadStandardOutput(), readAllStandardError(), inputChannel(), and setInputChannel().

### void QProcess::readyReadStandardError () `[signal]`

### void QProcess::readyReadStandardOutput () `[signal]`

### void QProcess::setEnvironment ( const QStringList & environment )

Sets the environment that QProcess will use when starting a process to environment.

See also environment().

### void QProcess::setInputChannel ( ProcessChannel channel )

Sets the current input channel of QProcess to channel. The current input channel is used by the functions read(), readAll(), readLine() and getChar(). It also decides which channel triggers QProcess to emit readyRead().

See also inputChannel().

### void QProcess::setProcessState ( QProcess::ProcessState state ) `[protected]`

### void QProcess::setWorkingDirectory ( const QString & dir )

Sets the working directory to dir. QProcess will start the process in this directory. The default behavior is to start the process in the working directory of the calling process.

See also setWorkingDirectory() and start().

### void QProcess::start ( const QString & program, const QStringList & arguments = QStringList() )

Starts the program program in a new process, passing the command line arguments in arguments. QProcess will immediately enter the Starting state. If the process starts successfully, QProcess will emit started(); otherwise, error() will be emitted.

See also pid() and started().

### void QProcess::started () `[signal]`

### void QProcess::stateChanged ( QProcess::ProcessState state ) `[signal]`

### void QProcess::terminate ()

Terminates the current process, causing it to crash.

### bool QProcess::waitForFinished ( int msecs = 30000 )

Blocks until the process has finished and the finished() signal has been emitted, or until msecs milliseconds have passed.

Returns true if the process finished; otherwise returns false (if the operation timed out or if an error occurred).

This function can operate without an event loop. It is useful when writing non-GUI applications and when performing I/O operations in a non-GUI thread.

Warning: Calling this function from the main (GUI) thread might cause your user interface to freeze.

See also waitForFinished().

### bool QProcess::waitForStarted ( int msecs = 30000 )

Blocks until the process has started and the started() signal has been emitted, or until msecs milliseconds have passed.

Returns true if the process was started successfully; otherwise returns false (if the operation timed out or if an error occurred).

This function can operate without an event loop. It is useful when writing non-GUI applications and when performing I/O operations in a non-GUI thread.

Warning: Calling this function from the main (GUI) thread might cause your user interface to freeze.

See also waitForFinished().

### QString QProcess::workingDirectory () const

Returns the working directory that the QProcess will enter before the program has started.

See also setWorkingDirectory().