QProcess 类

QProcess 类用于启动外部程序并与它们进行通信。 更多...

头文件 #include <QProcess>
CMakefind_package(Qt6 REQUIRED COMPONENTS Core)
target_link_libraries(mytarget PRIVATE Qt6::Core)
qmakeQT += core
继承自 QIODevice

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

公共类型

结构体CreateProcessArguments
(自 6.6) 结构体UnixProcessParameters
CreateProcessArgumentModifier
枚举ExitStatus { NormalExit, CrashExit }
枚举InputChannelMode { ManagedInputChannel, ForwardedInputChannel }
枚举ProcessChannel { StandardOutput, StandardError }
枚举ProcessChannelMode { SeparateChannels, MergedChannels, ForwardedChannels, ForwardedErrorChannel, ForwardedOutputChannel }
枚举ProcessError { FailedToStart, Crashed, Timedout, WriteError, ReadError, UnknownError }
枚举ProcessState { NotRunning, Starting, Running }
(自 6.6) 枚举类UnixProcessFlag { CloseFileDescriptors, CreateNewSession, DisconnectControllingTerminal, IgnoreSigPipe, ResetIds, …, UseVFork }
标志UnixProcessFlags

公共函数

QProcess(QObject *parent = nullptr)
虚拟~QProcess()
QStringListarguments() const
(自 6.0) std::function<void ()>childProcessModifier() const
voidcloseReadChannel(QProcess::ProcessChannel channel)
voidcloseWriteChannel()
QProcess::CreateProcessArgumentModifiercreateProcessArgumentsModifier() const
QProcess::ProcessErrorerror() const
intexitCode() const
QProcess::ExitStatusexitStatus() const
(自 6.7) voidfailChildProcessModifier(const char *description, int error = 0)
QProcess::InputChannelModeinputChannelMode() const
QStringnativeArguments() const
QProcess::ProcessChannelModeprocessChannelMode() const
QProcessEnvironmentprocessEnvironment() const
qint64processId() const
QString程序() const
QStringArrayreadAllStandardError()
QStringArrayreadAllStandardOutput()
QProcess::ProcessChannelreadChannel() const
voidsetArguments(const QStringList &arguments)
(since 6.0) voidsetChildProcessModifier(const std::function&modifier)
voidsetCreateProcessArgumentsModifier(QProcess::CreateProcessArgumentModifier modifier)
voidsetInputChannelMode(QProcess::InputChannelMode mode)
voidsetNativeArguments(const QString &arguments)
voidsetProcessChannelMode(QProcess::ProcessChannelMode mode)
voidsetProcessEnvironment(const QProcessEnvironment &environment)
voidsetProgram(const QString &program)
voidsetReadChannel(QProcess::ProcessChannel channel)
voidsetStandardErrorFile(const QString &fileName, QIODeviceBase::OpenMode mode = Truncate)
voidsetStandardInputFile(const QString &fileName)
voidsetStandardOutputFile(const QString &fileName, QIODeviceBase::OpenMode mode = Truncate)
voidsetStandardOutputProcess(QProcess *destination)
(since 6.6) voidsetUnixProcessParameters(const QProcess::UnixProcessParameters &params)
(since 6.6) voidsetUnixProcessParameters(QProcess::UnixProcessFlags flagsOnly)
voidsetWorkingDirectory(const QString &dir)
voidstart(const QString &program, const QStringList &arguments = {}, QIODeviceBase::OpenMode mode = ReadWrite)
voidstart(QIODeviceBase::OpenMode mode = ReadWrite)
(since 6.0) voidstartCommand(const QString &command, QIODeviceBase::OpenMode mode = ReadWrite)
boolstartDetached(qint64 *pid = nullptr)
QProcess::ProcessStatestate() const
(since 6.6) QProcess::UnixProcessParametersunixProcessParameters() const
boolwaitForFinished(int msecs = 30000)
boolwaitForStarted(int msecs = 30000)
QStringworkingDirectory() const

