qprocess.3qt

linux下GUI编程工具qt的在线连接帮助手册

'\" t
.TH QProcess 3qt "11 October 2001" "Trolltech AS" \" -*- nroff -*-
.\" Copyright 1992-2001 Trolltech AS.  All rights reserved.  See the
.\" license file included in the distribution for a complete license
.\" statement.
.\"
.ad l
.nh
.SH NAME
QProcess \- Used to start external programs and to communicate with them
.PP
\fC#include <qprocess.h>\fR
.PP
Inherits QObject.
.PP
.SS "Public Members"
.in +1c
.ti -1c
.BI "\fBQProcess\fR ( QObject * parent = 0, const char * name = 0 )"
.br
.ti -1c
.BI "\fBQProcess\fR ( const QString & arg0, QObject * parent = 0, const char * name = 0 )"
.br
.ti -1c
.BI "\fBQProcess\fR ( const QStringList & args, QObject * parent = 0, const char * name = 0 )"
.br
.ti -1c
.BI "\fB~QProcess\fR ()"
.br
.ti -1c
.BI "QStringList \fBarguments\fR () const"
.br
.ti -1c
.BI "void \fBclearArguments\fR ()"
.br
.ti -1c
.BI "virtual void \fBsetArguments\fR ( const QStringList & args )"
.br
.ti -1c
.BI "virtual void \fBaddArgument\fR ( const QString & arg )"
.br
.ti -1c
.BI "QDir \fBworkingDirectory\fR () const"
.br
.ti -1c
.BI "virtual void \fBsetWorkingDirectory\fR ( const QDir & dir )"
.br
.ti -1c
.BI "enum \fBCommunication\fR { Stdin = 0x01, Stdout = 0x02, Stderr = 0x04, DupStderr = 0x08 }"
.br
.ti -1c
.BI "void \fBsetCommunication\fR ( int commFlags )"
.br
.ti -1c
.BI "int \fBcommunication\fR () const"
.br
.ti -1c
.BI "virtual bool \fBstart\fR ( QStringList * env = 0 )"
.br
.ti -1c
.BI "virtual bool \fBlaunch\fR ( const QString & buf, QStringList * env = 0 )"
.br
.ti -1c
.BI "virtual bool \fBlaunch\fR ( const QByteArray & buf, QStringList * env = 0 )"
.br
.ti -1c
.BI "bool \fBisRunning\fR () const"
.br
.ti -1c
.BI "bool \fBnormalExit\fR () const"
.br
.ti -1c
.BI "int \fBexitStatus\fR () const"
.br
.ti -1c
.BI "virtual QByteArray \fBreadStdout\fR ()"
.br
.ti -1c
.BI "virtual QByteArray \fBreadStderr\fR ()"
.br
.ti -1c
.BI "bool \fBcanReadLineStdout\fR () const"
.br
.ti -1c
.BI "bool \fBcanReadLineStderr\fR () const"
.br
.ti -1c
.BI "virtual QString \fBreadLineStdout\fR ()"
.br
.ti -1c
.BI "virtual QString \fBreadLineStderr\fR ()"
.br
.ti -1c
.BI "PID \fBprocessIdentifier\fR ()"
.br
.in -1c
.SS "Public Slots"
.in +1c
.ti -1c
.BI "void \fBtryTerminate\fR () const"
.br
.ti -1c
.BI "void \fBkill\fR () const"
.br
.ti -1c
.BI "virtual void \fBwriteToStdin\fR ( const QByteArray & buf )"
.br
.ti -1c
.BI "virtual void \fBwriteToStdin\fR ( const QString & buf )"
.br
.ti -1c
.BI "virtual void \fBcloseStdin\fR ()"
.br
.in -1c
.SS "Signals"
.in +1c
.ti -1c
.BI "void \fBreadyReadStdout\fR ()"
.br
.ti -1c
.BI "void \fBreadyReadStderr\fR ()"
.br
.ti -1c
.BI "void \fBprocessExited\fR ()"
.br
.ti -1c
.BI "void \fBwroteToStdin\fR ()"
.br
.ti -1c
.BI "void \fBlaunchFinished\fR ()"
.br
.in -1c
.SH DESCRIPTION
The QProcess class is used to start external programs and to communicate with them.
.PP
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() function (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.
.PP
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, standard output and standard error, use the start() function.
.PP
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 QByteArray 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().
.PP
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 \fInot\fR 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().
.PP
Both start() and launch() can accept a string list of strings with the format, key=value, where the keys are the names of environment variables.
.PP
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 \fIreally\fR want to terminate the program, without it having any chance to clean up, you can use kill().
.PP
As an example, suppose we want to start the \fCuic\fR command (a Qt command line tool used with \fIQt Designer\fR) and perform some operations on the output (the \fCuic\fR 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:
.PP
.nf
.br
  uic -tr i18n small_dialog.ui
.br
.fi
.PP
A code snippet for this with the QProcess class might look like this:
.PP
.nf
.br
    UicManager::UicManager()
.br
    {
.fi
.PP
.nf
.br
        proc = new QProcess( this );
.fi
.PP
.nf
.br
        proc->addArgument( "uic" );
.br
        proc->addArgument( "-tr" );
.br
        proc->addArgument( "i18n" );
.br
        proc->addArgument( "small_dialog.ui" );
.br
.br
        connect( proc, SIGNAL(readyReadStdout()),
.br
                this, SLOT(readFromStdout()) );
.fi
.PP
.nf
.br
        if ( !proc->start() ) {
.br
            // error handling
.fi
.PP
.nf
.br
        }
.br
    }
.fi
.PP
.nf
.br
    void UicManager::readFromStdout()
.br
    {
.br
        // Read and process the data.
.br
        // Bear in mind that the data might be output in chunks.
.fi
.PP
.nf
.br
    }
.fi
.PP
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().
.PP
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.
.PP
See also QSocket, Input/Output and Networking and Miscellaneous Classes.
.SS "Member Type Documentation"
.SH "QProcess::Communication"
This enum type defines the communication channels connected to the process.
.TP
\fCQProcess::Stdin\fR - Data can be written to the process's standard input.
.TP
\fCQProcess::Stdout\fR - Data can be read from the process's standard output.
.TP
\fCQProcess::Stderr\fR - Data can be read from the process's standard error.
.TP
\fCQProcess::DupStderr\fR - Duplicates standard error to standard output for new processes; i.e. everything that the process writes to standard error, is reported by QProcess on standard output instead. This is especially useful if your application requires that the output on standard output and standard error is read in the same order as the process output it. Please note that this is a binary flag, so if you want to activate this together with standard input, output and error redirection (the default), you have to specify \fCStdin|Stdout|Stderr|DupStderr\fR for the setCommunication() call.
.PP
See also setCommunication() and communication().
.SH MEMBER FUNCTION DOCUMENTATION
.SH "QProcess::QProcess ( QObject * parent = 0, const char * name = 0 )"
Constructs a QProcess object. The \fIparent\fR and \fIname\fR parameters are passed to the QObject constructor.
.PP
See also setArguments(), addArgument() and start().
.SH "QProcess::QProcess ( const QString & arg0, QObject * parent = 0, const char * name = 0 )"