QProcess Class

QProcess 类用于启动外部程序并与之通信。更多

Header: #include <QProcess>
CMake.QProcess find_package(Qt6 REQUIRED COMPONENTS Core)
target_link_libraries(mytarget PRIVATE Qt6::Core)
qmake: QT += core
继承: QIODevice

注意:该类中的所有函数都是可重入的

公共类型

struct CreateProcessArguments
(since 6.6) struct UnixProcessParameters
CreateProcessArgumentModifier
enum ExitStatus { NormalExit, CrashExit }
enum InputChannelMode { ManagedInputChannel, ForwardedInputChannel }
enum ProcessChannel { StandardOutput, StandardError }
enum ProcessChannelMode { SeparateChannels, MergedChannels, ForwardedChannels, ForwardedErrorChannel, ForwardedOutputChannel }
enum ProcessError { FailedToStart, Crashed, Timedout, WriteError, ReadError, UnknownError }
enum ProcessState { NotRunning, Starting, Running }
(since 6.6) enum class UnixProcessFlag { CloseFileDescriptors, CreateNewSession, DisconnectControllingTerminal, IgnoreSigPipe, ResetIds, …, DisableCoreDumps }
flags UnixProcessFlags

公共函数

QProcess(QObject *parent = nullptr)
virtual ~QProcess()
QStringList arguments() const
(since 6.0) std::function<void ()> childProcessModifier() const
void closeReadChannel(QProcess::ProcessChannel channel)
void closeWriteChannel()
QProcess::CreateProcessArgumentModifier createProcessArgumentsModifier() const
QProcess::ProcessError error() const
int exitCode() const
QProcess::ExitStatus exitStatus() const
(since 6.7) void failChildProcessModifier(const char *description, int error = 0)
QProcess::InputChannelMode inputChannelMode() const
QString nativeArguments() const
QProcess::ProcessChannelMode processChannelMode() const
QProcessEnvironment processEnvironment() const
qint64 processId() const
QString program() const
QByteArray readAllStandardError()
QByteArray readAllStandardOutput()
QProcess::ProcessChannel readChannel() const
void setArguments(const QStringList &arguments)
(since 6.0) void setChildProcessModifier(const std::function<void ()> &modifier)
void setCreateProcessArgumentsModifier(QProcess::CreateProcessArgumentModifier modifier)
void setInputChannelMode(QProcess::InputChannelMode mode)
void setNativeArguments(const QString &arguments)
void setProcessChannelMode(QProcess::ProcessChannelMode mode)
void setProcessEnvironment(const QProcessEnvironment &environment)
void setProgram(const QString &program)
void setReadChannel(QProcess::ProcessChannel channel)
void setStandardErrorFile(const QString &fileName, QIODeviceBase::OpenMode mode = Truncate)
void setStandardInputFile(const QString &fileName)
void setStandardOutputFile(const QString &fileName, QIODeviceBase::OpenMode mode = Truncate)
void setStandardOutputProcess(QProcess *destination)
(since 6.6) void setUnixProcessParameters(const QProcess::UnixProcessParameters &params)
(since 6.6) void setUnixProcessParameters(QProcess::UnixProcessFlags flagsOnly)
void setWorkingDirectory(const QString &dir)
void start(const QString &program, const QStringList &arguments = {}, QIODeviceBase::OpenMode mode = ReadWrite)
void start(QIODeviceBase::OpenMode mode = ReadWrite)
(since 6.0) void startCommand(const QString &command, QIODeviceBase::OpenMode mode = ReadWrite)
bool startDetached(qint64 *pid = nullptr)
QProcess::ProcessState state() const
(since 6.6) QProcess::UnixProcessParameters unixProcessParameters() const
bool waitForFinished(int msecs = 30000)
bool waitForStarted(int msecs = 30000)
QString workingDirectory() const

重新实现的公共函数

virtual qint64 bytesToWrite() const override
virtual void close() override
virtual bool isSequential() const override
virtual bool open(QIODeviceBase::OpenMode mode = ReadWrite) override
virtual bool waitForBytesWritten(int msecs = 30000) override
virtual bool waitForReadyRead(int msecs = 30000) override

公共插槽

void kill()
void terminate()

信号

void errorOccurred(QProcess::ProcessError error)
void finished(int exitCode, QProcess::ExitStatus exitStatus = NormalExit)
void readyReadStandardError()
void readyReadStandardOutput()
void started()
void stateChanged(QProcess::ProcessState newState)

静态公共成员

int execute(const QString &program, const QStringList &arguments = {})
QString nullDevice()
QStringList splitCommand(QStringView command)
bool startDetached(const QString &program, const QStringList &arguments = {}, const QString &workingDirectory = QString(), qint64 *pid = nullptr)
QStringList systemEnvironment()

受保护函数

void setProcessState(QProcess::ProcessState state)

重新实现的受保护函数

virtual qint64 readData(char *data, qint64 maxlen) override

详细说明

运行进程

要启动进程,请将要运行的程序的名称和命令行参数作为参数传递给start() 。参数以单独字符串的形式在QStringList 中提供。

或者,也可以使用setProgram() 和setArguments() 设置程序运行,然后调用start() 或open()。

例如,下面的代码片段通过在参数列表中传递包含"-style "和 "fusion "的字符串,在 X11 平台上以 Fusion 风格运行模拟时钟示例:

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

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

然后,QProcess 进入Starting 状态,当程序启动后,QProcess 进入Running 状态并发出started() 命令。

QProcess 允许您将进程视为顺序 I/O 设备。就像使用QTcpSocket 访问网络连接一样,您可以向进程写入或从进程读取数据。然后,您可以通过调用write() 向进程的标准输入写入,并通过调用read(),readLine() 和getChar() 读取标准输出。由于继承了QIODevice ,QProcess 也可用作QXmlReader 的输入源,或使用QNetworkAccessManager 生成要上传的数据。

当进程退出时,QProcess 会重新进入NotRunning 状态(初始状态),并发出finished() 信号。

finished() 信号提供了进程的退出代码和退出状态作为参数,您还可以调用exitCode() 获取最后完成的进程的退出代码,调用exitStatus() 获取其退出状态。如果在任何时候发生错误,QProcess 都会发出errorOccurred() 信号。您还可以调用error() 查找上次发生的错误类型,调用state() 查找当前进程状态。