重实现公共函数

virtual qint64bytesToWrite() const override
virtual voidclose() override
virtual boolisSequential() const override
virtual boolvirtual void
virtual boolopen(QIODeviceBase::OpenMode mode = ReadWrite) override
virtual boolvirtual bool

waitForBytesWritten(int msecs = 30000) override

voidvirtual bool()
voidwaitForReadyRead(int msecs = 30000) override()

公共槽

voidkill
voidterminate
void信号()
voiderrorOccurred(QProcess::ProcessError error)()
voidfinished(int exitCode, QProcess::ExitStatus exitStatus = NormalExit)()
voidreadyReadStandardError

readyReadStandardOutput

intstarted
QStringstateChanged(QProcess::ProcessState newState)()
QStringListsplitCommand(QStringView command)
boolstartDetached(const QString &program, const QStringList &arguments = {}, const QString &workingDirectory = QString(), qint64 *pid = nullptr)
QStringList系统环境变量()

受保护函数

voidsetProcessState(QProcess::ProcessState state)

重实现的受保护函数

virtual qint64readData(char *data, qint64 maxlen) override
virtual qint64writeData(const char *data, qint64 len) override

详细描述

运行进程

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

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

例如,以下代码片段通过将包含"-style"和"fusion"的字符串作为列表中的两个项目运行X11平台上的模拟时钟示例

    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()读取标准输出。因为QProcess继承自QIODevice,所以QProcess还可以用作QXmlReader的输入源,或用于生成使用QNetworkAccessManager上传的数据。

当进程退出时,QProcess将重新进入NotRunning状态(初始状态),并发出finished事件。

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

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

查找可执行文件

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

QProcess以类似于Unix壳和Windows命令解释器在各自的命令行中操作的其中三种不同方式之一来解析程序名。

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

为了避免平台相关的行为或与当前应用程序启动方式相关的任何问题,建议始终传递要启动的可执行文件的绝对路径。对于与应用程序一起分发的辅助二进制文件,可以使用 QCoreApplication::applicationDirPath() 构建此路径。同样,为了明确运行相对于 setWorkingDirectory() 设置的目录的可执行文件,请使用以 "./" 或 "../" 开头的程序路径,具体取决于情况。

在Windows上,大多数情况下不需要".exe"后缀,除非在CreateProcess 文档中概述的使用。此外,QProcess会将Unix风格的正斜杠转换为Windows路径的转义反斜杠,为程序名。这使得使用QProcess编写的代码具有跨平台性,如上面的示例所示。

QProcess不支持直接执行Unix壳或Windows命令解释器的内建函数,例如“cmd.exe”的“dir”命令或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 将在启动时使用该环境为子进程。

常规场景是从当前环境通过调用 QProcessEnvironment::systemEnvironment() 开始,然后添加、更改或删除特定变量。然后将结果变量列表应用于 QProcess,以便通过 setProcessEnvironment()。

可以使用 QProcessEnvironment() 默认构造函数从环境中删除所有变量或从空环境开始,但这在受控和特定于系统的条件下不推荐,因为可能存在设置在当前进程环境中的系统变量,这些变量对于子进程的正确执行是必需的。

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

通过通道通信

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

通道的术语可能会令人误解。请注意,进程的输出通道对应于 QProcess 的 read 通道,而进程的输入通道对应于 QProcess 的 write 通道。这是因为我们使用 QProcess 读取的是进程的输出,而我们写入的成为进程的输入。

QProcess 可以合并两个输出通道,从而使正在运行的过程的标准输出和标准错误数据都使用标准输出通道。在启动进程之前,通过调用 setProcessChannelMode() 并使用 MergedChannels 来启用此功能。您还可以通过将 ForwardedChannels 作为参数传递来将正在运行的过程的输出转发到调用进程。还可以仅转发一个输出通道 - 通常人们会使用 ForwardedErrorChannel,但 ForwardedOutputChannel 也存在。请注意,在 GUI 应用程序中通常不建议使用通道转发 - 您应该以图形方式显示错误。

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

