1// Copyright (C) 2016 The Qt Company Ltd.
2// Copyright (C) 2023 Intel Corporation.
3// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR LGPL-3.0-only OR GPL-2.0-only OR GPL-3.0-only
4// Qt-Security score:critical reason:execute-external-code
5
6#ifndef QPROCESS_H
7#define QPROCESS_H
8
9#include <QtCore/qcompare.h>
10#include <QtCore/qiodevice.h>
11#include <QtCore/qstringlist.h>
12#include <QtCore/qshareddata.h>
13
14#include <functional>
15
16QT_REQUIRE_CONFIG(processenvironment);
17
18#if defined(Q_OS_WIN) || defined(Q_QDOC)
19struct _PROCESS_INFORMATION;
20struct _SECURITY_ATTRIBUTES;
21struct _STARTUPINFOW;
22using Q_PROCESS_INFORMATION = _PROCESS_INFORMATION;
23using Q_SECURITY_ATTRIBUTES = _SECURITY_ATTRIBUTES;
24using Q_STARTUPINFO = _STARTUPINFOW;
25#endif
26
27QT_BEGIN_NAMESPACE
28
29class QProcessPrivate;
30class QProcessEnvironmentPrivate;
31
32class Q_CORE_EXPORT QProcessEnvironment
33{
34public:
35 enum Initialization { InheritFromParent };
36
37 QProcessEnvironment();
38 QProcessEnvironment(Initialization) noexcept;
39 QProcessEnvironment(const QProcessEnvironment &other);
40 ~QProcessEnvironment();
41 QT_MOVE_ASSIGNMENT_OPERATOR_IMPL_VIA_PURE_SWAP(QProcessEnvironment)
42 QProcessEnvironment &operator=(const QProcessEnvironment &other);
43
44 void swap(QProcessEnvironment &other) noexcept { d.swap(other&: other.d); }
45
46#if QT_CORE_REMOVED_SINCE(6, 8)
47 bool operator==(const QProcessEnvironment &other) const;
48 inline bool operator!=(const QProcessEnvironment &other) const
49 { return !operator==(other); }
50#endif
51
52 bool isEmpty() const;
53 [[nodiscard]] bool inheritsFromParent() const;
54 void clear();
55
56 bool contains(const QString &name) const;
57 void insert(const QString &name, const QString &value);
58 void remove(const QString &name);
59 QString value(const QString &name, const QString &defaultValue = QString()) const;
60
61 QStringList toStringList() const;
62
63 QStringList keys() const;
64
65 void insert(const QProcessEnvironment &e);
66
67 static QProcessEnvironment systemEnvironment();
68
69private:
70 friend Q_CORE_EXPORT bool comparesEqual(const QProcessEnvironment &lhs,
71 const QProcessEnvironment &rhs);
72 Q_DECLARE_EQUALITY_COMPARABLE_NON_NOEXCEPT(QProcessEnvironment)
73 friend class QProcessPrivate;
74 friend class QProcessEnvironmentPrivate;
75 QSharedDataPointer<QProcessEnvironmentPrivate> d;
76};
77
78Q_DECLARE_SHARED(QProcessEnvironment)
79
80#if QT_CONFIG(process)
81
82class Q_CORE_EXPORT QProcess : public QIODevice
83{
84 Q_OBJECT
85public:
86 enum ProcessError {
87 FailedToStart,
88 Crashed,
89 Timedout,
90 ReadError,
91 WriteError,
92 UnknownError
93 };
94 Q_ENUM(ProcessError)
95
96 enum ProcessState {
97 NotRunning,
98 Starting,
99 Running
100 };
101 Q_ENUM(ProcessState)
102
103 enum ProcessChannel {
104 StandardOutput,
105 StandardError
106 };
107 Q_ENUM(ProcessChannel)
108
109 enum ProcessChannelMode {
110 SeparateChannels,
111 MergedChannels,
112 ForwardedChannels,
113 ForwardedOutputChannel,
114 ForwardedErrorChannel
115 };
116 Q_ENUM(ProcessChannelMode)
117
118 enum InputChannelMode {
119 ManagedInputChannel,
120 ForwardedInputChannel
121 };
122 Q_ENUM(InputChannelMode)
123
124 enum ExitStatus {
125 NormalExit,
126 CrashExit
127 };
128 Q_ENUM(ExitStatus)
129
130 explicit QProcess(QObject *parent = nullptr);
131 virtual ~QProcess();
132
133 void start(const QString &program, const QStringList &arguments = {}, OpenMode mode = ReadWrite);
134 void start(OpenMode mode = ReadWrite);
135 void startCommand(const QString &command, OpenMode mode = ReadWrite);
136 bool startDetached(qint64 *pid = nullptr);
137 bool open(OpenMode mode = ReadWrite) override;
138
139 QString program() const;
140 void setProgram(const QString &program);
141
142 QStringList arguments() const;
143 void setArguments(const QStringList & arguments);
144
145 ProcessChannelMode processChannelMode() const;
146 void setProcessChannelMode(ProcessChannelMode mode);
147 InputChannelMode inputChannelMode() const;
148 void setInputChannelMode(InputChannelMode mode);
149
150 ProcessChannel readChannel() const;
151 void setReadChannel(ProcessChannel channel);
152
153 void closeReadChannel(ProcessChannel channel);
154 void closeWriteChannel();
155
156 void setStandardInputFile(const QString &fileName);
157 void setStandardOutputFile(const QString &fileName, OpenMode mode = Truncate);
158 void setStandardErrorFile(const QString &fileName, OpenMode mode = Truncate);
159 void setStandardOutputProcess(QProcess *destination);
160
161#if defined(Q_OS_WIN) || defined(Q_QDOC)
162 QString nativeArguments() const;
163 void setNativeArguments(const QString &arguments);
164 struct CreateProcessArguments
165 {
166 const wchar_t *applicationName;
167 wchar_t *arguments;
168 Q_SECURITY_ATTRIBUTES *processAttributes;
169 Q_SECURITY_ATTRIBUTES *threadAttributes;
170 bool inheritHandles;
171 unsigned long flags;
172 void *environment;
173 const wchar_t *currentDirectory;
174 Q_STARTUPINFO *startupInfo;
175 Q_PROCESS_INFORMATION *processInformation;
176 };
177 typedef std::function<void(CreateProcessArguments *)> CreateProcessArgumentModifier;
178 CreateProcessArgumentModifier createProcessArgumentsModifier() const;
179 void setCreateProcessArgumentsModifier(CreateProcessArgumentModifier modifier);
180#endif // Q_OS_WIN || Q_QDOC
181#if defined(Q_OS_UNIX) || defined(Q_QDOC)
182 std::function<void(void)> childProcessModifier() const;
183 void setChildProcessModifier(const std::function<void(void)> &modifier);
184 Q_NORETURN void failChildProcessModifier(const char *description, int error = 0) noexcept;
185
186 enum class UnixProcessFlag : quint32 {
187 ResetSignalHandlers = 0x0001, // like POSIX_SPAWN_SETSIGDEF
188 IgnoreSigPipe = 0x0002,
189 // some room if we want to add IgnoreSigHup or so
190 CloseFileDescriptors = 0x0010,
191 UseVFork = 0x0020, // like POSIX_SPAWN_USEVFORK
192 CreateNewSession = 0x0040, // like POSIX_SPAWN_SETSID
193 DisconnectControllingTerminal = 0x0080,
194 ResetIds = 0x0100, // like POSIX_SPAWN_RESETIDS
195 DisableCoreDumps = 0x0200,
196 };
197 Q_DECLARE_FLAGS(UnixProcessFlags, UnixProcessFlag)
198 struct UnixProcessParameters
199 {
200 UnixProcessFlags flags = {};
201 int lowestFileDescriptorToClose = 0;
202
203 quint32 _reserved[6] {};
204 };
205 UnixProcessParameters unixProcessParameters() const noexcept;
206 void setUnixProcessParameters(const UnixProcessParameters &params);
207 void setUnixProcessParameters(UnixProcessFlags flagsOnly);
208#endif
209
210 QString workingDirectory() const;
211 void setWorkingDirectory(const QString &dir);
212
213 void setEnvironment(const QStringList &environment);
214 QStringList environment() const;
215 void setProcessEnvironment(const QProcessEnvironment &environment);
216 QProcessEnvironment processEnvironment() const;
217
218 QProcess::ProcessError error() const;
219 QProcess::ProcessState state() const;
220
221 qint64 processId() const;
222
223 bool waitForStarted(int msecs = 30000);
224 bool waitForReadyRead(int msecs = 30000) override;
225 bool waitForBytesWritten(int msecs = 30000) override;
226 bool waitForFinished(int msecs = 30000);
227
228 QByteArray readAllStandardOutput();
229 QByteArray readAllStandardError();
230
231 int exitCode() const;
232 QProcess::ExitStatus exitStatus() const;
233
234 // QIODevice
235 qint64 bytesToWrite() const override;
236 bool isSequential() const override;
237 void close() override;
238
239 static int execute(const QString &program, const QStringList &arguments = {});
240 static bool startDetached(const QString &program, const QStringList &arguments = {},
241 const QString &workingDirectory = QString(), qint64 *pid = nullptr);
242
243 static QStringList systemEnvironment();
244
245 static QString nullDevice();
246
247 static QStringList splitCommand(QStringView command);
248
249public Q_SLOTS:
250 void terminate();
251 void kill();
252
253Q_SIGNALS:
254 void started(QPrivateSignal);
255 void finished(int exitCode, QProcess::ExitStatus exitStatus = NormalExit);
256 void errorOccurred(QProcess::ProcessError error);
257 void stateChanged(QProcess::ProcessState state, QPrivateSignal);
258
259 void readyReadStandardOutput(QPrivateSignal);
260 void readyReadStandardError(QPrivateSignal);
261
262protected:
263 void setProcessState(ProcessState state);
264
265 // QIODevice
266 qint64 readData(char *data, qint64 maxlen) override;
267 qint64 writeData(const char *data, qint64 len) override;
268
269private:
270 Q_DECLARE_PRIVATE(QProcess)
271 Q_DISABLE_COPY(QProcess)
272
273#if QT_VERSION < QT_VERSION_CHECK(7,0,0)
274 // ### Qt7: Remove this struct and the virtual function; they're here only
275 // to cause build errors in Qt 5 code that wasn't updated to Qt 6's
276 // setChildProcessModifier()
277 struct Use_setChildProcessModifier_Instead {};
278 QT_DEPRECATED_X("Use setChildProcessModifier() instead")
279 virtual Use_setChildProcessModifier_Instead setupChildProcess();
280#endif
281
282 Q_PRIVATE_SLOT(d_func(), bool _q_canReadStandardOutput())
283 Q_PRIVATE_SLOT(d_func(), bool _q_canReadStandardError())
284#ifdef Q_OS_UNIX
285 Q_PRIVATE_SLOT(d_func(), bool _q_canWrite())
286#endif
287 Q_PRIVATE_SLOT(d_func(), bool _q_startupNotification())
288 Q_PRIVATE_SLOT(d_func(), void _q_processDied())
289};
290
291#ifdef Q_OS_UNIX
292Q_DECLARE_OPERATORS_FOR_FLAGS(QProcess::UnixProcessFlags)
293#endif
294
295#else // !QT_CONFIG(process)
296
297class QProcess
298{
299public:
300 Q_CORE_EXPORT static QStringList splitCommand(QStringView command);
301
302private:
303 QProcess() = delete;
304 Q_DISABLE_COPY_MOVE(QProcess)
305};
306
307#endif // QT_CONFIG(process)
308
309QT_END_NAMESPACE
310
311#endif // QPROCESS_H
312

source code of qtbase/src/corelib/io/qprocess.h