注意: VxWorks、iOS、tvOS 或 watchOS 不支持 QProcess。

查找可执行文件

可以通过调用setProgram() 或直接调用start() 来设置要运行的程序。使用程序名称和参数调用start() 的效果等同于在该函数之前调用setProgram() 和setArguments() ,然后调用重载而不使用这些参数。

QProcess 会以三种不同方式之一解释程序名称,这与 Unix shell 和 Windows 命令解释器在各自命令行中的操作方式类似:

  • 如果程序名称是一个绝对路径,那么它就是将要启动的确切可执行文件,QProcess 不会进行搜索。
  • 如果程序名是一个包含多个路径组件(即至少包含一个斜线)的相对路径,那么搜索该相对路径的起始目录取决于操作系统:在 Windows 系统中,它是父进程的当前工作目录,而在 Unix 系统中,它是用setWorkingDirectory() 设置的目录。
  • 如果程序名称是一个不带斜线的普通文件名,则其行为与操作系统有关。在 Unix 系统上,QProcess 会搜索PATH 环境变量;而在 Windows 系统上,搜索由操作系统执行,首先会搜索父进程的当前目录,然后才是PATH 环境变量(完整列表请参阅CreateProcess文档)。

为避免出现与平台相关的行为或与当前应用程序启动方式相关的任何问题,建议始终传递要启动的可执行文件的绝对路径。对于随应用程序一起提供的辅助二进制文件,可以以QCoreApplication::applicationDirPath() 开始构建这样一个路径。同样,要显式运行相对于setWorkingDirectory() 设置的目录的可执行文件,可使用以"./"或"../"开头的程序路径。

在 Windows 中,除了CreateProcess文档中列出的用途外,大多数用途都不需要".exe "后缀。此外,QProcess 还会将 Unix 风格的正斜杠转换为 Windows 路径的程序名反斜杠。这样,使用 QProcess 编写的代码就可以跨平台使用,如上面的示例所示。

QProcess 不支持直接执行 Unix shell 或 Windows 命令解释器的内置函数,如cmd.exedir 命令或 Bourne shell 的export 。在 Unix 上,尽管许多 shell 内置函数也作为单独的可执行文件提供,但它们的行为可能与作为内置函数实现的行为不同。要运行这些命令,必须明确执行解释器,并加上适当的选项。对于 Unix 系统,使用两个参数启动"/bin/sh":"-c "和一个包含要运行的命令行的字符串。对于 Windows 系统,由于cmd.exe 采用非标准方式解析命令行,因此应使用setNativeArguments() (例如,"/c dir d:")。

环境变量

QProcess API 提供了操作子进程将看到的环境变量的方法。默认情况下,子进程将拥有调用start() 函数时存在的当前进程环境变量的副本。这意味着在调用qputenv() 之前使用该函数执行的任何修改都将反映在子进程的环境中。请注意,QProcess 不会试图防止其他线程中出现与qputenv() 竞争的情况,因此建议在应用程序初始启动后避免使用qputenv() 。

可以使用processEnvironment() 和setProcessEnvironment() 函数修改特定子代的环境,这两个函数使用QProcessEnvironment 类。默认情况下,processEnvironment() 将返回QProcessEnvironment::inheritsFromParent() 为 true 的对象。设置一个不继承自父进程的环境将导致 QProcess 在启动子进程时完全使用该环境。

正常情况下,QProcess 会调用QProcessEnvironment::systemEnvironment() 从当前环境开始,然后添加、更改或删除特定变量。由此产生的变量名册可通过setProcessEnvironment() 应用于 QProcess。

使用 QProcessEnvironment() 默认构造函数,可以删除环境中的所有变量,或从一个空环境开始。在不受控和系统特定的情况下,这种做法并不可取,因为当前进程环境中可能设置了一些系统变量,而这些变量是正确执行子进程所必需的。

在 Windows 系统中,如果当前进程的"PATH""SystemRoot" 环境变量未设置,QProcess 将复制它们。虽然无法完全取消设置,但可以将它们设置为空。在 Windows 上将"PATH" 设为空值可能会导致子进程无法启动。

通过通道通信

进程有两个预定义的输出通道:标准输出通道 (stdout) 提供常规控制台输出,而标准错误通道 (stderr) 通常提供进程打印的错误信息。这些通道代表两个独立的数据流。您可以通过调用setReadChannel() 在它们之间切换。当当前读取通道上有数据时,QProcess 会发出readyRead() 。当有新的标准输出数据时,它还会发出readyReadStandardOutput() ;当有新的标准错误数据时,会发出readyReadStandardError() 。您可以通过调用readAllStandardOutput() 或readAllStandardError() 来明确读取两个通道中任何一个通道的所有数据,而不是调用read() 、readLine() 或getChar() 。

通道的术语可能会引起误解。请注意,进程的输出通道对应 QProcess 的读取通道,而进程的输入通道对应 QProcess 的写入通道。这是因为我们使用 QProcess 读取的是进程的输出,而我们写入的则是进程的输入。

QProcess 可以合并两个输出通道,使运行进程的标准输出和标准错误数据都使用标准输出通道。在启动进程前,用MergedChannels 调用setProcessChannelMode() 激活此功能。还可以通过ForwardedChannels 作为参数,将运行进程的输出转发给调用的主进程。也可以只转发其中一个输出通道--通常会使用ForwardedErrorChannel ,但也有ForwardedOutputChannel 。需要注意的是,在图形用户界面应用程序中,使用通道转发通常不是一个好主意--应该以图形方式显示错误。

某些进程需要特殊的环境设置才能运行。你可以通过调用setProcessEnvironment() 为你的进程设置环境变量。要设置工作目录,请调用setWorkingDirectory() 。默认情况下,进程在调用进程的当前工作目录下运行。

使用 QProcess 启动的图形用户界面应用程序的窗口定位和屏幕 Z 排序由底层窗口系统控制。对于 Qt 5 应用程序,可使用-qwindowgeometry 命令行选项指定定位;X11 应用程序通常接受-geometry 命令行选项。

同步进程 API

QProcess 提供了一组函数,通过暂停调用线程直到某些信号发出,QProcess 可以在没有事件循环的情况下使用:

从主线程(调用QApplication::exec() 的线程)调用这些函数可能会导致用户界面冻结。