使用 QProcess 启动的 GUI 应用程序所属窗口的定位和屏幕 Z 序列由底层窗口系统控制。对于 Qt 5 应用程序,可以使用 -qwindowgeometry 命令行选项指定位置;X11 应用程序通常接受 -geometry 命令行选项。

同步进程 API

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 将重用进程 A 的控制台窗口作为进程 B。在此示例中,为子进程 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().

枚举 QProcess::ExitStatus

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

常量描述
QProcess::NormalExit0进程正常退出。
QProcess::CrashExit1进程崩溃。

另请参阅 exitStatus().

枚举 QProcess::InputChannelMode

此枚举描述了 QProcess 的进程输入通道模式。将其中一个这些值传递给 setInputChannelMode() 以设置当前写入通道模式。

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

另请参阅 setInputChannelMode().

枚举 QProcess::ProcessChannel

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

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

另请参阅 setReadChannel().

枚举 QProcess::ProcessChannelMode

此枚举描述了 QProcess 的进程输出通道模式。将其中一个这些值传递给 setProcessChannelMode() 以设置当前读取通道模式。

常量描述
QProcess::SeparateChannels0QProcess 管理正在运行进程的输出,将标准输出和标准错误数据保留在单独的内部缓冲区中。您可以通过调用 setReadChannel() 来选择 QProcess 的当前读取通道。这是 QProcess 的默认通道模式。
QProcess::MergedChannels1QProcess 将正在运行进程的输出合并到标准输出通道(stdout)。标准错误通道(stderr)将不会接收任何数据。运行进程的标准输出和标准错误数据将交错。对于分离的进程,正在运行进程的合并输出将被转发到主进程。
QProcess::ForwardedChannels2QProcess 将正在运行进程的输出转发到主进程。子进程写入其标准输出和标准错误的内容也将写入主进程的标准输出和标准错误。
QProcess::ForwardedErrorChannel4QProcess 管理正在运行进程的标准输出,但其标准错误将被转发到主进程。这反映了命令行工具作为过滤器使用的典型用法,其中标准输出被重定向到另一个进程或文件,而标准错误被打印到控制台以进行诊断目的。(此值在 Qt 5.2 中引入。)
QProcess::ForwardedOutputChannel3与ForwardedErrorChannel 相辅相成。(此值在Qt 5.2中引入。)

注意:Windows 故意抑制仅GUI应用程序向继承控制台输出的内容。这 不适用 于重定向到文件或管道的输出。尽管如此,要仍然在控制台上转发仅GUI应用程序的输出,您必须使用SeparateChannels,并通过读取输出并将其写入适当的输出通道自行转发。

另请参阅:setProcessChannelMode()。

枚举 QProcess::ProcessError

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

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

另请参阅:error()。

枚举 QProcess::ProcessState

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

常量描述
QProcess::NotRunning0进程未运行。
QProcess::Starting1进程正在启动,但程序尚未被调用。
QProcess::Running2进程正在运行并准备好读取和写入。

另请参阅:state()。

[since 6.6] 枚举类 QProcess::UnixProcessFlag
标志 QProcess::UnixProcessFlags

这些标志可用于 UnixProcessParametersflags 字段。

