QProcess 类用于启动外部程序并与之通信。 更多...
头: | #include <QProcess> |
CMake: |
find_package(Qt6 REQUIRED COMPONENTS Core)
target_link_libraries(mytarget PRIVATE Qt6::Core) |
qmake: | QT += core |
继承: | QIODevice |
注意: 此类的所有函数 可重入 .
struct | CreateProcessArguments |
(从 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 } |
(从 6.6 起)
enum class
|
UnixProcessFlag { CloseFileDescriptors, CreateNewSession, DisconnectControllingTerminal, IgnoreSigPipe, ResetIds, …, UseVFork } |
flags | UnixProcessFlags |
QProcess (QObject * parent = nullptr) | |
virtual | ~QProcess () |
QStringList | arguments () const |
(从 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 |
(从 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 ) |
(从 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 ) |
(从 6.6 起)
void
|
setUnixProcessParameters (const QProcess::UnixProcessParameters & params ) |
(从 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) |
(从 6.0 起)
void
|
startCommand (const QString & 命令 , QIODeviceBase::OpenMode mode = ReadWrite) |
bool | startDetached (qint64 * pid = nullptr) |
QProcess::ProcessState | state () const |
(从 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 命令 ) |
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 |
virtual qint64 | writeData (const char * data , qint64 len ) 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 进入 运行 状态并发射 started ().
QProcess 允许把进程视为顺序 I/O 设备。可以读写进程,就像访问网络连接使用 QTcpSocket 。然后可以写入进程标准输入通过调用 write (),和读取标准输出通过调用 read (), readLine (),和 getChar ()。因为它继承 QIODevice ,QProcess 还可以用作输入源对于 QXmlReader ,或对于生成要上传的数据使用 QNetworkAccessManager .
当进程退出时,QProcess 重新进入 NotRunning 状态 (初始状态),并发射 finished ().
The finished () 信号以自变量形式提供进程退出代码和退出状态,也可以调用 exitCode () 以获得最后完成进程的退出代码,和 exitStatus () 以获得其退出状态。若在任何时间点出现错误,QProcess 将发射 errorOccurred () 信号。也可以调用 error () 以查找最后出现的错误类型,和 state () 以查找当前进程状态。
注意: QProcess 不支持 VxWorks iOS tvOS 或 watchOS。
可以设置要运行程序通过调用 setProgram () 或直接在 start () 调用。效果按调用 start () 采用程序名称和自变量,相当于调用 setProgram () 和 setArguments () 在该函数之前,然后调用没有那些参数的重载。
QProcess 以 3 种不同方式之一解释程序名,类似于 Unix Shell 和 Windows 命令解释器在它们自己的命令行中如何操作:
PATH
environment variable; on Windows, the search is performed by the OS and will first the parent process' current directory before the
PATH
environment variable (see the documentation for
CreateProcess
for the full list).
To avoid platform-dependent behavior or any issues with how the current application was launched, it is advisable to always pass an absolute path to the executable to be launched. For auxiliary binaries shipped with the application, one can construct such a path starting with QCoreApplication::applicationDirPath (). Similarly, to explicitly run an executable that is to be found relative to the directory set with setWorkingDirectory (), use a program path starting with "./" or "../" as the case may be.
On Windows, the ".exe" suffix is not required for most uses, except those outlined in the CreateProcess documentation. Additionally, QProcess will convert the Unix-style forward slashes to Windows path backslashes for the program name. This allows code using QProcess to be written in a cross-platform manner, as shown in the examples above.
QProcess does not support directly executing Unix shell or Windows command interpreter built-in functions, such as
cmd.exe
's
dir
command or the Bourne shell's
export
. On Unix, even though many shell built-ins are also provided as separate executables, their behavior may differ from those implemented as built-ins. To run those commands, one should explicitly execute the interpreter with suitable options. For Unix systems, launch "/bin/sh" with two arguments: "-c" and a string with the command-line to be run. For Windows, due to the non-standard way
cmd.exe
parses its command-line, use
setNativeArguments
() (for example, "/c dir d:").
The QProcess API offers methods to manipulate the environment variables that the child process will see. By default, the child process will have a copy of the current process environment variables that exist at the time the start () function is called. This means that any modifications performed using qputenv () prior to that call will be reflected in the child process' environment. Note that QProcess makes no attempt to prevent race conditions with qputenv () happening in other threads, so it is recommended to avoid qputenv () after the application's initial start up.
The environment for a specific child can be modified using the processEnvironment () 和 setProcessEnvironment () functions, which use the QProcessEnvironment class. By default, processEnvironment () will return an object for which QProcessEnvironment::inheritsFromParent () is true. Setting an environment that does not inherit from the parent will cause QProcess to use exactly that environment for the child when it is started.
The normal scenario starts from the current environment by calling QProcessEnvironment::systemEnvironment () and then proceeds to adding, changing, or removing specific variables. The resulting variable roster can then be applied to a QProcess with setProcessEnvironment ().
It is possible to remove all variables from the environment or to start from an empty environment, using the QProcessEnvironment() default constructor. This is not advisable outside of controlled and system-specific conditions, as there may be system variables that are set in the current process environment and are required for proper execution of the child process.
On Windows, QProcess will copy the current process'
"PATH"
and
"SystemRoot"
environment variables if they were unset. It is not possible to unset them completely, but it is possible to set them to empty values. Setting
"PATH"
to empty on Windows will likely cause the child process to fail to start.
进程有 2 个预定义输出通道:标准输出通道 (
stdout
) 供给常规控制台输出,和标准错误通道 (
stderr
) 通常提供由进程打印的错误。这些通道表示 2 个单独数据流。可以在它们之间切换通过调用
setReadChannel
()。QProcess 发射
readyRead
() 当当前读取通道数据可用时。它还发射
readyReadStandardOutput
() 当新标准输出数据可用时,和当新标准错误数据可用时,
readyReadStandardError
() 被发射。代替调用
read
(),
readLine
(),或
getChar
(),可以明确读取 2 通道之一的所有数据通过调用
readAllStandardOutput
() 或
readAllStandardError
().
通道术语可能产生误导。注意,进程的输出通道对应于 QProcess 的 read 通道,而进程的输入通道对应于 QProcess 的 write 通道。这是因为我们使用 QProcess 读取的是进程的输出,而写入的变为进程的输入。
QProcess 可以合并 2 输出通道,以便来自运行进程的标准输出和标准错误数据均使用标准输出通道。调用 setProcessChannelMode () 采用 MergedChannels 在开始激活此特征的进程之前。还有将正运行进程输出转发到调用主进程的选项,通过传递 ForwardedChannels 作为自变量。只转发某个输出通道是可能的 - 通常会使用 ForwardedErrorChannel ,但 ForwardedOutputChannel 也存在。注意,在 GUI 应用程序中使用通道转发通常是个坏主意 - 应该以图形呈现错误取而代之。
某些进程需要特殊环境设置才能运转。可以为进程设置环境变量通过调用 setProcessEnvironment ()。要设置工作目录,调用 setWorkingDirectory ()。默认情况下,进程在调用进程的当前工作目录下运行。
属于以 QProcess 启动的 GUI 应用程序的窗口的定位和屏幕 Z 次序,由底层窗口系统控制。对于 Qt 5 应用程序,可以指定定位使用
-qwindowgeometry
命令行选项;X11 应用程序一般接受
-geometry
命令行选项。
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();
另请参阅 QBuffer , QFile ,和 QTcpSocket .
注意: 此 typedef 只可用于桌面 Windows。
在 Windows,
QProcess
使用 Win32 API 函数
CreateProcess
去启动子级进程。而
QProcess
提供启动进程的舒适方式而无需担心平台细节,在某些情况下调优是可取的将参数传递给
CreateProcess
。这被履行通过定义
CreateProcessArgumentModifier
函数并把它传递给
setCreateProcessArgumentsModifier
.
A
CreateProcessArgumentModifier
函数接受一参数:指针指向
CreateProcessArguments
结构。此结构的成员会被传递给
CreateProcess
后于
CreateProcessArgumentModifier
函数被调用。
以下范例演示如何把自定义标志传递给
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::CreateProcessArguments and setCreateProcessArgumentsModifier ().
此枚举描述不同退出状态为 QProcess .
常量 | 值 | 描述 |
---|---|---|
QProcess::NormalExit
|
0
|
进程正常退出。 |
QProcess::CrashExit
|
1
|
进程崩溃。 |
另请参阅 exitStatus ().
此枚举描述进程输入通道模式为 QProcess 。将这些值之一传递给 setInputChannelMode () 去设置当前写入通道模式。
常量 | 值 | 描述 |
---|---|---|
QProcess::ManagedInputChannel
|
0
|
QProcess 管理正运行进程的输入。这是默认输入通道模式为 QProcess . |
QProcess::ForwardedInputChannel
|
1
|
QProcess 把主进程输入转发给正运行进程。子级进程从主进程的相同源读取其标准输入。注意:主进程不得试着读取其标准输入 (当子级进程正运行时)。 |
另请参阅 setInputChannelMode ().
此枚举描述正运行进程所使用的进程通道。传递这些值之一给 setReadChannel () 设置当前读取通道为 QProcess .
常量 | 值 | 描述 |
---|---|---|
QProcess::StandardOutput
|
0
|
正运行进程的 stdout (标准输出)。 |
QProcess::StandardError
|
1
|
正运行进程的 stderr (标准错误)。 |
另请参阅 setReadChannel ().
此枚举描述进程的输出通道模式为 QProcess 。将这些值之一传递给 setProcessChannelMode () 以设置当前读取通道模式。
常量 | 值 | 描述 |
---|---|---|
QProcess::SeparateChannels
|
0
|
QProcess 管理正运行进程的输出,将标准输出和标准错误数据保持在单独内部缓冲中。可以选择 QProcess 的当前读取通道通过调用 setReadChannel ()。这是默认通道模式对于 QProcess . |
QProcess::MergedChannels
|
1
|
QProcess
将在运行进程的输出合并到标准输出通道 (
stdout
)。标准错误通道 (
stderr
) 将不接收任何数据。运行进程的标准输出和标准错误数据是交错的。对于分离进程,正运行进程的合并输出被转发到主进程。
|
QProcess::ForwardedChannels
|
2
|
QProcess 将正运行进程的输出转发到主进程。由子级进程写入其标准输出和标准错误的任何内容,都将写入主进程的标准输出和标准错误。 |
QProcess::ForwardedErrorChannel
|
4
|
QProcess 管理在运行进程的标准输出,但会将标准错误转发到主进程。这反映将命令行工具作为过滤器的典型用法,其中标准输出被重定向到另一进程 (或文件),而标准错误被打印到控制台为诊断目的 (该值在 Qt 5.2 引入)。 |
QProcess::ForwardedOutputChannel
|
3
|
与 ForwardedErrorChannel 互补 (该值在 Qt 5.2 引入)。 |
注意: Windows 有意抑制从仅 GUI 应用程序输出到继承控制台。这 not 适用于重定向到文件或管道的输出。尽管如此,要在控制台转发仅 GUI 应用程序的输出,必须使用 SeparateChannels 和通过读取输出并将其写入适当输出通道自己来履行转发。
另请参阅 setProcessChannelMode ().
此枚举描述错误的不同类型,报告通过 QProcess .
常量 | 值 | 描述 |
---|---|---|
QProcess::FailedToStart
|
0
|
进程启动失败。被援引的程序丢失,或可能没有足够权限 (或资源) 援引程序。 |
QProcess::Crashed
|
1
|
进程有时崩溃在成功启动后。 |
QProcess::Timedout
|
2
|
最后 waitFor...() 函数超时。状态对于 QProcess 不变,和可以再次试着调用 waitFor...()。 |
QProcess::WriteError
|
4
|
发生错误当试图写入进程时。例如,进程可能未运行,或它可能已关闭其输入通道。 |
QProcess::ReadError
|
3
|
发生错误当试图从进程读取时。例如,进程可能未运行。 |
QProcess::UnknownError
|
5
|
发生未知错误。这是默认返回值为 error (). |
另请参阅 error ().
此枚举描述不同状态为 QProcess .
常量 | 值 | 描述 |
---|---|---|
QProcess::NotRunning
|
0
|
进程未运行。 |
QProcess::Starting
|
1
|
进程正在启动,但尚未援引程序。 |
QProcess::Running
|
2
|
进程正在运行且读写就绪。 |
另请参阅 state ().
[since 6.6]
enum class QProcess::
UnixProcessFlag
这些标志可以用于
flags
field of
UnixProcessParameters
.
常量 | 值 | 描述 |
---|---|---|
QProcess::UnixProcessFlag::CloseFileDescriptors
|
0x0010
|
Close all file descriptors above the threshold defined by
lowestFileDescriptorToClose
, preventing any currently open descriptor in the parent process from accidentally leaking to the child. The
stdin
,
stdout
,和
stderr
file descriptors are never closed.
|
QProcess::UnixProcessFlag::CreateNewSession (since Qt 6.7)
|
0x0040
|
Starts a new process session, by calling
setsid(2)
. This allows the child process to outlive the session the current process is in. This is one of the steps that
startDetached
() takes to allow the process to detach, and is also one of the steps to daemonize a process.
|
QProcess::UnixProcessFlag::DisconnectControllingTerminal (since Qt 6.7)
|
0x0080
|
Requests that the process disconnect from its controlling terminal, if it has one. If it has none, nothing happens. Processes still connected to a controlling terminal may get a Hang Up (
SIGHUP
) signal if the terminal closes, or one of the other terminal-control signals (
SIGTSTP
,
SIGTTIN
,
SIGTTOU
). Note that on some operating systems, a process may only disconnect from the controlling terminal if it is the session leader, meaning the
CreateNewSession
flag may be required. Like it, this is one of the steps to daemonize a process.
|
QProcess::UnixProcessFlag::IgnoreSigPipe
|
0x0002
|
Always sets the
SIGPIPE
signal to ignored (
SIG_IGN
), even if the
ResetSignalHandlers
flag was set. By default, if the child attempts to write to its standard output or standard error after the respective channel was closed with
QProcess::closeReadChannel
(), it would get the
SIGPIPE
signal and terminate immediately; with this flag, the write operation fails without a signal and the child may continue executing.
|
QProcess::UnixProcessFlag::ResetIds (since Qt 6.7)
|
0x0100
|
Drops any retained, effective user or group ID the current process may still have (see
setuid(2)
and
setgid(2)
, plus
QCoreApplication::setSetuidAllowed
()). This is useful if the current process was setuid or setgid and does not wish the child process to retain the elevated privileges.
|
QProcess::UnixProcessFlag::ResetSignalHandlers
|
0x0001
|
Resets all Unix signal handlers back to their default state (that is, pass
SIG_DFL
to
signal(2)
). This flag is useful to ensure any ignored (
SIG_IGN
) signal does not affect the child's behavior.
|
QProcess::UnixProcessFlag::UseVFork
|
0x0020
|
请求
QProcess
使用
vfork(2)
to start the child process. Use this flag to indicate that the callback function set with
setChildProcessModifier
() is safe to execute in the child side of a
vfork(2)
; that is, the callback does not modify any non-local variables (directly or through any function it calls), nor attempts to communicate with the parent process. It is implementation-defined if
QProcess
will actually use
vfork(2)
and if
vfork(2)
is different from standard
fork(2)
.
|
该枚举在 Qt 6.6 引入。
UnixProcessFlags 类型是 typedef 对于 QFlags <UnixProcessFlag>. It stores an OR combination of UnixProcessFlag values.
另请参阅 setUnixProcessParameters () 和 unixProcessParameters ().
[explicit]
QProcess::
QProcess
(
QObject
*
parent
= nullptr)
构造 QProcess 对象采用给定 parent .
[virtual noexcept]
QProcess::
~QProcess
()
销毁 QProcess 对象,即:杀除进程。
注意:此函数不会返回直到进程被终止。
返回上次启动进程采用的命令行自变量。
另请参阅 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 (),且无法再读取或写入数据。
关闭读取通道 channel 。在调用此函数后, QProcess 将不再接收通道数据。任何已收到的数据仍可用于读取。
调用此函数以节省内存,若对进程的输出不感兴趣。
另请参阅 closeWriteChannel () 和 setReadChannel ().
调度写入通道对于 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 ().
返回先前设置的
CreateProcess
修饰符函数。
注意: 此函数只可用于 Windows 平台。
另请参阅 setCreateProcessArgumentsModifier () 和 QProcess::CreateProcessArgumentModifier .
返回最后出现的错误类型。
另请参阅 state ().
[signal]
void
QProcess::
errorOccurred
(
QProcess::ProcessError
error
)
此信号被发射,当进程出现错误时。指定 error 描述出现的错误类型。
[static]
int
QProcess::
execute
(const
QString
&
program
, const
QStringList
&
arguments
= {})
启动程序 program 采用自变量 arguments 在新进程中,等待它完成,然后返回进程的退出代码。新进程写入控制台的任何数据会被转发给调用进程。
环境和工作目录继承自调用进程。
自变量处理分别等同 start () 重载。
若进程无法启动,返回 -2。若进程崩溃,返回 -1。否则,返回进程的退出代码。
另请参阅 start ().
返回最后完成进程的退出代码。
此值无效除非 exitStatus () 返回 NormalExit .
返回最后完成的进程退出状态。
在 Windows,若进程被另一应用程序的 TerminateProcess() 所终止,此函数仍会返回 NormalExit 除非退出代码小于 0。
[noexcept, since 6.7]
void
QProcess::
failChildProcessModifier
(const
char
*
description
,
int
error
= 0)
This functions can be used inside the modifier set with
setChildProcessModifier
() to indicate an error condition was encountered. When the modifier calls these functions,
QProcess
将发射
errorOccurred
() with code
QProcess::FailedToStart
in the parent process. The
description
can be used to include some information in
errorString
() to help diagnose the problem, usually the name of the call that failed, similar to the C Library function
perror()
。此外,
error
parameter can be an
<errno.h>
error code whose text form will also be included.
For example, a child modifier could prepare an extra file descriptor for the child process this way:
process.setChildProcessModifier([fd, &process]() { if (dup2(fd, TargetFileDescriptor) < 0) process.failChildProcessModifier(errno, "aux comm channel"); }); process.start();
Where
fd
is a file descriptor currently open in the parent process. If the
dup2()
system call resulted in an
EBADF
condition, the process
errorString
() could be "Child process modifier reported error: aux comm channel: Bad file descriptor".
This function does not return to the caller. Using it anywhere except in the child modifier and with the correct QProcess object is undefined behavior.
注意: The implementation imposes a length limit to the description parameter to about 500 characters. This does not include the text from the error 代码。
该函数在 Qt 6.7 引入。
另请参阅 setChildProcessModifier () 和 setUnixProcessParameters ().
[signal]
void
QProcess::
finished
(
int
exitCode
,
QProcess::ExitStatus
exitStatus
= NormalExit)
此信号被发射当进程完成时。 exitCode 是进程的退出代码 (仅对正常退出有效),和 exitStatus 是退出状态。在进程完成后,缓冲在 QProcess 仍完好无损。仍可以读取进程可能已写入的任何数据在完成之前。
另请参阅 exitStatus ().
返回通道模式对于 QProcess 标准输入通道。
另请参阅 setInputChannelMode () 和 InputChannelMode .
[override virtual]
bool
QProcess::
isSequential
() const
重实现: QIODevice::isSequential() const .
[slot]
void
QProcess::
kill
()
杀除当前进程,导致它立即退出。
在 Windows,kill() 使用 TerminateProcess,而在 Unix 和 macOS,把 SIGKILL 信号发送给进程。
另请参阅 terminate ().
返回程序的附加本机命令行自变量。
注意: 此函数只可用于 Windows 平台。
另请参阅 setNativeArguments ().
[static]
QString
QProcess::
nullDevice
()
操作系统的 null 设备。
返回的文件路径使用本机目录分隔符。
另请参阅 QProcess::setStandardInputFile (), QProcess::setStandardOutputFile (),和 QProcess::setStandardErrorFile ().
[override virtual]
bool
QProcess::
open
(
QIODeviceBase::OpenMode
mode
= ReadWrite)
重实现: QIODevice::open (QIODeviceBase::OpenMode mode).
启动程序设置通过 setProgram () 采用自变量设置通过 setArguments ()。OpenMode 被设为 mode .
此方法是别名化的 start (),且存在仅为完全实现定义接口通过 QIODevice .
返回
true
若程序已启动。
另请参阅 start (), setProgram (),和 setArguments ().
返回通道模式对于 QProcess 标准输出和标准错误通道。
另请参阅 setProcessChannelMode (), ProcessChannelMode ,和 setReadChannel ().
返回环境从 QProcess 将它传递给子级进程。若未设置环境使用 setProcessEnvironment (),此方法返回指示环境将继承自父级的对象。
另请参阅 setProcessEnvironment (), QProcessEnvironment::inheritsFromParent (),和 环境变量 .
返回正在运行进程的本机进程标识符,若可用。若目前没有进程正在运行,
0
被返回。
返回进程最后一次启动时采用的程序。
另请参阅 setProgram () 和 start ().
不管当前读取通道,此函数从进程标准错误返回所有可用数据按 QByteArray .
另请参阅 readyReadStandardError (), readAllStandardOutput (), readChannel (),和 setReadChannel ().
不管当前读取通道,此函数从进程标准输出返回所有可用数据按 QByteArray .
另请参阅 readyReadStandardOutput (), readAllStandardError (), readChannel (),和 setReadChannel ().
返回当前读取通道为 QProcess .
另请参阅 setReadChannel ().
[override virtual protected]
qint64
QProcess::
readData
(
char
*
data
,
qint64
maxlen
)
重实现: QIODevice::readData (char *data, qint64 maxSize).
[private signal]
void
QProcess::
readyReadStandardError
()
此信号被发射当进程已使新数据可用透过其标准错误通道 (
stderr
)。它被发射不管当前
读取通道
.
注意: 这是私有信号。它可以用于信号连接,但不能由用户发射。
另请参阅 readAllStandardError () 和 readChannel ().
[private signal]
void
QProcess::
readyReadStandardOutput
()
此信号被发射当进程已使新数据可用透过其标准输出通道 (
stdout
)。它被发射不管当前
读取通道
.
注意: 这是私有信号。它可以用于信号连接,但不能由用户发射。
另请参阅 readAllStandardOutput () 和 readChannel ().
设置 arguments 以传递给被调用程序当启动进程时。必须调用此函数先于 start ().
另请参阅 start (), setProgram (),和 arguments ().
[since 6.0]
void
QProcess::
setChildProcessModifier
(const
std::function
<
void
()> &
modifier
)
设置
modifier
函数为子级进程,对于 Unix 系统 (包括 macOS;对于 Windows,见
setCreateProcessArgumentsModifier
())。函数包含通过
modifier
自变量,会在子级进程中被援引后于
fork()
or
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(); }
If the modifier function experiences a failure condition, it can use
failChildProcessModifier
() to report the situation to the
QProcess
caller. Alternatively, it may use other methods of stopping the process, like
_exit()
,或
abort()
.
Certain properties of the child process, such as closing all extraneous file descriptors or disconnecting from the controlling TTY, can be more readily achieved by using setUnixProcessParameters (), which can detect failure and report a FailedToStart condition. The modifier is useful to change certain uncommon properties of the child process, such as setting up additional file descriptors. If both a child process modifier and Unix process parameters are set, the modifier is run before these parameters are applied.
注意: 在多线程应用程序中,此函数必须小心,不要调用任何可能已用于其它线程的互斥锁函数 (一般而言,建议仅使用由 POSIX 定义为 "异步信号安全" 的函数)。大多数 Qt API 在此回调中都不安全,包括 qDebug (),且可能导致死锁。
注意:
If the UnixProcessParameters::UseVFork flag is set via
setUnixProcessParameters
(),
QProcess
可以使用
vfork()
语义来启动子级进程,因此,该函数必须服从甚至更严格的约束。首先,因为它仍然与父级进程共享内存,所以不得将它写入任何非局部变量,且必须服从正确次序语义 (当读取它们时),以避免数据竞争。其次,甚至更多库函数可能行为失常;因此,此函数只应用于低级系统调用,譬如
read()
,
write()
,
setsid()
,
nice()
,和类似的。
该函数在 Qt 6.0 引入。
另请参阅 childProcessModifier (), failChildProcessModifier (),和 setUnixProcessParameters ().
设置
modifier
为
CreateProcess
Win32 API 调用。传递
QProcess::CreateProcessArgumentModifier()
以移除先前设置的。
注意: 此函数只可用于 Windows 平台且要求 C++ 11。
另请参阅 createProcessArgumentsModifier (), QProcess::CreateProcessArgumentModifier ,和 setChildProcessModifier ().
设置通道模式为 QProcess 标准输入通道到 mode 指定。会使用此模式当下次 start () 被调用。
另请参阅 inputChannelMode () 和 InputChannelMode .
这是重载函数。
设置额外本机命令行 arguments 为程序。
在操作系统中,若系统 API 用于传递命令行 arguments 到本机子进程使用单字符串,可以设想无法传递命令行凭借 QProcess 基于列表的可移植 API。在这种情况下,必须使用此函数来设置字符串, appended 到通常由自变量列表合成的字符串,带定界空格。
注意: 此函数只可用于 Windows 平台。
另请参阅 nativeArguments ().
设置通道模式为 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 (), ProcessChannelMode ,和 setReadChannel ().
设置 environment that QProcess 将传递给子级进程。
例如,以下代码添加环境变量
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 (),和 环境变量 .
[protected]
void
QProcess::
setProcessState
(
QProcess::ProcessState
state
)
设置当前状态为 QProcess 到 state 指定。
另请参阅 state ().
设置 program 为使用当启动进程时。此函数必须被调用先于 start ().
若
program
是绝对路径,它指定将要发起的准确可执行文件。相对路径将以特定平台方式解析,包括搜索
PATH
环境变量 (见
查找可执行文件
了解细节)。
另请参阅 start (), setArguments (), program (),和 QStandardPaths::findExecutable ().
设置当前读取通道为 QProcess 到给定 channel 。当前输入通道用于函数 read (), readAll (), readLine (),和 getChar ()。它还确定哪个通道触发 QProcess 以发射 readyRead ().
另请参阅 readChannel ().
将进程的标准错误重定向到文件 fileName 。当重定向到位时,标准错误读取通道被关闭:读取它使用 read () 将始终失败,就像 readAllStandardError ()。文件将被追加若 mode 为 Append,否则, 它将被截取。
见 setStandardOutputFile () 了解如何打开文件的更多相关信息。
注意:若 setProcessChannelMode () 被调用采用自变量 QProcess::MergedChannels ,此函数不起作用。
另请参阅 setStandardInputFile (), setStandardOutputFile (),和 setStandardOutputProcess ().
将进程的标准输入重定向到文件指示通过 fileName 。当输入重定向到位时, QProcess 对象将处于只读模式 (调用 write () 将导致出错)。
要使进程立即读取 EOF,传递 nullDevice () 在此。这更清洁比使用 closeWriteChannel () 在写入任何数据之前,因为在启动进程之前可以设置它。
若文件 fileName 不存在此刻 start () 被调用或不可读,启动进程将失败。
在进程启动后调用 setStandardInputFile() 不起作用。
另请参阅 setStandardOutputFile (), setStandardErrorFile (),和 setStandardOutputProcess ().
将进程的标准输出重定向到文件 fileName 。当重定向到位时,标准输出读取通道被关闭:读取它使用 read () 将始终失败,就像 readAllStandardOutput ().
要丢弃来自进程的所有标准输出,传递 nullDevice () 在此。这比简单从不读取标准输出更高效,因为没有 QProcess 缓冲被填充。
若文件 fileName 不存在此刻 start () 被调用,它将被创建。若它无法被创建,启动将失败。
若文件存在且 mode 为 QIODevice::Truncate,文件将被截取。否则 (若 mode 为 QIODevice::Append),文件将被追加。
在进程启动后调用 setStandardOutputFile() 不起作用。
若 fileName 为空字符串,它停止重定向标准输出。这对重定向后,还原标准输出很有用。
另请参阅 setStandardInputFile (), setStandardErrorFile (),和 setStandardOutputProcess ().
将此进程的标准输出流管道到 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 修改子级进程,在发起目标可执行文件之前。
This function can be used to change certain properties of the child process, such as closing all extraneous file descriptors, changing the nice level of the child, or disconnecting from the controlling TTY. For more fine-grained control of the child process or to modify it in other ways, use the setChildProcessModifier () function. If both a child process modifier and Unix process parameters are set, the modifier is run before these parameters are applied.
注意: 此函数只可用于 Unix 平台。
该函数在 Qt 6.6 引入。
另请参阅 unixProcessParameters () 和 setChildProcessModifier ().
[since 6.6]
void
QProcess::
setUnixProcessParameters
(
QProcess::UnixProcessFlags
flagsOnly
)
这是重载函数。
Sets the extra settings for the child process on Unix systems to
flagsOnly
. This is the same as the overload with just the
flags
field set.
注意: 此函数只可用于 Unix 平台。
该函数在 Qt 6.6 引入。
另请参阅 unixProcessParameters () 和 setChildProcessModifier ().
把工作目录设为 dir . QProcess 将在此目录下启动进程。默认行为是在调用进程的工作目录下启动进程。
另请参阅 workingDirectory () 和 start ().
[static]
QStringList
QProcess::
splitCommand
(
QStringView
命令
)
分割字符串 命令 成令牌列表,并返回列表。
带空格的令牌可以由双引号环绕;3 连续双引号表示引号字符本身。
启动给定 program 在新进程中,传递的命令行自变量在 arguments 。见 setProgram () 了解有关信息对于如何 QProcess searches for the executable to be run. The OpenMode is set to mode . No further splitting of the arguments is performed.
The QProcess 对象将立即进入 Starting 状态。若进程成功启动, QProcess 将发射 started ();否则, errorOccurred () will be emitted. Do note that on platforms that are able to start child processes synchronously (notably Windows), those signals will be emitted before this function returns and this QProcess object will transition to either QProcess::Running or QProcess::NotRunning state, respectively. On others paltforms, the started () 和 errorOccurred () signals will be delayed.
调用 waitForStarted () to make sure the process has started (or has failed to start) and those signals have been emitted. It is safe to call that function even if the process starting state is already known, though the signal will not be emitted again.
Windows:
自变量加引号并被拼接到兼容命令行采用
CommandLineToArgvW()
Windows 函数。对于有不同命令行要求加引号的程序,需要使用
setNativeArguments
()。值得注意的是程序不遵循
CommandLineToArgvW()
规则是 cmd.exe,因此是所有批处理脚本。
若 QProcess 对象已在运行进程,可能在控制台打印警告,且现有进程将不受影响地继续运行。
注意: Success at starting the child process only implies the operating system has successfully created the process and assigned the resources every process has, such as its process ID. The child process may crash or otherwise fail very early and thus not produce its expected output. On most operating systems, this may include dynamic linking errors.
另请参阅 processId (), started (), waitForStarted (),和 setNativeArguments ().
这是重载函数。
启动程序设置通过 setProgram () 采用自变量设置通过 setArguments ()。OpenMode 被设为 mode .
另请参阅 open (), setProgram (),和 setArguments ().
[since 6.0]
void
QProcess::
startCommand
(const
QString
&
命令
,
QIODeviceBase::OpenMode
mode
= ReadWrite)
启动命令 命令 在新进程中。OpenMode 被设为 mode .
命令 是包含程序名称及其自变量的单文本字符串。自变量由一个或多个空格分隔。例如:
QProcess process; process.startCommand("del /s *.txt"); // same as process.start("del", QStringList() << "/s" << "*.txt"); ...
必须引用包含空格的自变量才能被正确提供给新进程。例如:
QProcess process; process.startCommand("dir \"My Documents\"");
文字引号在 命令 字符串由 3 引号表示。例如:
QProcess process; process.startCommand("dir \"Epic 12\"\"\" Singles\"");
之后 命令 字符串被拆分并取消引号,此函数的行为像 start ().
在将命令行自变量传递给子进程的本机系统 API 使用单字符串的 Windows 操作系统,可以设想无法传递命令行凭借 QProcess 的基于列表的可移植 API。在这些罕见情况下,需要使用 setProgram () 和 setNativeArguments () 而不是此函数。
该函数在 Qt 6.0 引入。
另请参阅 splitCommand () 和 start ().
启动程序设置通过
setProgram
() 采用自变量设置通过
setArguments
() 在新进程中,并与之分离。返回
true
当成功时;否则返回
false
。若调用进程退出,分离进程将不受影响地继续运行。
Unix: 启动进程将在它自己的会话中运行,且行动像守护程序。
进程将在指定目录下启动设置通过 setWorkingDirectory ()。若 workingDirectory () 为空,工作目录继承自调用进程。
若函数成功,那么 * pid 被设为启动进程的进程标识符;否则,它被设为 -1。注意,子级进程可能退出,且 PID 可能在没有通知的情况下失效。此外,在子级进程退出后,同一 PID 可能被完全不同进程回收和使用。用户代码应小心当使用此变量时,特别是若某人打算通过操作系统手段强制终止进程。
startDetached() 仅支持以下属性 setter:
所有其它特性对于 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()。
启动程序
program
采用自变量
arguments
按新进程中,并与之分离。返回
true
当成功时;否则返回
false
。若调用进程退出,分离进程将不受影响地继续运行。
自变量处理分别等同 start () 重载。
进程将被启动在目录 workingDirectory 。若 workingDirectory 为空,工作目录继承自调用进程。
若函数成功,那么 * pid 被设为启动进程的进程标识符。
另请参阅 start ().
[private signal]
void
QProcess::
started
()
此信号被发射由 QProcess 当此过程已开始,且 state () 返回 运行 .
注意: 这是私有信号。它可以用于信号连接,但不能由用户发射。
返回进程的当前状态。
另请参阅 stateChanged () 和 error ().
[private signal]
void
QProcess::
stateChanged
(
QProcess::ProcessState
newState
)
此信号被发射每当状态为 QProcess 改变。 newState 自变量为状态 QProcess 要改变。
注意: 这是私有信号。它可以用于信号连接,但不能由用户发射。
[static]
QStringList
QProcess::
systemEnvironment
()
以 key=value 对列表形式返回调用进程的环境。范例:
QStringList environment = QProcess::systemEnvironment(); // environment = {"PATH=/usr/bin:/usr/local/bin", // "USER=greg", "HOME=/home/greg"}
此函数不缓存系统环境。因此,获得环境的更新版本是可能的,若低级 C 库函数像
setenv
or
putenv
有被调用。
不管怎样,注意,重复调用此函数将重新创建环境变量列表 (非通俗操作)。
注意: 对于新代码,推荐使用 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 object describing extra flags and settings that will be applied to the child process on Unix systems. The default settings correspond to a default-constructed UnixProcessParameters .
注意: 此函数只可用于 Unix 平台。
该函数在 Qt 6.6 引入。
另请参阅 setUnixProcessParameters () 和 childProcessModifier ().
[override virtual]
bool
QProcess::
waitForBytesWritten
(
int
msecs
= 30000)
重实现: QIODevice::waitForBytesWritten (int msecs).
阻塞直到进程已完成且 finished () 信号已发射,或直到 msecs 毫秒已过去。
返回
true
若进程已完成;否则返回
false
(若操作超时,若发生错误,或者若此
QProcess
已完成)。
可以在没有事件循环的情况下操作此函数。它很有用,当编写非 GUI 应用程序和在非 GUI 线程中履行 I/O 操作时。
警告: 从主 GUI 线程调用此函数可能导致用户界面被冻结。
若 msecs 为 -1,此函数不会超时。
另请参阅 finished (), waitForStarted (), waitForReadyRead (),和 waitForBytesWritten ().
[override virtual]
bool
QProcess::
waitForReadyRead
(
int
msecs
= 30000)
重实现: QIODevice::waitForReadyRead (int msecs).
阻塞直到进程启动且 started () 信号已发射,或直到 msecs 毫秒已过去。
返回
true
若进程成功启动;否则返回
false
(if the operation timed out or if an error occurred). If the process had already started successfully before this function, it returns immediately.
可以在没有事件循环的情况下操作此函数。它很有用,当编写非 GUI 应用程序和在非 GUI 线程中履行 I/O 操作时。
警告: 从主 GUI 线程调用此函数可能导致用户界面被冻结。
若 msecs 为 -1,此函数不会超时。
另请参阅 started (), waitForReadyRead (), waitForBytesWritten (),和 waitForFinished ().
若 QProcess 已赋值工作目录,此函数返回工作目录 QProcess 将在程序开始之前进入。否则,返回空字符串 (即:没有赋值目录),且 QProcess 将使用应用程序的当前工作目录取而代之。
另请参阅 setWorkingDirectory ().
[override virtual protected]
qint64
QProcess::
writeData
(const
char
*
data
,
qint64
len
)
重实现: QIODevice::writeData (const char *data, qint64 maxSize).