下面的示例运行gzip 来压缩字符串 "Qt rocks!",没有事件循环:

    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();

另请参阅 QBufferQFileQTcpSocket

成员类型文档

QProcess::CreateProcessArgumentModifier

注意: 该类型定义仅适用于桌面 Windows。

在 Windows 上,QProcess 使用 Win32 API 函数CreateProcess 来启动子进程。虽然QProcess 提供了一种无需担心平台细节即可轻松启动进程的方法,但在某些情况下,最好还是对传递给CreateProcess 的参数进行微调。这可以通过定义CreateProcessArgumentModifier 函数并将其传递给setCreateProcessArgumentsModifier 来实现。

CreateProcessArgumentModifier 函数接收一个参数:指向CreateProcessArguments 结构的指针。在调用CreateProcessArgumentModifier 函数后,该结构体的成员将被传递到CreateProcess

下面的示例演示了如何向CreateProcess 传递自定义标志。当从控制台进程 A 启动控制台进程 B 时,QProcess 默认会为进程 B 重用进程 A 的控制台窗口。在本例中,将为子进程 B 创建一个具有自定义配色方案的新控制台窗口。

    QProcess process;
    process.setCreateProcessArgumentsModifier([] (QProcess::CreateProcessArguments *args)
    {
        args->flags |= CREATE_NEW_CONSOLE;
        args->startupInfo->dwFlags &= ~STARTF_USESTDHANDLES;
        args->startupInfo->dwFlags |= STARTF_USEFILLATTRIBUTE;
        args->startupInfo->dwFillAttribute = BACKGROUND_BLUE | FOREGROUND_RED
                                           | FOREGROUND_INTENSITY;
    });
    process.start("C:\\Windows\\System32\\cmd.exe", QStringList() << "/k" << "title" << "The Child Process");

另请参阅 QProcess::CreateProcessArgumentssetCreateProcessArgumentsModifier()。

enum QProcess::ExitStatus

该枚举描述了QProcess 的不同退出状态。

常量说明
QProcess::NormalExit0进程正常退出。
QProcess::CrashExit1进程崩溃。

另请参阅 exitStatus().

enum QProcess::InputChannelMode

该枚举描述了QProcess 的过程输入通道模式。将其中一个值传入setInputChannelMode() 可设置当前的写入通道模式。

常量说明
QProcess::ManagedInputChannel0QProcess 管理运行进程的输入。这是 的默认输入通道模式。QProcess
QProcess::ForwardedInputChannel1QProcess 将主进程的输入转发给运行中的进程。子进程从与主进程相同的源读取标准输入。请注意,当子进程正在运行时,主进程不得尝试读取其标准输入。

另请参阅 setInputChannelMode().

enum QProcess::ProcessChannel

该枚举描述了运行中的进程所使用的进程通道。将其中一个值传递给setReadChannel() 可设置QProcess 的当前读取通道。

常量说明
QProcess::StandardOutput0运行进程的标准输出(stdout)。
QProcess::StandardError1运行进程的标准错误 (stderr)。

另请参阅 setReadChannel().

enum QProcess::ProcessChannelMode

该枚举描述了QProcess 的过程输出通道模式。将其中一个值传入setProcessChannelMode() 可设置当前的读取通道模式。

常量说明
QProcess::SeparateChannels0QProcess 管理运行进程的输出,将标准输出和标准错误数据保存在不同的内部缓冲区中。调用 () 可以选择 的当前读取通道。这是 的默认通道模式。setReadChannel QProcess QProcess
QProcess::MergedChannels1QProcess 将运行进程的输出合并到标准输出通道 ( ) 中。标准错误通道 ( ) 不会接收任何数据。运行进程的标准输出和标准错误数据将交错排列。对于分离进程,运行进程的合并输出将转发给主进程。stdoutstderr
QProcess::ForwardedChannels2QProcess 将运行进程的输出转发给主进程。子进程写入其标准输出和标准错误的任何内容都将写入主进程的标准输出和标准错误。
QProcess::ForwardedErrorChannel4QProcess 管理运行中进程的标准输出,但将其标准错误转发给主进程。这反映了命令行工具作为过滤器的典型用途,即标准输出被重定向到另一个进程或文件,而标准错误被打印到控制台以进行诊断。(此值在 Qt 5.2 中引入)。
QProcess::ForwardedOutputChannel3与 ForwardedErrorChannel 互补。(此值在 Qt 5.2 中引入)。

注意: Windows 故意抑制从纯图形用户界面应用程序到继承控制台的输出。这不适用于重定向到文件或管道的输出。要在控制台上转发纯图形用户界面应用程序的输出,必须使用 SeparateChannels,并通过读取输出并将其写入适当的输出通道来自行完成转发。

另请参阅 setProcessChannelMode()。

enum QProcess::ProcessError

该枚举描述了QProcess 报告的不同错误类型。

常量说明
QProcess::FailedToStart0进程启动失败。可能是调用的程序丢失,也可能是调用程序的权限或资源不足。
QProcess::Crashed1进程在成功启动一段时间后崩溃。
QProcess::Timedout2最后一个 waitFor...() 函数超时。QProcess 的状态保持不变,您可以再次尝试调用 waitFor...()。
QProcess::WriteError4尝试向进程写入时发生错误。例如,进程可能没有运行,或者关闭了输入通道。
QProcess::ReadError3尝试从进程读取数据时发生错误。例如,进程可能没有运行。
QProcess::UnknownError5发生未知错误。这是error() 的默认返回值。

另请参阅 error()。

enum QProcess::ProcessState

该枚举描述了QProcess 的不同状态。

常量说明
QProcess::NotRunning0进程未运行。
QProcess::Starting1进程正在启动,但程序尚未调用。
QProcess::Running2进程正在运行,可以进行读写操作。

另请参阅 state().

[since 6.6] 枚举类 QProcess::UnixProcessFlag
flags QProcess::UnixProcessFlags

这些标志可用于UnixProcessParametersflags 字段。