常量描述
QProcess::UnixProcessFlag::CloseFileDescriptors0x0010关闭所有高于 lowestFileDescriptorToClose 定义的阈值的文件描述符,防止任何当前在父进程中打开的描述符意外泄漏到子进程。stdin、stdout 和 stderr 文件描述符从不关闭。
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 (从 Qt 6.7 开始)0x0100删除当前进程可能仍保留的任何保留用户或组 ID(参见 setuid(2)setgid(2),以及 QCoreApplication::setSetuidAllowed()). 如果当前进程已设置为 setuid 或 setgid 而不希望子进程保留提升的权限,则此功能非常有用。
QProcess::UnixProcessFlag::ResetSignalHandlers0x0001将所有 Unix 信号处理程序重置为其默认状态(即,将 SIG_DFL 传递给 signal(2))。此标志有助于确保任何被忽略的 (SIG_IGN) 信号不会影响子进程的行为。
QProcess::UnixProcessFlag::UseVFork0x0020请求 QProcess 使用 vfork(2) 启动子进程。使用此标志来指示使用 setChildProcessModifier() 设置的回调函数在 vfork(2) 的子进程中是安全的;也就是说,回调不修改任何非局部变量(直接或通过它调用的任何函数),也不尝试与父进程通信。是否实际使用 vfork(2) 以及它与标准 fork(2) 是否不同,取决于实现。

此枚举在 Qt 6.6 中引入。

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

另请参阅 setUnixProcessParameters() 和 unixProcessParameters

成员函数文档

[显式构造函数] QProcess::QProcess(QObject *parent = nullptr)

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

[虚拟 noexcept 析构函数] QProcess::~QProcess()

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

请注意,此函数将不会返回直到进程被终止。

QStringList QProcess::arguments() const

返回进程上次启动时使用的命令行参数。

另请参阅 setArguments() 和 start

[重写虚拟] qint64 QProcess::bytesToWrite() const

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

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

返回先前通过调用 setChildProcessModifier() 设置的修饰函数。

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

此函数是在 Qt 6.0 中引入的。

参阅:setChildProcessModifier() 和 unixProcessParameters

[重载虚函数] void QProcess::close()

重实现:QIODevice::close

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

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

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

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

参阅:closeWriteChannelsetReadChannel

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 平台。

参阅:setCreateProcessArgumentsModifierQProcess::CreateProcessArgumentModifier

QProcess::ProcessError QProcess::error() const

返回上次出错的类型。

另请参阅:state()。

[信号] void QProcess::errorOccurred(QProcess::ProcessError error)

当进程发生错误时,会发出此信号。指定的 error 描述了发生的错误类型。

[静态] 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()终止,则此函数仍将返回NormalExit,除非退出代码小于0。

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

此函数可用于setChildProcessModifier()中指定的修饰器集中,以指示遇到错误条件。当修饰器调用这些函数时,在父进程中QProcess将使用代码QProcess::FailedToStart触发errorOccurred()。可以使用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()可能为"子进程修饰器报告错误:辅助通信通道:文件描述符错误"。

此函数不会返回给调用者。除了在子修饰器和正确的QProcess对象中使用,其他任何使用都是未定义行为。

注意:实现中对description参数施加了长度限制,约为500个字符。此限制不包括错误代码的文本。

此功能是在Qt 6.7中引入的。

参见setChildProcessModifier()和setUnixProcessParameters

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

当进程完成后,此信号将被触发。exitCode是进程的退出代码(仅对正常退出有效),exitStatus是退出状态。在进程完成后,QProcess中的缓冲区仍然完好。您仍然可以读取进程完成前可能写入的任何数据。

另请参阅 exitStatus().

QProcess::InputChannelMode QProcess::inputChannelMode() const

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

另请参阅setInputChannelMode() 和 InputChannelMode.

[重写虚函数] bool QProcess::isSequential() const

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

[槽函数] void QProcess::kill()

终止当前进程,使其立即退出。

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

另请参阅terminate.

QString QProcess::nativeArguments() const

返回程序的额外本地命令行参数。

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

另请参阅setNativeArguments.

[静态] QString QProcess::nullDevice()

操作系统的空设备。

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

另请参阅QProcess::setStandardInputFile(),QProcess::setStandardOutputFile() 和 QProcess::setStandardErrorFile.

[重写虚函数] bool QProcess::open(QIODeviceBase::OpenMode mode = ReadWrite)

