diff options
| author | Thiago Macieira <thiago.macieira@intel.com> | 2023-03-16 17:24:15 -0700 |
|---|---|---|
| committer | Thiago Macieira <thiago.macieira@intel.com> | 2023-05-22 10:43:50 -0700 |
| commit | f9c87cfd44bcf4b90cb45354252ef19f647b0469 (patch) | |
| tree | 178c478b703821ead52916e2db562ee819c780c2 /src/corelib/io/qprocess.cpp | |
| parent | 6a4afebc5ce8db69a6c9fb398cada31e6bad5e3c (diff) | |
QProcess/Unix: add setUnixProcessParameters()
This commit adds those three flags that are either frequent enough or
difficult to do: close all file descriptors above stderr and reset the
signal handlers. Setting SIGPIPE to be ignored isn't critical, but is
required when the ResetSignalHandlers flag is used, as this is run
after the user child process modifier.
[ChangeLog][QtCore][QProcess] Added setUnixProcessParameters() function
that can be used to modify certain settings of the child process,
without the need to provide a callback using setChildProcessModifier().
Change-Id: Icfe44ecf285a480fafe4fffd174d0d1d63840403
Reviewed-by: Volker Hilsheimer <volker.hilsheimer@qt.io>
Diffstat (limited to 'src/corelib/io/qprocess.cpp')
| -rw-r--r-- | src/corelib/io/qprocess.cpp | 135 |
1 files changed, 127 insertions, 8 deletions
diff --git a/src/corelib/io/qprocess.cpp b/src/corelib/io/qprocess.cpp index 7f3cc7bd894..ddcd7a4768a 100644 --- a/src/corelib/io/qprocess.cpp +++ b/src/corelib/io/qprocess.cpp @@ -805,6 +805,58 @@ void QProcessPrivate::Channel::clear() */ /*! + \class QProcess::UnixProcessParameters + \inmodule QtCore + \note This struct is only available on Unix platforms + \since 6.6 + + This struct can be used to pass extra, Unix-specific configuration for the + child process using QProcess::setUnixProcessParameters(). + + Its members are: + \list + \li UnixProcessParameters::flags Flags, see QProcess::UnixProcessFlags + \endlist + + All of the settings above can also be manually achieved by calling the + respective POSIX function from a handler set with + QProcess::setChildProcessModifier(). This structure allows QProcess to deal + with any platform-specific differences, benefit from certain optimizations, + and reduces code duplication. Moreover, if any of those functions fail, + QProcess will enter QProcess::FailedToStart state, while the child process + modifier callback is not allowed to fail. + + \sa QProcess::setUnixProcessParameters(), QProcess::setChildProcessModifier() +*/ + +/*! + \enum QProcess::UnixProcessFlags + \since 6.6 + + These flags can be used in the \c flags field of \l UnixProcessParameters. + + \value CloseNonStandardFileDescriptors Close all file descriptors besides + \c stdin, \c stdout, and \c stderr, preventing any currently open + descriptor in the parent process from accidentally leaking to the + child. + + \value IgnoreSigPipe Always sets the \c SIGPIPE signal to ignored + (\c SIG_IGN), even if the \c 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 \c SIGPIPE signal and + terminate immediately; with this flag, the write operation fails + without a signal and the child may continue executing. + + \value ResetSignalHandlers Resets all Unix signal handlers back to their + default state (that is, pass \c SIG_DFL to \c{signal(2)}). This flag + is useful to ensure any ignored (\c SIG_IGN) signal does not affect + the child's behavior. + + \sa setUnixProcessParameters(), unixProcessParameters() +*/ + +/*! \fn void QProcess::errorOccurred(QProcess::ProcessError error) \since 5.6 @@ -1553,7 +1605,7 @@ void QProcess::setCreateProcessArgumentsModifier(CreateProcessArgumentModifier m \note This function is only available on Unix platforms. - \sa setChildProcessModifier() + \sa setChildProcessModifier(), unixProcessParameters() */ std::function<void(void)> QProcess::childProcessModifier() const { @@ -1567,12 +1619,9 @@ std::function<void(void)> QProcess::childProcessModifier() const Sets the \a modifier function for the child process, for Unix systems (including \macos; for Windows, see setCreateProcessArgumentsModifier()). The function contained by the \a modifier argument will be invoked in the - child process after \c{fork()} or \c{vfork()} is completed and QProcess has set up the - standard file descriptors for the child process, but before \c{execve()}, - inside start(). The modifier is useful to change certain properties of the - child process, such as setting up additional file descriptors or closing - others, changing the nice level, disconnecting from the controlling TTY, - etc. + child process after \c{fork()} or \c{vfork()} is completed and QProcess has + set up the standard file descriptors for the child process, but before + \c{execve()}, inside start(). The following shows an example of setting up a child process to run without privileges: @@ -1582,13 +1631,22 @@ std::function<void(void)> QProcess::childProcessModifier() const If the modifier function needs to exit the process, remember to use \c{_exit()}, not \c{exit()}. + 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 \l{QProcess::}{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. + \note In multithreaded applications, this function must be careful not to call any functions that may lock mutexes that may have been in use in other threads (in general, using only functions defined by POSIX as "async-signal-safe" is advised). Most of the Qt API is unsafe inside this callback, including qDebug(), and may lead to deadlocks. - \sa childProcessModifier() + \sa childProcessModifier(), setUnixProcessParameters() */ void QProcess::setChildProcessModifier(const std::function<void(void)> &modifier) { @@ -1597,6 +1655,67 @@ void QProcess::setChildProcessModifier(const std::function<void(void)> &modifier d->unixExtras.reset(new QProcessPrivate::UnixExtras); d->unixExtras->childProcessModifier = modifier; } + +/*! + \since 6.6 + Returns the \l 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. + + \note This function is only available on Unix platforms. + + \sa childProcessModifier() +*/ +auto QProcess::unixProcessParameters() const noexcept -> UnixProcessParameters +{ + Q_D(const QProcess); + return d->unixExtras ? d->unixExtras->processParameters : UnixProcessParameters{}; +} + +/*! + \since 6.6 + Sets the extra settings and parameters for the child process on Unix + systems to be \a params. This function can be used to ask QProcess to + modify the child process before launching the target executable. + + 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. + + \note This function is only available on Unix platforms. + + \sa unixProcessParameters(), setChildProcessModifier() +*/ +void QProcess::setUnixProcessParameters(const UnixProcessParameters ¶ms) +{ + Q_D(QProcess); + if (!d->unixExtras) + d->unixExtras.reset(new QProcessPrivate::UnixExtras); + d->unixExtras->processParameters = params; +} + +/*! + \since 6.6 + \overload + + Sets the extra settings for the child process on Unix systems to \a + flagsOnly. This is the same as the overload with just the \c flags field + set. + \note This function is only available on Unix platforms. + + \sa unixProcessParameters(), setChildProcessModifier() +*/ +void QProcess::setUnixProcessParameters(UnixProcessFlags flagsOnly) +{ + Q_D(QProcess); + if (!d->unixExtras) + d->unixExtras.reset(new QProcessPrivate::UnixExtras); + d->unixExtras->processParameters = { flagsOnly }; +} #endif /*! |