常量说明
QProcess::UnixProcessFlag::CloseFileDescriptors0x0010关闭所有超过lowestFileDescriptorToClose 所定义阈值的文件描述符,防止父进程中任何当前打开的描述符意外泄漏给子进程。stdinstdoutstderr 文件描述符永远不会关闭。
QProcess::UnixProcessFlag::CreateNewSession (since Qt 6.7)0x0040通过调用setsid(2) ,启动一个新的进程会话。这样,子进程就可以在当前进程所处的会话结束后继续运行。这是startDetached() 允许进程脱离的步骤之一,也是对进程进行守护进程化的步骤之一。
QProcess::UnixProcessFlag::DisconnectControllingTerminal (since Qt 6.7)0x0080如果进程有控制终端,则要求进程断开与其控制终端的连接。如果没有控制终端,则什么也不会发生。如果终端关闭,仍连接到控制终端的进程可能会收到挂起(SIGHUP )信号,或其他终端控制信号(SIGTSTP,SIGTTIN,SIGTTOU )。请注意,在某些操作系统上,进程只有在作为会话领导者的情况下才能断开与控制终端的连接,这意味着可能需要使用CreateNewSession 标志。和它一样,这是守护进程的步骤之一。
QProcess::UnixProcessFlag::IgnoreSigPipe0x0002总是将SIGPIPE 信号设置为忽略 (SIG_IGN),即使已设置ResetSignalHandlers 标志。默认情况下,如果子进程在使用QProcess::closeReadChannel() 关闭相应通道后试图向标准输出或标准错误中写入内容,则会收到SIGPIPE 信号并立即终止;使用该标志后,写入操作会失败,但不会收到信号,子进程可以继续执行。
QProcess::UnixProcessFlag::ResetIds (since Qt 6.7)0x0100删除当前进程可能保留的有效用户或组 ID(参见setuid(2)setgid(2) 以及QCoreApplication::setSetuidAllowed() )。如果当前进程使用了 setuid 或 setgid,且不希望子进程保留已提升的权限,则此操作非常有用。
QProcess::UnixProcessFlag::ResetSignalHandlers0x0001将所有 Unix 信号处理器重置为默认状态(即通过SIG_DFLsignal(2) )。该标记有助于确保任何被忽略的 (SIG_IGN) 信号不会影响子进程的行为。
QProcess::UnixProcessFlag::UseVFork0x0020要求QProcess 使用vfork(2) 启动子进程。使用此标志可表明在setChildProcessModifier() 中设置的回调函数可在vfork(2) 的子进程中安全执行;也就是说,回调函数不会修改任何非本地变量(直接或通过它调用的任何函数),也不会试图与父进程通信。至于QProcess 是否会实际使用vfork(2) ,以及vfork(2) 是否与标准fork(2) 不同,则由实现定义。
QProcess::UnixProcessFlag::DisableCoreDumps (since Qt 6.9)0x0200要求QProcess 禁用子进程中的核心转储。如果正在运行的可执行文件可能会崩溃,但用户和维护者对生成错误报告不感兴趣(例如,可执行文件是一个测试进程),这将非常有用。该设置不会影响崩溃进程的exitStatus() 。它是通过将核心转储大小资源软限制设置为零来实现的,这意味着应用程序仍可通过将其提升至硬限制值来扭转这一变化。

该枚举在 Qt 6.6 中引入。

UnixProcessFlags 类型是QFlags<UnixProcessFlag> 的类型定义。它存储 UnixProcessFlag 值的 OR 组合。

另请参阅 setUnixProcessParameters() 和unixProcessParameters()。

成员函数文档

[explicit] QProcess::QProcess(QObject *parent = nullptr)

用给定的parent 构建一个 QProcess 对象。

[virtual noexcept] QProcess::~QProcess()

销毁QProcess 对象,即杀死进程。

请注意,在进程终止之前,该函数不会返回。

QStringList QProcess::arguments() const

返回进程最后启动时的命令行参数。

另请参阅 setArguments() 和start()。

[override virtual] qint64 QProcess::bytesToWrite() const

重实现:QIODevice::bytesToWrite() const.

[since 6.0] std::function<void ()> QProcess::childProcessModifier() const

返回之前通过调用setChildProcessModifier() 设置的修改器函数。

注: 此函数仅适用于 Unix 平台。

此函数在 Qt 6.0 中引入。

另请参阅 setChildProcessModifier() 和unixProcessParameters()。

[override virtual] void QProcess::close()

重新实现:QIODevice::close().

关闭与进程的所有通信并杀死进程。调用此函数后,QProcess 将不再发出readyRead() ,数据也无法读取或写入。

void QProcess::closeReadChannel(QProcess::ProcessChannel channel)

关闭读取通道channel 。调用此函数后,QProcess 将不再接收通道上的数据。任何已接收的数据仍可用于读取。

如果对进程的输出不感兴趣,调用此函数可节省内存。

另请参阅 closeWriteChannel() 和setReadChannel()。

void QProcess::closeWriteChannel()

计划关闭QProcess 的写入通道。一旦所有数据都已写入进程,通道就会关闭。调用此函数后,任何向进程写入数据的尝试都将失败。

对于在通道关闭前读取输入数据的程序来说,关闭写入通道是必要的。例如,程序 "more "用于在 Unix 和 Windows 的控制台中显示文本数据。但在QProcess 的写入通道关闭之前,它不会显示文本数据。举例说明:

QProcess more;
more.start("more");
more.write("Text to display");
more.closeWriteChannel();
// QProcess will emit readyRead() once "more" starts printing

调用start() 时会隐式打开写入通道。

另请参阅 closeReadChannel()。

QProcess::CreateProcessArgumentModifier QProcess::createProcessArgumentsModifier() const

返回先前设置的CreateProcess 修改器函数。

注: 该函数仅适用于 Windows 平台。

另请参阅 setCreateProcessArgumentsModifier() 和QProcess::CreateProcessArgumentModifier

QProcess::ProcessError QProcess::error() const

返回最后发生的错误类型。

另请参阅 state()。

[signal] void QProcess::errorOccurred(QProcess::ProcessError error)

该信号在进程发生错误时发出。指定的error 描述了发生错误的类型。

[static] int QProcess::execute(const QString &program, const QStringList &arguments = {})

在新进程中使用参数arguments 启动程序program ,等待程序结束,然后返回进程的退出代码。新进程写入控制台的任何数据都会转发给调用进程。

环境和工作目录从调用进程继承。

参数处理与start() 的重载相同。

如果进程无法启动,将返回 -2。如果进程崩溃,则返回-1。否则,将返回进程的退出代码。

另请参阅 start() 。

int QProcess::exitCode() const

返回最后完成的进程的退出代码。