重新实现了: QIODevice::open(QIODeviceBase::OpenMode mode).

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

此方法是对 start() 的别名,仅存在是为了完全实现由 QIODevice 定义的接口。

如果程序已启动,返回 true

另请参阅start(),setProgram() 和 setArguments.

QProcess::ProcessChannelMode QProcess::processChannelMode() const

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

另请参阅setProcessChannelMode(),ProcessChannelModesetReadChannel.

QProcessEnvironment QProcess::processEnvironment() const

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

另请参阅setProcessEnvironment(),QProcessEnvironment::inheritsFromParent() 和 环境变量

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

[重写虚拟受保护] qint64 QProcess::readData(char *data, qint64 maxlen)

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

[私有信号] void QProcess::readyReadStandardError()

当进程通过其标准错误通道(stderr)提供新的数据时,将发出此信号。无论当前的 读取通道 如何,都会发出此信号。

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

另请参阅 readAllStandardError() 和 readChannel

[私有信号] void QProcess::readyReadStandardOutput()

当进程通过其标准输出通道(stdout)提供新的数据时,将发出此信号。无论当前的 读取通道 如何,都会发出此信号。

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

另请参阅 readAllStandardOutput() 和 readChannel

void QProcess::setArguments(const QStringList &arguments)

在启动进程时设置传递给调用程序的 arguments。必须在 start() 调用之前调用此函数。

另请参阅 start(),setProgramarguments

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

为子进程设置modifier函数,适用于Unix系统(包括macOS;对于Windows,请参阅setCreateProcessArgumentsModifier())。modifier参数所包含的函数将在完成fork()vfork()之后,但QProcess设置子进程的标准文件描述符之前,在内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();
}

如果modifier函数遇到失败情况,可以使用failChildProcessModifier()将情况报告给QProcess调用者。或者,它也可以使用其他停止进程的方法,如_exit()abort()

通过使用setUnixProcessParameters(),可以更方便地实现某些子进程属性,例如关闭所有多余的文件描述符或从控制TTY断开连接。该修饰符适用于更改某些不常见的子进程属性,例如设置额外的文件描述符。如果同时设置了子进程修饰符和Unix进程参数,则修饰符将在应用这些参数之前运行。

注意:在多线程应用程序中,此函数必须小心不要调用任何可能锁定可能在其他线程中使用的互斥锁的函数(通常建议只使用由POSIX定义为“async-signal-safe”的函数)。大多数Qt API在此回调中都是不安全的,包括qDebug(),可能导致死锁。

注意:如果在setUnixProcessParameters()中通过QProcess设置UnixProcessParameters::UseVFork标志,则该函数可能使用vfork()语义来启动子进程,因此必须遵守甚至更严格的约束。首先,因为它仍然与父进程共享内存,所以它不能写入任何非局部变量,并且在从中读取时必须遵守适当的顺序语义,以避免数据竞争。其次,更多的库函数可能表现出不正常的行为;因此,此函数应该只使用低级系统调用,如read()write()setsid()nice()和类似调用。

此函数是在 Qt 6.0 中引入的。

另见:childProcessModifierfailChildProcessModifiersetUnixProcessParameters

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

为Win32 API调用CreateProcess设置modifier。传递QProcess::CreateProcessArgumentModifier()以删除以前设置的任何值。

注意:此功能仅在Windows平台上可用,并需要C++11。

另见:createProcessArgumentsModifierQProcess::CreateProcessArgumentModifiersetChildProcessModifier

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

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

请参阅inputChannelMode() 和 InputChannelMode

void QProcess::setNativeArguments(const QString &arguments)

这是一个重载函数。

为程序设置额外的原生命令行 arguments

在系统API用到单个字符串通过原生方式传递命令行参数到子进程的操作系统上,可能会遇到无法通过 QProcess 的可移植列表型 API 传递的命令行。在这种情况下,必须使用此函数来设置一个字符串,该字符串将作为一个分隔空格附接到由常规参数列表组成的字符串之后。

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

