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