除非exitStatus() 返回NormalExit ,否则该值无效。

QProcess::ExitStatus QProcess::exitStatus() const

返回最后完成的进程的退出状态。

在 Windows 系统中,如果进程是通过其他应用程序的 TerminateProcess() 终止的,除非退出代码小于 0,否则该函数仍将返回NormalExit

[noexcept, since 6.7] void QProcess::failChildProcessModifier(const char *description, int error = 0)

这些函数可在修改器集setChildProcessModifier() 中使用,以表示遇到了错误情况。当修改器调用这些函数时,QProcess 会在父进程中发出代码为QProcess::FailedToStarterrorOccurred() 。description 可用于在errorString() 中包含一些信息,以帮助诊断问题,通常是调用失败的名称,类似于 C 库函数perror() 。此外,error 参数可以是一个<errno.h> 错误代码,其文本形式也将被包含在内。

例如,子进程修改器可以这样为子进程准备一个额外的文件描述符:

process.setChildProcessModifier([fd, &process]() {
    if (dup2(fd, TargetFileDescriptor) < 0)
        process.failChildProcessModifier(errno, "aux comm channel");
});
process.start();

其中fd 是父进程当前打开的文件描述符。如果dup2() 系统调用导致EBADF 条件,则进程errorString() 可以是 "子进程修改器报错:aux comm channel:Bad file descriptor"。

该函数不会返回给调用者。除子进程修改器和正确的QProcess 对象外,在其他任何地方使用该函数都是未定义的行为。

注意: description 参数的长度限制为 500 个字符左右。这不包括error 代码中的文本。

此函数在 Qt 6.7 中引入。

另请参阅 setChildProcessModifier() 和setUnixProcessParameters()。

[signal] void QProcess::finished(int exitCode, QProcess::ExitStatus exitStatus = NormalExit)

exitCode 是进程的退出代码(仅对正常退出有效),exitStatus 是退出状态。进程结束后,QProcess 中的缓冲区仍然完好无损。您仍然可以读取进程结束前可能写入的任何数据。

另请参阅 exitStatus() 。

QProcess::InputChannelMode QProcess::inputChannelMode() const

返回QProcess 标准输入通道的通道模式。

另请参阅 setInputChannelMode() 和InputChannelMode

[override virtual] bool QProcess::isSequential() const

重实现:QIODevice::isSequential() const.

[slot] void QProcess::kill()

杀死当前进程,使其立即退出。

在 Windows 上,kill() 使用的是 TerminateProcess,而在 Unix 和 macOS 上,则是向进程发送 SIGKILL 信号。

另请参阅 terminate().

QString QProcess::nativeArguments() const

返回程序的附加本地命令行参数。

注意: 该函数仅适用于 Windows 平台。

另请参阅 setNativeArguments()。

[static] QString QProcess::nullDevice()

操作系统的空设备。

返回的文件路径使用本地目录分隔符。

另请参阅 QProcess::setStandardInputFile()、QProcess::setStandardOutputFile() 和QProcess::setStandardErrorFile()。

[override virtual] bool QProcess::open(QIODeviceBase::OpenMode mode = ReadWrite)

重实现:QIODevice::open(QIODeviceBase::OpenMode mode)。

使用setArguments() 设置的参数启动setProgram() 设置的程序。OpenMode 设置为mode

该方法是start() 的别名,仅用于完全实现QIODevice 定义的接口。

如果程序已启动,则返回true

另请参阅 start()、setProgram() 和setArguments()。

QProcess::ProcessChannelMode QProcess::processChannelMode() const

返回QProcess 标准输出和标准错误通道的通道模式。

另请参阅 setProcessChannelMode(),ProcessChannelMode, 和setReadChannel().

QProcessEnvironment QProcess::processEnvironment() const

返回QProcess 将传递给子进程的环境。如果没有使用setProcessEnvironment() 设置环境,此方法将返回一个对象,表明环境将从父进程继承。

另请参阅 setProcessEnvironment()、QProcessEnvironment::inheritsFromParent() 和Environment variables

qint64 QProcess::processId() const

返回正在运行的进程的本地进程标识符(如果有)。如果当前没有正在运行的进程,则返回0

QString QProcess::program() const

返回进程最后启动的程序。

另请参阅 setProgram() 和start()。

QByteArray QProcess::readAllStandardError()

无论当前读取通道如何,该函数都会以QByteArray 的形式返回进程标准错误中的所有可用数据。

另请参见 readyReadStandardError()、readAllStandardOutput()、readChannel() 和setReadChannel()。

QByteArray QProcess::readAllStandardOutput()

无论当前读取通道如何,该函数都会以QByteArray 的形式返回进程标准输出中的所有可用数据。

另请参见 readyReadStandardOutput()、readAllStandardError()、readChannel() 和setReadChannel()。

QProcess::ProcessChannel QProcess::readChannel() const

返回QProcess 的当前读取通道。

另请参阅 setReadChannel() 。

[override virtual protected] qint64 QProcess::readData(char *data, qint64 maxlen)

重实现:QIODevice::readData(char *data, qint64 maxSize)。

[private signal] void QProcess::readyReadStandardError()

当进程通过其标准错误通道 (stderr) 提供新数据时,就会发出该信号。无论当前read channel 与否,都会发出该信号。

注意: 这是一个私有信号。它可以在信号连接中使用,但不能由用户发出。

另请参阅 readAllStandardError() 和readChannel()。

[private signal] void QProcess::readyReadStandardOutput()

当进程通过其标准输出通道 (stdout) 提供新数据时,就会发出该信号。无论当前read channel 与否,都会发出该信号。

注意: 这是一个私有信号。它可以在信号连接中使用,但不能由用户发出。

另请参阅 readAllStandardOutput() 和readChannel()。

void QProcess::setArguments(const QStringList &arguments)

设置arguments ,以便在启动进程时传递给被调用程序。该函数必须在start() 之前调用。

另请参阅 start()、setProgram() 和arguments()。

[since 6.0] void QProcess::setChildProcessModifier(const std::function<void ()> &modifier)

为子进程设置modifier 函数,适用于 Unix 系统(包括 macOS;适用于 Windows,参见setCreateProcessArgumentsModifier() )。modifier 参数中包含的函数将在fork()vfork() 完成且QProcess 为子进程设置了标准文件描述符后,但在execve() 之前,在start() 中调用。

