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