include/QtCore/qprocess.h

0001 // Copyright (C) 2016 The Qt Company Ltd.
0002 // Copyright (C) 2023 Intel Corporation.
0003 // SPDX-License-Identifier: LicenseRef-Qt-Commercial OR LGPL-3.0-only OR GPL-2.0-only OR GPL-3.0-only
0004 // Qt-Security score:critical reason:execute-external-code
0005
0006 #ifndef QPROCESS_H
0007 #define QPROCESS_H
0008
0009 #include <QtCore/qcompare.h>
0010 #include <QtCore/qiodevice.h>
0011 #include <QtCore/qstringlist.h>
0012 #include <QtCore/qshareddata.h>
0013
0014 #include <functional>
0015
0016 QT_REQUIRE_CONFIG(processenvironment);
0017
0018 #if defined(Q_OS_WIN) || defined(Q_QDOC)
0019 struct _PROCESS_INFORMATION;
0020 struct _SECURITY_ATTRIBUTES;
0021 struct _STARTUPINFOW;
0022 using Q_PROCESS_INFORMATION = _PROCESS_INFORMATION;
0023 using Q_SECURITY_ATTRIBUTES = _SECURITY_ATTRIBUTES;
0024 using Q_STARTUPINFO = _STARTUPINFOW;
0025 #endif
0026
0027 QT_BEGIN_NAMESPACE
0028
0029 class QProcessPrivate;
0030 class QProcessEnvironmentPrivate;
0031
0032 class Q_CORE_EXPORT QProcessEnvironment
0033 {
0034 public:
0035     enum Initialization { InheritFromParent };
0036
0037     QProcessEnvironment();
0038     QProcessEnvironment(Initialization) noexcept;
0039     QProcessEnvironment(const QProcessEnvironment &other);
0040     ~QProcessEnvironment();
0041     QT_MOVE_ASSIGNMENT_OPERATOR_IMPL_VIA_PURE_SWAP(QProcessEnvironment)
0042     QProcessEnvironment &operator=(const QProcessEnvironment &other);
0043
0044     void swap(QProcessEnvironment &other) noexcept { d.swap(other.d); }
0045
0046 #if QT_CORE_REMOVED_SINCE(6, 8)
0047     bool operator==(const QProcessEnvironment &other) const;
0048     inline bool operator!=(const QProcessEnvironment &other) const
0049     { return !operator==(other); }
0050 #endif
0051
0052     bool isEmpty() const;
0053     [[nodiscard]] bool inheritsFromParent() const;
0054     void clear();
0055
0056     bool contains(const QString &name) const;
0057     void insert(const QString &name, const QString &value);
0058     void remove(const QString &name);
0059     QString value(const QString &name, const QString &defaultValue = QString()) const;
0060
0061     QStringList toStringList() const;
0062
0063     QStringList keys() const;
0064
0065     void insert(const QProcessEnvironment &e);
0066
0067     static QProcessEnvironment systemEnvironment();
0068
0069 private:
0070     friend Q_CORE_EXPORT bool comparesEqual(const QProcessEnvironment &lhs,
0071                                             const QProcessEnvironment &rhs);
0072     Q_DECLARE_EQUALITY_COMPARABLE_NON_NOEXCEPT(QProcessEnvironment)
0073     friend class QProcessPrivate;
0074     friend class QProcessEnvironmentPrivate;
0075     QSharedDataPointer<QProcessEnvironmentPrivate> d;
0076 };
0077
0078 Q_DECLARE_SHARED(QProcessEnvironment)
0079
0080 #if QT_CONFIG(process)
0081
0082 class Q_CORE_EXPORT QProcess : public QIODevice
0083 {
0084     Q_OBJECT
0085 public:
0086     enum ProcessError {
0087         FailedToStart,
0088         Crashed,
0089         Timedout,
0090         ReadError,
0091         WriteError,
0092         UnknownError
0093     };
0094     Q_ENUM(ProcessError)
0095
0096     enum ProcessState {
0097         NotRunning,
0098         Starting,
0099         Running
0100     };
0101     Q_ENUM(ProcessState)
0102
0103     enum ProcessChannel {
0104         StandardOutput,
0105         StandardError
0106     };
0107     Q_ENUM(ProcessChannel)
0108
0109     enum ProcessChannelMode {
0110         SeparateChannels,
0111         MergedChannels,
0112         ForwardedChannels,
0113         ForwardedOutputChannel,
0114         ForwardedErrorChannel
0115     };
0116     Q_ENUM(ProcessChannelMode)
0117
0118     enum InputChannelMode {
0119         ManagedInputChannel,
0120         ForwardedInputChannel
0121     };
0122     Q_ENUM(InputChannelMode)
0123
0124     enum ExitStatus {
0125         NormalExit,
0126         CrashExit
0127     };
0128     Q_ENUM(ExitStatus)
0129
0130     explicit QProcess(QObject *parent = nullptr);
0131     virtual ~QProcess();
0132
0133     void start(const QString &program, const QStringList &arguments = {}, OpenMode mode = ReadWrite);
0134     void start(OpenMode mode = ReadWrite);
0135     void startCommand(const QString &command, OpenMode mode = ReadWrite);
0136     bool startDetached(qint64 *pid = nullptr);
0137     bool open(OpenMode mode = ReadWrite) override;
0138
0139     QString program() const;
0140     void setProgram(const QString &program);
0141
0142     QStringList arguments() const;
0143     void setArguments(const QStringList & arguments);
0144
0145     ProcessChannelMode processChannelMode() const;
0146     void setProcessChannelMode(ProcessChannelMode mode);
0147     InputChannelMode inputChannelMode() const;
0148     void setInputChannelMode(InputChannelMode mode);
0149
0150     ProcessChannel readChannel() const;
0151     void setReadChannel(ProcessChannel channel);
0152
0153     void closeReadChannel(ProcessChannel channel);
0154     void closeWriteChannel();
0155
0156     void setStandardInputFile(const QString &fileName);
0157     void setStandardOutputFile(const QString &fileName, OpenMode mode = Truncate);
0158     void setStandardErrorFile(const QString &fileName, OpenMode mode = Truncate);
0159     void setStandardOutputProcess(QProcess *destination);
0160
0161 #if defined(Q_OS_WIN) || defined(Q_QDOC)
0162     QString nativeArguments() const;
0163     void setNativeArguments(const QString &arguments);
0164     struct CreateProcessArguments
0165     {
0166         const wchar_t *applicationName;
0167         wchar_t *arguments;
0168         Q_SECURITY_ATTRIBUTES *processAttributes;
0169         Q_SECURITY_ATTRIBUTES *threadAttributes;
0170         bool inheritHandles;
0171         unsigned long flags;
0172         void *environment;
0173         const wchar_t *currentDirectory;
0174         Q_STARTUPINFO *startupInfo;
0175         Q_PROCESS_INFORMATION *processInformation;
0176     };
0177     typedef std::function<void(CreateProcessArguments *)> CreateProcessArgumentModifier;
0178     CreateProcessArgumentModifier createProcessArgumentsModifier() const;
0179     void setCreateProcessArgumentsModifier(CreateProcessArgumentModifier modifier);
0180 #endif // Q_OS_WIN || Q_QDOC
0181 #if defined(Q_OS_UNIX) || defined(Q_QDOC)
0182     std::function<void(void)> childProcessModifier() const;
0183     void setChildProcessModifier(const std::function<void(void)> &modifier);
0184     Q_NORETURN void failChildProcessModifier(const char *description, int error = 0) noexcept;
0185
0186     enum class UnixProcessFlag : quint32 {
0187         ResetSignalHandlers                 = 0x0001, // like POSIX_SPAWN_SETSIGDEF
0188         IgnoreSigPipe                       = 0x0002,
0189         // some room if we want to add IgnoreSigHup or so
0190         CloseFileDescriptors                = 0x0010,
0191         UseVFork                            = 0x0020, // like POSIX_SPAWN_USEVFORK
0192         CreateNewSession                    = 0x0040, // like POSIX_SPAWN_SETSID
0193         DisconnectControllingTerminal       = 0x0080,
0194         ResetIds                            = 0x0100, // like POSIX_SPAWN_RESETIDS
0195         DisableCoreDumps                    = 0x0200,
0196     };
0197     Q_DECLARE_FLAGS(UnixProcessFlags, UnixProcessFlag)
0198     struct UnixProcessParameters
0199     {
0200         UnixProcessFlags flags = {};
0201         int lowestFileDescriptorToClose = 0;
0202
0203         quint32 _reserved[6] {};
0204     };
0205     UnixProcessParameters unixProcessParameters() const noexcept;
0206     void setUnixProcessParameters(const UnixProcessParameters &params);
0207     void setUnixProcessParameters(UnixProcessFlags flagsOnly);
0208 #endif
0209
0210     QString workingDirectory() const;
0211     void setWorkingDirectory(const QString &dir);
0212
0213     void setEnvironment(const QStringList &environment);
0214     QStringList environment() const;
0215     void setProcessEnvironment(const QProcessEnvironment &environment);
0216     QProcessEnvironment processEnvironment() const;
0217
0218     QProcess::ProcessError error() const;
0219     QProcess::ProcessState state() const;
0220
0221     qint64 processId() const;
0222
0223     bool waitForStarted(int msecs = 30000);
0224     bool waitForReadyRead(int msecs = 30000) override;
0225     bool waitForBytesWritten(int msecs = 30000) override;
0226     bool waitForFinished(int msecs = 30000);
0227
0228     QByteArray readAllStandardOutput();
0229     QByteArray readAllStandardError();
0230
0231     int exitCode() const;
0232     QProcess::ExitStatus exitStatus() const;
0233
0234     // QIODevice
0235     qint64 bytesToWrite() const override;
0236     bool isSequential() const override;
0237     void close() override;
0238
0239     static int execute(const QString &program, const QStringList &arguments = {});
0240     static bool startDetached(const QString &program, const QStringList &arguments = {},
0241                               const QString &workingDirectory = QString(), qint64 *pid = nullptr);
0242
0243     static QStringList systemEnvironment();
0244
0245     static QString nullDevice();
0246
0247     static QStringList splitCommand(QStringView command);
0248
0249 public Q_SLOTS:
0250     void terminate();
0251     void kill();
0252
0253 Q_SIGNALS:
0254     void started(QPrivateSignal);
0255     void finished(int exitCode, QProcess::ExitStatus exitStatus = NormalExit);
0256     void errorOccurred(QProcess::ProcessError error);
0257     void stateChanged(QProcess::ProcessState state, QPrivateSignal);
0258
0259     void readyReadStandardOutput(QPrivateSignal);
0260     void readyReadStandardError(QPrivateSignal);
0261
0262 protected:
0263     void setProcessState(ProcessState state);
0264
0265     // QIODevice
0266     qint64 readData(char *data, qint64 maxlen) override;
0267     qint64 writeData(const char *data, qint64 len) override;
0268
0269 private:
0270     Q_DECLARE_PRIVATE(QProcess)
0271     Q_DISABLE_COPY(QProcess)
0272
0273 #if QT_VERSION < QT_VERSION_CHECK(7,0,0)
0274     // ### Qt7: Remove this struct and the virtual function; they're here only
0275     // to cause build errors in Qt 5 code that wasn't updated to Qt 6's
0276     // setChildProcessModifier()
0277     struct Use_setChildProcessModifier_Instead {};
0278     QT_DEPRECATED_X("Use setChildProcessModifier() instead")
0279     virtual Use_setChildProcessModifier_Instead setupChildProcess();
0280 #endif
0281
0282     Q_PRIVATE_SLOT(d_func(), bool _q_canReadStandardOutput())
0283     Q_PRIVATE_SLOT(d_func(), bool _q_canReadStandardError())
0284 #ifdef Q_OS_UNIX
0285     Q_PRIVATE_SLOT(d_func(), bool _q_canWrite())
0286 #endif
0287     Q_PRIVATE_SLOT(d_func(), bool _q_startupNotification())
0288     Q_PRIVATE_SLOT(d_func(), void _q_processDied())
0289 };
0290
0291 #ifdef Q_OS_UNIX
0292 Q_DECLARE_OPERATORS_FOR_FLAGS(QProcess::UnixProcessFlags)
0293 #endif
0294
0295 #else // !QT_CONFIG(process)
0296
0297 class QProcess
0298 {
0299 public:
0300     Q_CORE_EXPORT static QStringList splitCommand(QStringView command);
0301
0302 private:
0303     QProcess() = delete;
0304     Q_DISABLE_COPY_MOVE(QProcess)
0305 };
0306
0307 #endif // QT_CONFIG(process)
0308
0309 QT_END_NAMESPACE
0310
0311 #endif // QPROCESS_H