下面是一个设置子进程无权限运行的示例:

void runSandboxed(const QString &name, const QStringList &arguments)
{
    QProcess proc;
    proc.setChildProcessModifier([] {
        // Drop all privileges in the child process, and enter
        // a chroot jail.
        ::setgroups(0, nullptr);
        ::chroot("/run/safedir");
        ::chdir("/");
        ::setgid(safeGid);
        ::setuid(safeUid);
        ::umask(077);
    });
    proc.start(name, arguments);
    proc.waitForFinished();
}

如果修改器函数遇到故障情况,它可以使用failChildProcessModifier() 向QProcess 调用者报告情况。或者,它也可以使用其他方法停止进程,如_exit()abort()

子进程的某些属性,如关闭所有无关文件描述符或断开与控制 TTY 的连接,可以通过使用setUnixProcessParameters() 更容易地实现,它可以检测失败并报告FailedToStart 情况。修改器可用于更改子进程的某些不常用属性,如设置额外的文件描述符。如果同时设置了子进程修改器和 Unix 进程参数,则会在应用这些参数之前运行修改器。

注意: 在多线程应用程序中,该函数必须注意不要调用任何可能锁定其他线程正在使用的互斥的函数(一般来说,建议只使用 POSIX 定义为 "异步信号安全 "的函数)。在此回调中,包括qDebug() 在内的大部分 Qt XML API 都是不安全的,可能会导致死锁。

注意: 如果通过setUnixProcessParameters() 设置了 UnixProcessParameters::UseVFork(UnixProcessParameters::UseVFork)标志,QProcess 可能会使用vfork() 语义来启动子进程,因此该函数必须遵守更严格的约束。首先,由于该函数仍与父进程共享内存,它不得向任何非本地变量写入内容,并且在读取这些内容时必须遵守适当的排序语义,以避免数据竞赛。其次,甚至更多的库函数都可能出现错误行为;因此,该函数只能使用低级系统调用,如read(),write(),setsid(),nice() 等类似调用。

此函数在 Qt 6.0 中引入。

另请参见 childProcessModifier()、failChildProcessModifier() 和setUnixProcessParameters()。

void QProcess::setCreateProcessArgumentsModifier(QProcess::CreateProcessArgumentModifier modifier)

CreateProcess Win32 API 调用设置modifier 。通过QProcess::CreateProcessArgumentModifier() 可删除之前设置的值。

注: 此函数仅适用于 Windows 平台,需要 C++11。

另请参阅 createProcessArgumentsModifier(),QProcess::CreateProcessArgumentModifier, 和setChildProcessModifier().

void QProcess::setInputChannelMode(QProcess::InputChannelMode mode)

QProcess 标准输入通道的通道模式设置为指定的mode 。下次调用start() 时将使用该模式。

另请参阅 inputChannelMode() 和InputChannelMode

void QProcess::setNativeArguments(const QString &arguments)

这是一个重载函数。

为程序设置额外的本地命令行arguments

在操作系统中,将命令行arguments 传递给子进程的系统 API 本机使用的是单个字符串,因此可以设想无法通过QProcess 的基于可移植列表的 API 传递命令行。在这种情况下,必须使用本函数来设置一个字符串,该字符串将附加到由常规参数列表组成的字符串上,并用空格分隔。

注意: 该函数仅适用于 Windows 平台。

另请参阅 nativeArguments()。

void QProcess::setProcessChannelMode(QProcess::ProcessChannelMode mode)

QProcess 标准输出和标准错误通道的通道模式设置为指定的mode 。下次调用start() 时将使用该模式。例如

QProcessbuilder; builder.setProcessChannelMode(QProcess::MergedChannels); builder.start("make" QStringList()<< "-j2");if(!builder.waitForFinished())    qDebug() << "Make failed:" << builder.errorString();
不然    qDebug() << "Make output:" << builder.readAll();

另请参见 processChannelMode(),ProcessChannelMode, 和setReadChannel().

void QProcess::setProcessEnvironment(const QProcessEnvironment &environment)

设置QProcess 将传递给子进程的environment

例如,以下代码添加了环境变量TMPDIR

QProcess process;
QProcessEnvironment env = QProcessEnvironment::systemEnvironment();
env.insert("TMPDIR", "C:\\MyApp\\temp"); // Add an environment variable
process.setProcessEnvironment(env);
process.start("myapp");

请注意,在 Windows 系统中,环境变量名称是不区分大小写的。

另请参阅 processEnvironment(),QProcessEnvironment::systemEnvironment() 和Environment variables

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

QProcess 的当前状态设置为指定的state

另请参阅 state().

void QProcess::setProgram(const QString &program)

设置启动进程时使用的program 。该函数必须在start() 之前调用。

如果program 是绝对路径,它将指定启动的确切可执行文件。相对路径将以特定平台的方式解析,包括搜索PATH 环境变量(详见Finding the Executable )。

另请参阅 start()、setArguments()、program() 和QStandardPaths::findExecutable()。

void QProcess::setReadChannel(QProcess::ProcessChannel channel)

QProcess 的当前读取通道设置为给定的channel 。函数read() 、readAll() 、readLine() 和getChar() 会使用当前输入通道。它还决定哪个通道触发QProcess 发送readyRead()。

另请参见 readChannel()。

void QProcess::setStandardErrorFile(const QString &fileName, QIODeviceBase::OpenMode mode = Truncate)

将进程的标准错误重定向到文件fileName 。重定向到位后,标准错误读取通道将关闭:使用read() 和readAllStandardError() 从标准错误读取文件总是失败。如果mode 是 Append,文件将被追加,否则将被截断。

有关如何打开文件的更多信息,请参阅setStandardOutputFile() 。

注意:如果调用setProcessChannelMode() 时的参数为QProcess::MergedChannels ,则此函数不起作用。

另请参阅 setStandardInputFile()、setStandardOutputFile() 和setStandardOutputProcess()。

void QProcess::setStandardInputFile(const QString &fileName)

将进程的标准输入重定向到fileName 所指示的文件。当输入重定向到位时,QProcess 对象将处于只读模式(调用write() 将导致错误)。

要使进程立即读取 EOF,可在此处传递nullDevice() 。这比在写入任何数据前使用closeWriteChannel() 更简洁,因为它可以在启动进程前进行设置。