请参阅nativeArguments

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

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

QProcess builder;
builder.setProcessChannelMode(QProcess::MergedChannels);
builder.start("make", QStringList() << "-j2");

if (!builder.waitForFinished())
    qDebug() << "Make failed:" << builder.errorString();
else
    qDebug() << "Make output:" << builder.readAll();

请参阅processChannelMode(),ProcessChannelModesetReadChannel

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() 和 环境变量

[受保护] 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

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

另请参阅setStandardInputFilesetStandardOutputFilesetStandardOutputProcess

void QProcess::setStandardInputFile(const QString &fileName)

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

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

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

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

另请参阅setStandardOutputFilesetStandardErrorFilesetStandardOutputProcess

void QProcess::setStandardOutputFile(const QString &">fileNameQIODeviceBase::OpenMode mode = Truncate)

将进程的标准输出重定向到文件 fileName。当重定向就绪时,标准输出读取通道将关闭:使用 read() 从它读取将始终失败,同样 readAllStandardOutput 也将失败。

为了丢弃进程的所有标准输出,请在此处传递 nullDevice()。这比简单地永不读取标准输出更高效,因为没有填充 QProcess 缓冲区。

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

如果文件存在且模式设置为QIODevice::Truncate,则文件将被截断。否则(如果模式设置为QIODevice::Append),文件将被追加。

在进程开始后调用setStandardOutputFile()没有任何效果。

如果文件名是一个空字符串,将停止重定向标准输出。这对于在重定向后恢复标准输出很有用。

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

void QProcess::setStandardOutputProcess(QProcess *destination)

将此进程的标准输出流管道传输到目的进程的标准输入。

以下shell命令

command1 | command2

可以使用QProcess配合以下代码实现

QProcess process1;
QProcess process2;

process1.setStandardOutputProcess(&process2);

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

[自6.6以来] void QProcess::setUnixProcessParameters(const QProcess::UnixProcessParameters &params)

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

此函数可用于更改子进程的某些属性,例如关闭所有多余的文件描述符、更改子进程的优先级或从控制TTY断开连接。要更精细地控制子进程或在其他方式中修改它,请使用setChildProcessModifier()函数。如果同时设置了子进程修改器和Unix进程参数,则修改器将在应用这些参数之前运行。

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

此函数是在Qt 6.6中引入的。

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

[自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()。

[静态] QStringList QProcess::splitCommand(QStringView command)

将字符串command拆分为标记列表并返回该列表。

空格周围的标记可以包含在双引号内;连续的三个双引号表示引号字符本身。

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

在新进程中启动指定的程序,并将命令行参数传递到arguments中。有关QProcess如何搜索要运行的执行文件的详细信息,请参阅setProgram()函数。OpenMode被设置为mode。不会对这些参数进行进一步拆分。

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

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

Windows: 这些参数被引号括起来,并合并到与Windows函数CommandLineToArgvW()兼容的命令行中。对于具有不同命令行引号要求的程序,您需要使用setNativeArguments()。一个不遵循CommandLineToArgvW()规则的著名程序是cmd.exe,因此所有批处理脚本也是如此。

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

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

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

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

这是一个重载函数。

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

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

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

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

命令 是一个包含程序名称及其参数的单个字符串。参数由一个或多个空格分隔。例如

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

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

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

命令 字符串中的字面引号表示为三重引号。例如

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

在将 命令 字符串分割并取消引号后,此函数的行为类似于 start ()。

在操作系统中,系统 API 用于将命令行参数原生前传给子进程是使用单个字符串(Windows),可以形象地想要通过 QProcess 的便携式基于列表的 API 传递的命令行。在这些罕见情况下,您需要使用 setProgram () 和 setNativeArguments () 替代此函数。

此函数是在 Qt 6.0 中引入的。

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

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

在新的进程中以 setProgram () 设置的程序和 setArguments () 设置的参数启动程序,并从中分离出来。成功返回 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)。

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

此函数重载 startDetached ()。

以新进程启动程序,并用参数运行,然后与它断开连接。成功时返回true;否则返回false。如果调用进程退出,则断开的进程将不受影响地继续运行。

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

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

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

参见start()。

[私有信号] void QProcess::started()

当进程启动且state()返回Running时,QProcess会发出此信号。

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

QProcess::ProcessState QProcess::state() const

返回进程的当前状态。

另请参阅stateChanged() 和 error

[私有信号] void QProcess::stateChanged(QProcess::ProcessState newState)

每次QProcess的QProcess状态改变时都会发出此信号。参数newStateQProcess改变了到的新状态。

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

[静态] 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

[槽函数] void QProcess::terminate()

尝试终止进程。

调用此函数不一定会导致进程退出(它将有机会提示用户保存未保存的文件等)。

在Windows上,terminate()将向进程的所有顶级窗口以及主线程自身发送WM_CLOSE消息。在Unix和macOS上,发送SIGTERM信号。

在Windows上不运行事件循环或事件循环不处理WM_CLOSE消息的控制台应用程序可以通过调用kill()来终止。

另请参阅kill

[noexcept, 自6.6以来] QProcess::UnixProcessParameters QProcess::unixProcessParameters() const

返回描述在Unix系统上将应用于子进程的额外标志和设置的UnixProcessParameters对象。默认设置对应于默认构造的UnixProcessParameters

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

此函数是在Qt 6.6中引入的。

另请参阅setUnixProcessParameters() 和 childProcessModifier

[重写虚函数] bool QProcess::waitForBytesWritten(int msecs = 30000)

重实现了: QIODevice::waitForBytesWritten(int msecs).

bool QProcess::waitForFinished(int msecs = 30000)

阻塞直到进程完成并发出 finished() 信号,或者直到经过 msecs 毫秒。

如果进程完成,则返回 true;否则返回 false(如果操作超时,如果发生错误,或者如果这个 QProcess 已经完成)。

此函数可以在没有事件循环的情况下运行。当编写非GUI应用程序以及在非GUI线程中执行I/O操作时非常有用。

警告:在主(GUI)线程中调用此函数可能会使您的用户界面冻结。

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

另请参阅:finished(),waitForStarted(),waitForReadyRead() 和 waitForBytesWritten

[重写虚函数] bool QProcess::waitForReadyRead(int msecs = 30000)

重实现了:QIODevice::waitForReadyRead(int msecs).

bool QProcess::waitForStarted(int msecs = 30000)

阻塞直到进程开始并发出 started() 信号,或者直到经过 msecs 毫秒。

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

此函数可以在没有事件循环的情况下运行。当编写非GUI应用程序以及在非GUI线程中执行I/O操作时非常有用。

警告:在主(GUI)线程中调用此函数可能会使您的用户界面冻结。

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

另请参阅:started(),waitForReadyRead(),waitForBytesWrittenwaitForFinished

QString QProcess::workingDirectory() const

如果已为 QProcess 指定工作目录,则此函数将返回 QProcess 在程序开始之前将进入的工作目录。如果没有分配目录,则返回空字符串,且 QProcess 将使用应用程序的当前工作目录。

另请参阅:setWorkingDirectory

[重写虚保护] qint64 QProcess::writeData(const char *data, qint64 len)

重实现了:QIODevice::writeData(const char *data, qint64 maxSize).

© 2024 Qt公司有限公司。此处包含的文档贡献的版权归各自所有者所有。此处提供的文档根据自由软件基金会发布的 GNU自由文档许可证版本1.3 的条件许可。Qt及其相关标志是芬兰的 Qt公司及其在大中华区及其他国家/地区的商标。所有其他商标均为其各自所有者的财产。