如果在调用start() 时,文件fileName 不存在或不可读,则启动进程将失败。

在进程启动后调用 setStandardInputFile() 没有任何作用。

另请参阅 setStandardOutputFile()、setStandardErrorFile() 和setStandardOutputProcess()。

void QProcess::setStandardOutputFile(const QString &fileName, QIODeviceBase::OpenMode mode = Truncate)

将进程的标准输出重定向到文件fileName 。重定向到位后,标准输出读取通道将关闭:使用read() 和readAllStandardOutput() 从标准输出读取将永远失败。

要放弃进程的所有标准输出,请在此处传递nullDevice() 。这比直接不读取标准输出更有效,因为不会填满QProcess 缓冲区。

如果在调用start() 时,文件fileName 不存在,则会被创建。如果无法创建,启动将失败。

如果文件存在且modeQIODeviceBase::Truncate ,文件将被截断。否则(如果modeQIODeviceBase::Append ),文件将被追加。

在进程启动后调用 setStandardOutputFile() 没有任何作用。

如果fileName 为空字符串,它将停止重定向标准输出。这对重定向后恢复标准输出非常有用。

另请参阅 setStandardInputFile()、setStandardErrorFile() 和setStandardOutputProcess()。

void QProcess::setStandardOutputProcess(QProcess *destination)

将该进程的标准输出流导入destination 进程的标准输入。

下面是 shell 命令:

command1 | command2

可通过QProcess 使用以下代码完成:

QProcess process1;
QProcess process2;

process1.setStandardOutputProcess(&process2);

process1.start("command1");
process2.start("command2");

[since 6.6] void QProcess::setUnixProcessParameters(const QProcess::UnixProcessParameters &params)

为 Unix 系统上的子进程设置额外的设置和参数,params 。该函数可用于要求QProcess 在启动目标可执行文件前修改子进程。

该函数可用于更改子进程的某些属性,如关闭所有无关文件描述符、更改子进程的友好级别或断开与控制 TTY 的连接。要对子进程进行更精细的控制或以其他方式进行修改,请使用setChildProcessModifier() 函数。如果同时设置了子进程修改器和 Unix 进程参数,则在应用这些参数之前先运行修改器。

注意: 此函数仅适用于 Unix 平台。

此函数在 Qt 6.6 中引入。

另请参阅 unixProcessParameters() 和setChildProcessModifier()。

[since 6.6] void QProcess::setUnixProcessParameters(QProcess::UnixProcessFlags flagsOnly)

这是一个重载函数。

在 Unix 系统上将子进程的额外设置设置为flagsOnly 。这与只设置flags 字段的重载相同。

注意: 此函数仅适用于 Unix 平台。

该函数在 Qt 6.6 中引入。

另请参阅 unixProcessParameters() 和setChildProcessModifier()。

void QProcess::setWorkingDirectory(const QString &dir)

dir QProcess 将在此目录下启动进程。默认行为是在调用进程的工作目录下启动进程。

另请参阅 workingDirectory() 和start()。

[static] QStringList QProcess::splitCommand(QStringView command)

将字符串command 分割成一个标记列表,并返回该列表。

带有空格的标记可以用双引号包围;三个连续的双引号代表引号字符本身。

void QProcess::start(const QString &program, const QStringList &arguments = {}, QIODeviceBase::OpenMode mode = ReadWrite)

在一个新进程中启动给定的program ,在arguments 中传递命令行参数。关于QProcess 如何搜索要运行的可执行文件,请参阅setProgram() 。OpenMode 设置为mode 。不会进一步拆分参数。

QProcess 对象将立即进入启动状态。如果进程启动成功,QProcess 将发出started() ;否则将发出errorOccurred() 。请注意,在可以同步启动子进程的平台上(尤其是 Windows),这些信号将在此函数返回之前发出,而QProcess 对象将分别过渡到QProcess::RunningQProcess::NotRunning 状态。在其他平台上,started() 和errorOccurred() 信号将被延迟。

调用waitForStarted() 可确保进程已启动(或启动失败),并且这些信号已发出。即使已经知道进程的启动状态,调用该函数也是安全的,尽管信号不会再次发出。

窗口参数会被加引号并连接到与CommandLineToArgvW() Windows 函数兼容的命令行中。对于命令行引号要求不同的程序,需要使用setNativeArguments() 。cmd.exe 以及所有批处理脚本都不遵循CommandLineToArgvW() 规则。

如果QProcess 对象已在运行一个进程,控制台可能会打印出警告,但现有进程将不受影响地继续运行。

注意: 成功启动子进程仅意味着操作系统已成功创建进程并分配了每个进程都有的资源,如进程 ID。子进程可能会很早就崩溃或以其他方式失败,从而无法产生预期输出。在大多数操作系统中,这可能包括动态链接错误。

另请参阅 processId()、started()、waitForStarted() 和setNativeArguments() 。

void QProcess::start(QIODeviceBase::OpenMode mode = ReadWrite)

这是一个重载函数。

使用setArguments() 设置的参数启动setProgram() 设置的程序。OpenMode 设置为mode

另请参阅 open()、setProgram() 和setArguments()。

[since 6.0] void QProcess::startCommand(const QString &command, QIODeviceBase::OpenMode mode = ReadWrite)

在新进程中启动command 命令。OpenMode 设置为mode

command 是一个包含程序名称及其参数的文本字符串。参数之间用一个或多个空格隔开。例如

QProcess process;
process.startCommand("del /s *.txt");
// same as process.start("del", QStringList() << "/s" << "*.txt");
...

包含空格的参数必须加引号才能正确提供给新进程。例如

QProcess process;
process.startCommand("dir \"My Documents\"");

command 字符串中的字面引号用三个引号表示。例如

QProcess process;
process.startCommand("dir \"Epic 12\"\"\" Singles\"");

command 字符串被拆分并取消引号后,该函数的行为与start() 类似。

在将命令行参数传递给子进程的系统 API 本身使用单个字符串的操作系统(Windows)上,可以设想无法通过QProcess 的可移植基于列表的 API 传递命令行。在这些罕见的情况下,您需要使用setProgram() 和setNativeArguments() 代替此函数。

此函数在 Qt 6.0 中引入。

另请参阅 splitCommand() 和start()。

bool QProcess::startDetached(qint64 *pid = nullptr)

setArguments() 设置的参数在一个新进程中启动setProgram() 设置的程序,并从中分离。成功时返回true ,否则返回false 。如果调用进程退出,分离的进程将不受影响地继续运行。

Unix:启动的进程将在自己的会话中运行,就像一个守护进程。

进程将在setWorkingDirectory() 设置的目录中启动。如果workingDirectory() 为空,工作目录将从调用进程继承。

如果函数执行成功,*pid 将被设置为已启动进程的进程标识符;否则,将被设置为-1。需要注意的是,子进程可能会退出,PID 也可能在不经意间变为无效。此外,子进程退出后,相同的 PID 可能会被回收,并被完全不同的进程使用。用户代码在使用该变量时应小心谨慎,尤其是在打算通过操作系统手段强制终止进程时。

startDetached() 仅支持以下属性设置:

QProcess 对象的所有其他属性都将被忽略。

注意: 被调用进程继承调用进程的控制台窗口。要抑制控制台输出,请将标准/错误输出重定向到QProcess::nullDevice() 。

另请参阅 start() 和startDetached(const QString &program, const QStringList &arguments, const QString &workingDirectory, qint64 *pid)。

[static] bool QProcess::startDetached(const QString &program, const QStringList &arguments = {}, const QString &workingDirectory = QString(), qint64 *pid = nullptr)

此函数重载 startDetached()。

使用参数arguments 在新进程中启动程序program ,并从中分离。成功时返回true ,否则返回false 。如果调用进程退出,分离的进程将不受影响地继续运行。

参数处理与start() 的重载相同。

进程将在workingDirectory 目录中启动。如果workingDirectory 为空,工作目录将从调用进程继承。

如果函数执行成功,*pid 将被设置为已启动进程的进程标识符。

另请参阅 start() 。

[private signal] void QProcess::started()

QProcess 在进程启动时发出该信号,state() 返回Running

注意: 这是一个私有信号。可以在信号连接中使用,但用户不能发出。

QProcess::ProcessState QProcess::state() const

返回进程的当前状态。

另请参阅 stateChanged() 和error()。

[private signal] void QProcess::stateChanged(QProcess::ProcessState newState)

每当QProcess 的状态发生变化时,就会发出该信号。newState 参数是QProcess 变为的状态。

注意: 这是一个私有信号。可以在信号连接中使用,但用户不能发出。

[static] QStringList QProcess::systemEnvironment()

以键=值对列表的形式返回调用进程的环境。举例说明

QStringList environment = QProcess::systemEnvironment();
// environment = {"PATH=/usr/bin:/usr/local/bin",
//                "USER=greg", "HOME=/home/greg"}

此函数不缓存系统环境。因此,如果调用了setenvputenv 等低级 C 库函数,则有可能获得环境的更新版本。

但要注意的是,重复调用该函数将重新创建环境变量列表,这是一个非繁琐的操作。

注意: 对于新代码,建议使用QProcessEnvironment::systemEnvironment()

另请参阅 QProcessEnvironment::systemEnvironment() 和setProcessEnvironment()。

[slot] void QProcess::terminate()

试图终止进程。

进程可能不会因为调用此函数而退出(它有机会提示用户任何未保存的文件等)。

在 Windows 系统中,terminate() 会向进程的所有顶级窗口发送一条 WM_CLOSE 消息,然后发送给进程本身的主线程。在 Unix 和 macOS 上,则会发送SIGTERM 信号。

在 Windows 上,如果控制台应用程序没有运行事件循环,或其事件循环没有处理 WM_CLOSE 消息,则只能通过调用kill() 来终止。

另请参阅 kill()。

[noexcept, since 6.6] QProcess::UnixProcessParameters QProcess::unixProcessParameters() const

返回UnixProcessParameters 对象,该对象描述了将应用于 Unix 系统子进程的额外标志和设置。默认设置与默认构建的UnixProcessParameters 对应。

注意: 此函数仅适用于 Unix 平台。

该函数在 Qt 6.6 中引入。

另请参阅 setUnixProcessParameters() 和childProcessModifier()。

[override virtual] bool QProcess::waitForBytesWritten(int msecs = 30000)

重实现:QIODevice::waitForBytesWritten(int msecs)。

bool QProcess::waitForFinished(int msecs = 30000)

阻塞,直至进程结束且finished() 信号发出,或msecs 毫秒已过。

如果进程结束,则返回true ;否则返回false (如果操作超时、发生错误或QProcess 已经结束)。

该函数可以在没有事件循环的情况下运行。在编写非图形用户界面应用程序和在非图形用户界面线程中执行 I/O 操作时,该函数非常有用。

警告: 从主(GUI)线程调用此函数可能会导致用户界面冻结。

如果 msecs 为-1,则此函数不会超时。

另请参阅 finished()、waitForStarted()、waitForReadyRead() 和waitForBytesWritten()。

[override virtual] bool QProcess::waitForReadyRead(int msecs = 30000)

重实现:QIODevice::waitForReadyRead(int msecs)。

bool QProcess::waitForStarted(int msecs = 30000)

阻塞直到进程启动且started() 信号发出,或直到msecs 毫秒过去。

如果进程启动成功,则返回true ;否则返回false (如果操作超时或发生错误)。如果进程在此函数之前已经成功启动,则立即返回。

该函数可以在没有事件循环的情况下运行。在编写非图形用户界面应用程序和在非图形用户界面线程中执行 I/O 操作时,该函数非常有用。

警告 从主(GUI)线程调用此函数可能会导致用户界面冻结。

如果 msecs 为-1,则此函数不会超时。

另请参阅 started()、waitForReadyRead()、waitForBytesWritten() 和waitForFinished()。

QString QProcess::workingDirectory() const

如果QProcess 已分配了工作目录,则该函数返回QProcess 在程序启动前将进入的工作目录。否则(即未分配目录),将返回空字符串,QProcess 将使用应用程序的当前工作目录。

另请参阅 setWorkingDirectory() 。

© 2025 The Qt Company Ltd. Documentation contributions included herein are the copyrights of their respective owners. The documentation provided herein is licensed under the terms of the GNU Free Documentation License version 1.3 as published by the Free Software Foundation. Qt and respective logos are trademarks of The Qt Company Ltd. in Finland and/or other countries worldwide. All other trademarks are property of their respective owners.