1/****************************************************************************
2**
3** Copyright (C) 2016 The Qt Company Ltd.
4** Copyright (C) 2016 Intel Corporation.
5** Contact: https://www.qt.io/licensing/
6**
7** This file is part of the QtCore module of the Qt Toolkit.
8**
9** $QT_BEGIN_LICENSE:LGPL$
10** Commercial License Usage
11** Licensees holding valid commercial Qt licenses may use this file in
12** accordance with the commercial license agreement provided with the
13** Software or, alternatively, in accordance with the terms contained in
14** a written agreement between you and The Qt Company. For licensing terms
15** and conditions see https://www.qt.io/terms-conditions. For further
16** information use the contact form at https://www.qt.io/contact-us.
17**
18** GNU Lesser General Public License Usage
19** Alternatively, this file may be used under the terms of the GNU Lesser
20** General Public License version 3 as published by the Free Software
21** Foundation and appearing in the file LICENSE.LGPL3 included in the
22** packaging of this file. Please review the following information to
23** ensure the GNU Lesser General Public License version 3 requirements
24** will be met: https://www.gnu.org/licenses/lgpl-3.0.html.
25**
26** GNU General Public License Usage
27** Alternatively, this file may be used under the terms of the GNU
28** General Public License version 2.0 or (at your option) the GNU General
29** Public license version 3 or any later version approved by the KDE Free
30** Qt Foundation. The licenses are as published by the Free Software
31** Foundation and appearing in the file LICENSE.GPL2 and LICENSE.GPL3
32** included in the packaging of this file. Please review the following
33** information to ensure the GNU General Public License requirements will
34** be met: https://www.gnu.org/licenses/gpl-2.0.html and
35** https://www.gnu.org/licenses/gpl-3.0.html.
36**
37** $QT_END_LICENSE$
38**
39****************************************************************************/
40
41//#define QPROCESS_DEBUG
42
43#include <qdebug.h>
44#include <qdir.h>
45#include <qscopedvaluerollback.h>
46#if defined(Q_OS_WIN)
47#include <qtimer.h>
48#endif
49#if defined QPROCESS_DEBUG
50#include <qstring.h>
51#include <ctype.h>
52
53QT_BEGIN_NAMESPACE
54/*
55 Returns a human readable representation of the first \a len
56 characters in \a data.
57*/
58static QByteArray qt_prettyDebug(const char *data, int len, int maxSize)
59{
60 if (!data) return "(null)";
61 QByteArray out;
62 for (int i = 0; i < len && i < maxSize; ++i) {
63 char c = data[i];
64 if (isprint(c)) {
65 out += c;
66 } else switch (c) {
67 case '\n': out += "\\n"; break;
68 case '\r': out += "\\r"; break;
69 case '\t': out += "\\t"; break;
70 default:
71 char buf[5];
72 qsnprintf(buf, sizeof(buf), "\\%3o", c);
73 buf[4] = '\0';
74 out += QByteArray(buf);
75 }
76 }
77
78 if (len < maxSize)
79 out += "...";
80
81 return out;
82}
83
84QT_END_NAMESPACE
85
86#endif
87
88#include "qprocess.h"
89#include "qprocess_p.h"
90
91#include <qbytearray.h>
92#include <qelapsedtimer.h>
93#include <qcoreapplication.h>
94#include <qsocketnotifier.h>
95#include <qtimer.h>
96
97#ifdef Q_OS_WIN
98#include <qwineventnotifier.h>
99#else
100#include <private/qcore_unix_p.h>
101#endif
102
103#if __has_include(<paths.h>)
104#include <paths.h>
105#endif
106
107QT_BEGIN_NAMESPACE
108
109/*!
110 \since 5.6
111
112 \macro QT_NO_PROCESS_COMBINED_ARGUMENT_START
113 \relates QProcess
114
115 Disables the
116 \l {QProcess::start(const QString &, QIODevice::OpenMode)}
117 {QProcess::start}() overload taking a single string.
118 In most cases where it is used, the user intends for the first argument
119 to be treated atomically as per the other overload.
120
121 \sa QProcess::start(const QString &command, QIODevice::OpenMode mode)
122*/
123
124/*!
125 \class QProcessEnvironment
126 \inmodule QtCore
127
128 \brief The QProcessEnvironment class holds the environment variables that
129 can be passed to a program.
130
131 \ingroup io
132 \ingroup misc
133 \ingroup shared
134 \reentrant
135 \since 4.6
136
137 A process's environment is composed of a set of key=value pairs known as
138 environment variables. The QProcessEnvironment class wraps that concept
139 and allows easy manipulation of those variables. It's meant to be used
140 along with QProcess, to set the environment for child processes. It
141 cannot be used to change the current process's environment.
142
143 The environment of the calling process can be obtained using
144 QProcessEnvironment::systemEnvironment().
145
146 On Unix systems, the variable names are case-sensitive. Note that the
147 Unix environment allows both variable names and contents to contain arbitrary
148 binary data (except for the NUL character). QProcessEnvironment will preserve
149 such variables, but does not support manipulating variables whose names or
150 values cannot be encoded by the current locale settings (see
151 QTextCodec::codecForLocale).
152
153 On Windows, the variable names are case-insensitive, but case-preserving.
154 QProcessEnvironment behaves accordingly.
155
156 \sa QProcess, QProcess::systemEnvironment(), QProcess::setProcessEnvironment()
157*/
158
159QStringList QProcessEnvironmentPrivate::toList() const
160{
161 QStringList result;
162 result.reserve(alloc: vars.size());
163 for (auto it = vars.cbegin(), end = vars.cend(); it != end; ++it)
164 result << nameToString(name: it.key()) + QLatin1Char('=') + valueToString(value: it.value());
165 return result;
166}
167
168QProcessEnvironment QProcessEnvironmentPrivate::fromList(const QStringList &list)
169{
170 QProcessEnvironment env;
171 QStringList::ConstIterator it = list.constBegin(),
172 end = list.constEnd();
173 for ( ; it != end; ++it) {
174 int pos = it->indexOf(c: QLatin1Char('='), from: 1);
175 if (pos < 1)
176 continue;
177
178 QString value = it->mid(position: pos + 1);
179 QString name = *it;
180 name.truncate(pos);
181 env.insert(name, value);
182 }
183 return env;
184}
185
186QStringList QProcessEnvironmentPrivate::keys() const
187{
188 QStringList result;
189 result.reserve(alloc: vars.size());
190 auto it = vars.constBegin();
191 const auto end = vars.constEnd();
192 for ( ; it != end; ++it)
193 result << nameToString(name: it.key());
194 return result;
195}
196
197void QProcessEnvironmentPrivate::insert(const QProcessEnvironmentPrivate &other)
198{
199 auto it = other.vars.constBegin();
200 const auto end = other.vars.constEnd();
201 for ( ; it != end; ++it)
202 vars.insert(akey: it.key(), avalue: it.value());
203
204#ifdef Q_OS_UNIX
205 const OrderedNameMapMutexLocker locker(this, &other);
206 auto nit = other.nameMap.constBegin();
207 const auto nend = other.nameMap.constEnd();
208 for ( ; nit != nend; ++nit)
209 nameMap.insert(akey: nit.key(), avalue: nit.value());
210#endif
211}
212
213/*!
214 Creates a new QProcessEnvironment object. This constructor creates an
215 empty environment. If set on a QProcess, this will cause the current
216 environment variables to be removed.
217*/
218QProcessEnvironment::QProcessEnvironment()
219 : d(nullptr)
220{
221}
222
223/*!
224 Frees the resources associated with this QProcessEnvironment object.
225*/
226QProcessEnvironment::~QProcessEnvironment()
227{
228}
229
230/*!
231 Creates a QProcessEnvironment object that is a copy of \a other.
232*/
233QProcessEnvironment::QProcessEnvironment(const QProcessEnvironment &other)
234 : d(other.d)
235{
236}
237
238/*!
239 Copies the contents of the \a other QProcessEnvironment object into this
240 one.
241*/
242QProcessEnvironment &QProcessEnvironment::operator=(const QProcessEnvironment &other)
243{
244 d = other.d;
245 return *this;
246}
247
248/*!
249 \fn void QProcessEnvironment::swap(QProcessEnvironment &other)
250 \since 5.0
251
252 Swaps this process environment instance with \a other. This
253 function is very fast and never fails.
254*/
255
256/*!
257 \fn bool QProcessEnvironment::operator !=(const QProcessEnvironment &other) const
258
259 Returns \c true if this and the \a other QProcessEnvironment objects are different.
260
261 \sa operator==()
262*/
263
264/*!
265 Returns \c true if this and the \a other QProcessEnvironment objects are equal.
266
267 Two QProcessEnvironment objects are considered equal if they have the same
268 set of key=value pairs. The comparison of keys is done case-sensitive on
269 platforms where the environment is case-sensitive.
270
271 \sa operator!=(), contains()
272*/
273bool QProcessEnvironment::operator==(const QProcessEnvironment &other) const
274{
275 if (d == other.d)
276 return true;
277 if (d) {
278 if (other.d) {
279 return d->vars == other.d->vars;
280 } else {
281 return isEmpty();
282 }
283 } else {
284 return other.isEmpty();
285 }
286}
287
288/*!
289 Returns \c true if this QProcessEnvironment object is empty: that is
290 there are no key=value pairs set.
291
292 \sa clear(), systemEnvironment(), insert()
293*/
294bool QProcessEnvironment::isEmpty() const
295{
296 // Needs no locking, as no hash nodes are accessed
297 return d ? d->vars.isEmpty() : true;
298}
299
300/*!
301 Removes all key=value pairs from this QProcessEnvironment object, making
302 it empty.
303
304 \sa isEmpty(), systemEnvironment()
305*/
306void QProcessEnvironment::clear()
307{
308 if (d)
309 d->vars.clear();
310 // Unix: Don't clear d->nameMap, as the environment is likely to be
311 // re-populated with the same keys again.
312}
313
314/*!
315 Returns \c true if the environment variable of name \a name is found in
316 this QProcessEnvironment object.
317
318
319 \sa insert(), value()
320*/
321bool QProcessEnvironment::contains(const QString &name) const
322{
323 if (!d)
324 return false;
325 return d->vars.contains(akey: d->prepareName(name));
326}
327
328/*!
329 Inserts the environment variable of name \a name and contents \a value
330 into this QProcessEnvironment object. If that variable already existed,
331 it is replaced by the new value.
332
333 On most systems, inserting a variable with no contents will have the
334 same effect for applications as if the variable had not been set at all.
335 However, to guarantee that there are no incompatibilities, to remove a
336 variable, please use the remove() function.
337
338 \sa contains(), remove(), value()
339*/
340void QProcessEnvironment::insert(const QString &name, const QString &value)
341{
342 // our re-impl of detach() detaches from null
343 d.detach(); // detach before prepareName()
344 d->vars.insert(akey: d->prepareName(name), avalue: d->prepareValue(value));
345}
346
347/*!
348 Removes the environment variable identified by \a name from this
349 QProcessEnvironment object. If that variable did not exist before,
350 nothing happens.
351
352
353 \sa contains(), insert(), value()
354*/
355void QProcessEnvironment::remove(const QString &name)
356{
357 if (d) {
358 d.detach(); // detach before prepareName()
359 d->vars.remove(akey: d->prepareName(name));
360 }
361}
362
363/*!
364 Searches this QProcessEnvironment object for a variable identified by
365 \a name and returns its value. If the variable is not found in this object,
366 then \a defaultValue is returned instead.
367
368 \sa contains(), insert(), remove()
369*/
370QString QProcessEnvironment::value(const QString &name, const QString &defaultValue) const
371{
372 if (!d)
373 return defaultValue;
374
375 const auto it = d->vars.constFind(akey: d->prepareName(name));
376 if (it == d->vars.constEnd())
377 return defaultValue;
378
379 return d->valueToString(value: it.value());
380}
381
382/*!
383 Converts this QProcessEnvironment object into a list of strings, one for
384 each environment variable that is set. The environment variable's name
385 and its value are separated by an equal character ('=').
386
387 The QStringList contents returned by this function are suitable for
388 presentation.
389 Use with the QProcess::setEnvironment function is not recommended due to
390 potential encoding problems under Unix, and worse performance.
391
392 \sa systemEnvironment(), QProcess::systemEnvironment(),
393 QProcess::setProcessEnvironment()
394*/
395QStringList QProcessEnvironment::toStringList() const
396{
397 if (!d)
398 return QStringList();
399 return d->toList();
400}
401
402/*!
403 \since 4.8
404
405 Returns a list containing all the variable names in this QProcessEnvironment
406 object.
407*/
408QStringList QProcessEnvironment::keys() const
409{
410 if (!d)
411 return QStringList();
412 return d->keys();
413}
414
415/*!
416 \overload
417 \since 4.8
418
419 Inserts the contents of \a e in this QProcessEnvironment object. Variables in
420 this object that also exist in \a e will be overwritten.
421*/
422void QProcessEnvironment::insert(const QProcessEnvironment &e)
423{
424 if (!e.d)
425 return;
426
427 // our re-impl of detach() detaches from null
428 d->insert(other: *e.d);
429}
430
431#if QT_CONFIG(process)
432
433void QProcessPrivate::Channel::clear()
434{
435 switch (type) {
436 case PipeSource:
437 Q_ASSERT(process);
438 process->stdinChannel.type = Normal;
439 process->stdinChannel.process = nullptr;
440 break;
441 case PipeSink:
442 Q_ASSERT(process);
443 process->stdoutChannel.type = Normal;
444 process->stdoutChannel.process = nullptr;
445 break;
446 }
447
448 type = Normal;
449 file.clear();
450 process = nullptr;
451}
452
453/*!
454 \class QProcess
455 \inmodule QtCore
456
457 \brief The QProcess class is used to start external programs and
458 to communicate with them.
459
460 \ingroup io
461
462 \reentrant
463
464 \section1 Running a Process
465
466 To start a process, pass the name and command line arguments of
467 the program you want to run as arguments to start(). Arguments
468 are supplied as individual strings in a QStringList.
469
470 Alternatively, you can set the program to run with setProgram()
471 and setArguments(), and then call start() or open().
472
473 For example, the following code snippet runs the analog clock
474 example in the Fusion style on X11 platforms by passing strings
475 containing "-style" and "fusion" as two items in the list of
476 arguments:
477
478 \snippet qprocess/qprocess-simpleexecution.cpp 0
479 \dots
480 \snippet qprocess/qprocess-simpleexecution.cpp 1
481 \snippet qprocess/qprocess-simpleexecution.cpp 2
482
483 QProcess then enters the \l Starting state, and when the program
484 has started, QProcess enters the \l Running state and emits
485 started().
486
487 QProcess allows you to treat a process as a sequential I/O
488 device. You can write to and read from the process just as you
489 would access a network connection using QTcpSocket. You can then
490 write to the process's standard input by calling write(), and
491 read the standard output by calling read(), readLine(), and
492 getChar(). Because it inherits QIODevice, QProcess can also be
493 used as an input source for QXmlReader, or for generating data to
494 be uploaded using QNetworkAccessManager.
495
496 When the process exits, QProcess reenters the \l NotRunning state
497 (the initial state), and emits finished().
498
499 The finished() signal provides the exit code and exit status of
500 the process as arguments, and you can also call exitCode() to
501 obtain the exit code of the last process that finished, and
502 exitStatus() to obtain its exit status. If an error occurs at
503 any point in time, QProcess will emit the errorOccurred() signal.
504 You can also call error() to find the type of error that occurred
505 last, and state() to find the current process state.
506
507 \note QProcess is not supported on VxWorks, iOS, tvOS, watchOS,
508 or the Universal Windows Platform.
509
510 \section1 Communicating via Channels
511
512 Processes have two predefined output channels: The standard
513 output channel (\c stdout) supplies regular console output, and
514 the standard error channel (\c stderr) usually supplies the
515 errors that are printed by the process. These channels represent
516 two separate streams of data. You can toggle between them by
517 calling setReadChannel(). QProcess emits readyRead() when data is
518 available on the current read channel. It also emits
519 readyReadStandardOutput() when new standard output data is
520 available, and when new standard error data is available,
521 readyReadStandardError() is emitted. Instead of calling read(),
522 readLine(), or getChar(), you can explicitly read all data from
523 either of the two channels by calling readAllStandardOutput() or
524 readAllStandardError().
525
526 The terminology for the channels can be misleading. Be aware that
527 the process's output channels correspond to QProcess's
528 \e read channels, whereas the process's input channels correspond
529 to QProcess's \e write channels. This is because what we read
530 using QProcess is the process's output, and what we write becomes
531 the process's input.
532
533 QProcess can merge the two output channels, so that standard
534 output and standard error data from the running process both use
535 the standard output channel. Call setProcessChannelMode() with
536 MergedChannels before starting the process to activate
537 this feature. You also have the option of forwarding the output of
538 the running process to the calling, main process, by passing
539 ForwardedChannels as the argument. It is also possible to forward
540 only one of the output channels - typically one would use
541 ForwardedErrorChannel, but ForwardedOutputChannel also exists.
542 Note that using channel forwarding is typically a bad idea in GUI
543 applications - you should present errors graphically instead.
544
545 Certain processes need special environment settings in order to
546 operate. You can set environment variables for your process by
547 calling setProcessEnvironment(). To set a working directory, call
548 setWorkingDirectory(). By default, processes are run in the
549 current working directory of the calling process.
550
551 The positioning and the screen Z-order of windows belonging to
552 GUI applications started with QProcess are controlled by
553 the underlying windowing system. For Qt 5 applications, the
554 positioning can be specified using the \c{-qwindowgeometry}
555 command line option; X11 applications generally accept a
556 \c{-geometry} command line option.
557
558 \note On QNX, setting the working directory may cause all
559 application threads, with the exception of the QProcess caller
560 thread, to temporarily freeze during the spawning process,
561 owing to a limitation in the operating system.
562
563 \section1 Synchronous Process API
564
565 QProcess provides a set of functions which allow it to be used
566 without an event loop, by suspending the calling thread until
567 certain signals are emitted:
568
569 \list
570 \li waitForStarted() blocks until the process has started.
571
572 \li waitForReadyRead() blocks until new data is
573 available for reading on the current read channel.
574
575 \li waitForBytesWritten() blocks until one payload of
576 data has been written to the process.
577
578 \li waitForFinished() blocks until the process has finished.
579 \endlist
580
581 Calling these functions from the main thread (the thread that
582 calls QApplication::exec()) may cause your user interface to
583 freeze.
584
585 The following example runs \c gzip to compress the string "Qt
586 rocks!", without an event loop:
587
588 \snippet process/process.cpp 0
589
590 \section1 Notes for Windows Users
591
592 Some Windows commands (for example, \c dir) are not provided by
593 separate applications, but by the command interpreter itself.
594 If you attempt to use QProcess to execute these commands directly,
595 it won't work. One possible solution is to execute the command
596 interpreter itself (\c{cmd.exe} on some Windows systems), and ask
597 the interpreter to execute the desired command.
598
599 \sa QBuffer, QFile, QTcpSocket
600*/
601
602/*!
603 \enum QProcess::ProcessChannel
604
605 This enum describes the process channels used by the running process.
606 Pass one of these values to setReadChannel() to set the
607 current read channel of QProcess.
608
609 \value StandardOutput The standard output (stdout) of the running
610 process.
611
612 \value StandardError The standard error (stderr) of the running
613 process.
614
615 \sa setReadChannel()
616*/
617
618/*!
619 \enum QProcess::ProcessChannelMode
620
621 This enum describes the process output channel modes of QProcess.
622 Pass one of these values to setProcessChannelMode() to set the
623 current read channel mode.
624
625 \value SeparateChannels QProcess manages the output of the
626 running process, keeping standard output and standard error data
627 in separate internal buffers. You can select the QProcess's
628 current read channel by calling setReadChannel(). This is the
629 default channel mode of QProcess.
630
631 \value MergedChannels QProcess merges the output of the running
632 process into the standard output channel (\c stdout). The
633 standard error channel (\c stderr) will not receive any data. The
634 standard output and standard error data of the running process
635 are interleaved.
636
637 \value ForwardedChannels QProcess forwards the output of the
638 running process onto the main process. Anything the child process
639 writes to its standard output and standard error will be written
640 to the standard output and standard error of the main process.
641
642 \value ForwardedErrorChannel QProcess manages the standard output
643 of the running process, but forwards its standard error onto the
644 main process. This reflects the typical use of command line tools
645 as filters, where the standard output is redirected to another
646 process or a file, while standard error is printed to the console
647 for diagnostic purposes.
648 (This value was introduced in Qt 5.2.)
649
650 \value ForwardedOutputChannel Complementary to ForwardedErrorChannel.
651 (This value was introduced in Qt 5.2.)
652
653 \note Windows intentionally suppresses output from GUI-only
654 applications to inherited consoles.
655 This does \e not apply to output redirected to files or pipes.
656 To forward the output of GUI-only applications on the console
657 nonetheless, you must use SeparateChannels and do the forwarding
658 yourself by reading the output and writing it to the appropriate
659 output channels.
660
661 \sa setProcessChannelMode()
662*/
663
664/*!
665 \enum QProcess::InputChannelMode
666 \since 5.2
667
668 This enum describes the process input channel modes of QProcess.
669 Pass one of these values to setInputChannelMode() to set the
670 current write channel mode.
671
672 \value ManagedInputChannel QProcess manages the input of the running
673 process. This is the default input channel mode of QProcess.
674
675 \value ForwardedInputChannel QProcess forwards the input of the main
676 process onto the running process. The child process reads its standard
677 input from the same source as the main process.
678 Note that the main process must not try to read its standard input
679 while the child process is running.
680
681 \sa setInputChannelMode()
682*/
683
684/*!
685 \enum QProcess::ProcessError
686
687 This enum describes the different types of errors that are
688 reported by QProcess.
689
690 \value FailedToStart The process failed to start. Either the
691 invoked program is missing, or you may have insufficient
692 permissions to invoke the program.
693
694 \value Crashed The process crashed some time after starting
695 successfully.
696
697 \value Timedout The last waitFor...() function timed out. The
698 state of QProcess is unchanged, and you can try calling
699 waitFor...() again.
700
701 \value WriteError An error occurred when attempting to write to the
702 process. For example, the process may not be running, or it may
703 have closed its input channel.
704
705 \value ReadError An error occurred when attempting to read from
706 the process. For example, the process may not be running.
707
708 \value UnknownError An unknown error occurred. This is the default
709 return value of error().
710
711 \sa error()
712*/
713
714/*!
715 \enum QProcess::ProcessState
716
717 This enum describes the different states of QProcess.
718
719 \value NotRunning The process is not running.
720
721 \value Starting The process is starting, but the program has not
722 yet been invoked.
723
724 \value Running The process is running and is ready for reading and
725 writing.
726
727 \sa state()
728*/
729
730/*!
731 \enum QProcess::ExitStatus
732
733 This enum describes the different exit statuses of QProcess.
734
735 \value NormalExit The process exited normally.
736
737 \value CrashExit The process crashed.
738
739 \sa exitStatus()
740*/
741
742/*!
743 \typedef QProcess::CreateProcessArgumentModifier
744 \note This typedef is only available on desktop Windows.
745
746 On Windows, QProcess uses the Win32 API function \c CreateProcess to
747 start child processes. While QProcess provides a comfortable way to start
748 processes without worrying about platform
749 details, it is in some cases desirable to fine-tune the parameters that are
750 passed to \c CreateProcess. This is done by defining a
751 \c CreateProcessArgumentModifier function and passing it to
752 \c setCreateProcessArgumentsModifier.
753
754 A \c CreateProcessArgumentModifier function takes one parameter: a pointer
755 to a \c CreateProcessArguments struct. The members of this struct will be
756 passed to \c CreateProcess after the \c CreateProcessArgumentModifier
757 function is called.
758
759 The following example demonstrates how to pass custom flags to
760 \c CreateProcess.
761 When starting a console process B from a console process A, QProcess will
762 reuse the console window of process A for process B by default. In this
763 example, a new console window with a custom color scheme is created for the
764 child process B instead.
765
766 \snippet qprocess/qprocess-createprocessargumentsmodifier.cpp 0
767
768 \sa QProcess::CreateProcessArguments
769 \sa setCreateProcessArgumentsModifier()
770*/
771
772/*!
773 \class QProcess::CreateProcessArguments
774 \inmodule QtCore
775 \note This struct is only available on the Windows platform.
776
777 This struct is a representation of all parameters of the Windows API
778 function \c CreateProcess. It is used as parameter for
779 \c CreateProcessArgumentModifier functions.
780
781 \sa QProcess::CreateProcessArgumentModifier
782*/
783
784/*!
785 \fn void QProcess::error(QProcess::ProcessError error)
786 \obsolete
787
788 Use errorOccurred() instead.
789*/
790
791/*!
792 \fn void QProcess::errorOccurred(QProcess::ProcessError error)
793 \since 5.6
794
795 This signal is emitted when an error occurs with the process. The
796 specified \a error describes the type of error that occurred.
797*/
798
799/*!
800 \fn void QProcess::started()
801
802 This signal is emitted by QProcess when the process has started,
803 and state() returns \l Running.
804*/
805
806/*!
807 \fn void QProcess::stateChanged(QProcess::ProcessState newState)
808
809 This signal is emitted whenever the state of QProcess changes. The
810 \a newState argument is the state QProcess changed to.
811*/
812
813#if QT_DEPRECATED_SINCE(5, 13)
814/*!
815 \fn void QProcess::finished(int exitCode)
816 \obsolete
817 \overload
818
819 Use finished(int exitCode, QProcess::ExitStatus status) instead.
820*/
821#endif
822
823/*!
824 \fn void QProcess::finished(int exitCode, QProcess::ExitStatus exitStatus)
825
826 This signal is emitted when the process finishes. \a exitCode is the exit
827 code of the process (only valid for normal exits), and \a exitStatus is
828 the exit status.
829 After the process has finished, the buffers in QProcess are still intact.
830 You can still read any data that the process may have written before it
831 finished.
832
833 \sa exitStatus()
834*/
835
836/*!
837 \fn void QProcess::readyReadStandardOutput()
838
839 This signal is emitted when the process has made new data
840 available through its standard output channel (\c stdout). It is
841 emitted regardless of the current \l{readChannel()}{read channel}.
842
843 \sa readAllStandardOutput(), readChannel()
844*/
845
846/*!
847 \fn void QProcess::readyReadStandardError()
848
849 This signal is emitted when the process has made new data
850 available through its standard error channel (\c stderr). It is
851 emitted regardless of the current \l{readChannel()}{read
852 channel}.
853
854 \sa readAllStandardError(), readChannel()
855*/
856
857/*!
858 \internal
859*/
860QProcessPrivate::QProcessPrivate()
861{
862 readBufferChunkSize = QRINGBUFFER_CHUNKSIZE;
863 writeBufferChunkSize = QRINGBUFFER_CHUNKSIZE;
864 processChannelMode = QProcess::SeparateChannels;
865 inputChannelMode = QProcess::ManagedInputChannel;
866 processError = QProcess::UnknownError;
867 processState = QProcess::NotRunning;
868 pid = 0;
869 sequenceNumber = 0;
870 exitCode = 0;
871 exitStatus = QProcess::NormalExit;
872 startupSocketNotifier = nullptr;
873 deathNotifier = nullptr;
874 childStartedPipe[0] = INVALID_Q_PIPE;
875 childStartedPipe[1] = INVALID_Q_PIPE;
876 forkfd = -1;
877 crashed = false;
878 dying = false;
879 emittedReadyRead = false;
880 emittedBytesWritten = false;
881#ifdef Q_OS_WIN
882 stdinWriteTrigger = 0;
883 processFinishedNotifier = 0;
884#endif // Q_OS_WIN
885}
886
887/*!
888 \internal
889*/
890QProcessPrivate::~QProcessPrivate()
891{
892 if (stdinChannel.process)
893 stdinChannel.process->stdoutChannel.clear();
894 if (stdoutChannel.process)
895 stdoutChannel.process->stdinChannel.clear();
896}
897
898/*!
899 \internal
900*/
901void QProcessPrivate::cleanup()
902{
903 q_func()->setProcessState(QProcess::NotRunning);
904#ifdef Q_OS_WIN
905 if (pid) {
906 CloseHandle(pid->hThread);
907 CloseHandle(pid->hProcess);
908 delete pid;
909 pid = 0;
910 }
911 if (stdinWriteTrigger) {
912 delete stdinWriteTrigger;
913 stdinWriteTrigger = 0;
914 }
915 if (processFinishedNotifier) {
916 delete processFinishedNotifier;
917 processFinishedNotifier = 0;
918 }
919
920#endif
921 pid = 0;
922 sequenceNumber = 0;
923 dying = false;
924
925 if (stdoutChannel.notifier) {
926 delete stdoutChannel.notifier;
927 stdoutChannel.notifier = nullptr;
928 }
929 if (stderrChannel.notifier) {
930 delete stderrChannel.notifier;
931 stderrChannel.notifier = nullptr;
932 }
933 if (stdinChannel.notifier) {
934 delete stdinChannel.notifier;
935 stdinChannel.notifier = nullptr;
936 }
937 if (startupSocketNotifier) {
938 delete startupSocketNotifier;
939 startupSocketNotifier = nullptr;
940 }
941 if (deathNotifier) {
942 delete deathNotifier;
943 deathNotifier = nullptr;
944 }
945 closeChannel(channel: &stdoutChannel);
946 closeChannel(channel: &stderrChannel);
947 closeChannel(channel: &stdinChannel);
948 destroyPipe(pipe: childStartedPipe);
949#ifdef Q_OS_UNIX
950 if (forkfd != -1)
951 qt_safe_close(fd: forkfd);
952 forkfd = -1;
953#endif
954}
955
956/*!
957 \internal
958*/
959void QProcessPrivate::setError(QProcess::ProcessError error, const QString &description)
960{
961 processError = error;
962 if (description.isEmpty()) {
963 switch (error) {
964 case QProcess::FailedToStart:
965 errorString = QProcess::tr(s: "Process failed to start");
966 break;
967 case QProcess::Crashed:
968 errorString = QProcess::tr(s: "Process crashed");
969 break;
970 case QProcess::Timedout:
971 errorString = QProcess::tr(s: "Process operation timed out");
972 break;
973 case QProcess::ReadError:
974 errorString = QProcess::tr(s: "Error reading from process");
975 break;
976 case QProcess::WriteError:
977 errorString = QProcess::tr(s: "Error writing to process");
978 break;
979 case QProcess::UnknownError:
980 errorString.clear();
981 break;
982 }
983 } else {
984 errorString = description;
985 }
986}
987
988/*!
989 \internal
990*/
991void QProcessPrivate::setErrorAndEmit(QProcess::ProcessError error, const QString &description)
992{
993 Q_Q(QProcess);
994 Q_ASSERT(error != QProcess::UnknownError);
995 setError(error, description);
996 emit q->errorOccurred(error: processError);
997#if QT_DEPRECATED_SINCE(5, 6)
998QT_WARNING_PUSH
999QT_WARNING_DISABLE_DEPRECATED
1000 emit q->error(error: processError);
1001QT_WARNING_POP
1002#endif
1003}
1004
1005/*!
1006 \internal
1007 Returns \c true if we emitted readyRead().
1008*/
1009bool QProcessPrivate::tryReadFromChannel(Channel *channel)
1010{
1011 Q_Q(QProcess);
1012 if (channel->pipe[0] == INVALID_Q_PIPE)
1013 return false;
1014
1015 qint64 available = bytesAvailableInChannel(channel);
1016 if (available == 0)
1017 available = 1; // always try to read at least one byte
1018
1019 QProcess::ProcessChannel channelIdx = (channel == &stdoutChannel
1020 ? QProcess::StandardOutput
1021 : QProcess::StandardError);
1022 Q_ASSERT(readBuffers.size() > int(channelIdx));
1023 QRingBuffer &readBuffer = readBuffers[int(channelIdx)];
1024 char *ptr = readBuffer.reserve(bytes: available);
1025 qint64 readBytes = readFromChannel(channel, data: ptr, maxlen: available);
1026 if (readBytes <= 0)
1027 readBuffer.chop(bytes: available);
1028 if (readBytes == -2) {
1029 // EWOULDBLOCK
1030 return false;
1031 }
1032 if (readBytes == -1) {
1033 setErrorAndEmit(error: QProcess::ReadError);
1034#if defined QPROCESS_DEBUG
1035 qDebug("QProcessPrivate::tryReadFromChannel(%d), failed to read from the process",
1036 int(channel - &stdinChannel));
1037#endif
1038 return false;
1039 }
1040 if (readBytes == 0) {
1041 // EOF
1042 if (channel->notifier)
1043 channel->notifier->setEnabled(false);
1044 closeChannel(channel);
1045#if defined QPROCESS_DEBUG
1046 qDebug("QProcessPrivate::tryReadFromChannel(%d), 0 bytes available",
1047 int(channel - &stdinChannel));
1048#endif
1049 return false;
1050 }
1051#if defined QPROCESS_DEBUG
1052 qDebug("QProcessPrivate::tryReadFromChannel(%d), read %lld bytes from the process' output",
1053 int(channel - &stdinChannel), readBytes);
1054#endif
1055
1056 if (channel->closed) {
1057 readBuffer.chop(bytes: readBytes);
1058 return false;
1059 }
1060
1061 readBuffer.chop(bytes: available - readBytes);
1062
1063 bool didRead = false;
1064 if (currentReadChannel == channelIdx) {
1065 didRead = true;
1066 if (!emittedReadyRead) {
1067 QScopedValueRollback<bool> guard(emittedReadyRead, true);
1068 emit q->readyRead();
1069 }
1070 }
1071 emit q->channelReadyRead(channel: int(channelIdx));
1072 if (channelIdx == QProcess::StandardOutput)
1073 emit q->readyReadStandardOutput(QProcess::QPrivateSignal());
1074 else
1075 emit q->readyReadStandardError(QProcess::QPrivateSignal());
1076 return didRead;
1077}
1078
1079/*!
1080 \internal
1081*/
1082bool QProcessPrivate::_q_canReadStandardOutput()
1083{
1084 return tryReadFromChannel(channel: &stdoutChannel);
1085}
1086
1087/*!
1088 \internal
1089*/
1090bool QProcessPrivate::_q_canReadStandardError()
1091{
1092 return tryReadFromChannel(channel: &stderrChannel);
1093}
1094
1095/*!
1096 \internal
1097*/
1098bool QProcessPrivate::_q_canWrite()
1099{
1100 if (writeBuffer.isEmpty()) {
1101 if (stdinChannel.notifier)
1102 stdinChannel.notifier->setEnabled(false);
1103#if defined QPROCESS_DEBUG
1104 qDebug("QProcessPrivate::canWrite(), not writing anything (empty write buffer).");
1105#endif
1106 return false;
1107 }
1108
1109 const bool writeSucceeded = writeToStdin();
1110
1111 if (writeBuffer.isEmpty() && stdinChannel.closed)
1112 closeWriteChannel();
1113 else if (stdinChannel.notifier)
1114 stdinChannel.notifier->setEnabled(!writeBuffer.isEmpty());
1115 return writeSucceeded;
1116}
1117
1118/*!
1119 \internal
1120*/
1121bool QProcessPrivate::_q_processDied()
1122{
1123 Q_Q(QProcess);
1124#if defined QPROCESS_DEBUG
1125 qDebug("QProcessPrivate::_q_processDied()");
1126#endif
1127#ifdef Q_OS_UNIX
1128 if (!waitForDeadChild())
1129 return false;
1130#endif
1131#ifdef Q_OS_WIN
1132 if (processFinishedNotifier)
1133 processFinishedNotifier->setEnabled(false);
1134 drainOutputPipes();
1135#endif
1136
1137 // the process may have died before it got a chance to report that it was
1138 // either running or stopped, so we will call _q_startupNotification() and
1139 // give it a chance to emit started() or errorOccurred(FailedToStart).
1140 if (processState == QProcess::Starting) {
1141 if (!_q_startupNotification())
1142 return true;
1143 }
1144
1145 if (dying) {
1146 // at this point we know the process is dead. prevent
1147 // reentering this slot recursively by calling waitForFinished()
1148 // or opening a dialog inside slots connected to the readyRead
1149 // signals emitted below.
1150 return true;
1151 }
1152 dying = true;
1153
1154 // in case there is data in the pipe line and this slot by chance
1155 // got called before the read notifications, call these two slots
1156 // so the data is made available before the process dies.
1157 _q_canReadStandardOutput();
1158 _q_canReadStandardError();
1159
1160 findExitCode();
1161
1162 if (crashed) {
1163 exitStatus = QProcess::CrashExit;
1164 setErrorAndEmit(error: QProcess::Crashed);
1165 }
1166
1167 bool wasRunning = (processState == QProcess::Running);
1168
1169 cleanup();
1170
1171 if (wasRunning) {
1172 // we received EOF now:
1173 emit q->readChannelFinished();
1174 // in the future:
1175 //emit q->standardOutputClosed();
1176 //emit q->standardErrorClosed();
1177
1178#if QT_DEPRECATED_SINCE(5, 13)
1179QT_WARNING_PUSH
1180QT_WARNING_DISABLE_DEPRECATED
1181 emit q->finished(exitCode);
1182QT_WARNING_POP
1183#endif
1184 emit q->finished(exitCode, exitStatus);
1185 }
1186#if defined QPROCESS_DEBUG
1187 qDebug("QProcessPrivate::_q_processDied() process is dead");
1188#endif
1189 return true;
1190}
1191
1192/*!
1193 \internal
1194*/
1195bool QProcessPrivate::_q_startupNotification()
1196{
1197 Q_Q(QProcess);
1198#if defined QPROCESS_DEBUG
1199 qDebug("QProcessPrivate::startupNotification()");
1200#endif
1201
1202 if (startupSocketNotifier)
1203 startupSocketNotifier->setEnabled(false);
1204 QString errorMessage;
1205 if (processStarted(errorMessage: &errorMessage)) {
1206 q->setProcessState(QProcess::Running);
1207 emit q->started(QProcess::QPrivateSignal());
1208 return true;
1209 }
1210
1211 q->setProcessState(QProcess::NotRunning);
1212 setErrorAndEmit(error: QProcess::FailedToStart, description: errorMessage);
1213#ifdef Q_OS_UNIX
1214 // make sure the process manager removes this entry
1215 waitForDeadChild();
1216 findExitCode();
1217#endif
1218 cleanup();
1219 return false;
1220}
1221
1222/*!
1223 \internal
1224*/
1225void QProcessPrivate::closeWriteChannel()
1226{
1227#if defined QPROCESS_DEBUG
1228 qDebug("QProcessPrivate::closeWriteChannel()");
1229#endif
1230 if (stdinChannel.notifier) {
1231 delete stdinChannel.notifier;
1232 stdinChannel.notifier = nullptr;
1233 }
1234#ifdef Q_OS_WIN
1235 // ### Find a better fix, feeding the process little by little
1236 // instead.
1237 flushPipeWriter();
1238#endif
1239 closeChannel(channel: &stdinChannel);
1240}
1241
1242/*!
1243 Constructs a QProcess object with the given \a parent.
1244*/
1245QProcess::QProcess(QObject *parent)
1246 : QIODevice(*new QProcessPrivate, parent)
1247{
1248#if defined QPROCESS_DEBUG
1249 qDebug("QProcess::QProcess(%p)", parent);
1250#endif
1251}
1252
1253/*!
1254 Destructs the QProcess object, i.e., killing the process.
1255
1256 Note that this function will not return until the process is
1257 terminated.
1258*/
1259QProcess::~QProcess()
1260{
1261 Q_D(QProcess);
1262 if (d->processState != NotRunning) {
1263 qWarning().nospace()
1264 << "QProcess: Destroyed while process (" << QDir::toNativeSeparators(pathName: program()) << ") is still running.";
1265 kill();
1266 waitForFinished();
1267 }
1268#ifdef Q_OS_UNIX
1269 // make sure the process manager removes this entry
1270 d->findExitCode();
1271#endif
1272 d->cleanup();
1273}
1274
1275#if QT_DEPRECATED_SINCE(5, 13)
1276/*!
1277 \obsolete
1278 Returns the read channel mode of the QProcess. This function is
1279 equivalent to processChannelMode()
1280
1281 \sa processChannelMode()
1282*/
1283QProcess::ProcessChannelMode QProcess::readChannelMode() const
1284{
1285 return processChannelMode();
1286}
1287
1288/*!
1289 \obsolete
1290
1291 Use setProcessChannelMode(\a mode) instead.
1292
1293 \sa setProcessChannelMode()
1294*/
1295void QProcess::setReadChannelMode(ProcessChannelMode mode)
1296{
1297 setProcessChannelMode(mode);
1298}
1299#endif
1300
1301/*!
1302 \since 4.2
1303
1304 Returns the channel mode of the QProcess standard output and
1305 standard error channels.
1306
1307 \sa setProcessChannelMode(), ProcessChannelMode, setReadChannel()
1308*/
1309QProcess::ProcessChannelMode QProcess::processChannelMode() const
1310{
1311 Q_D(const QProcess);
1312 return d->processChannelMode;
1313}
1314
1315/*!
1316 \since 4.2
1317
1318 Sets the channel mode of the QProcess standard output and standard
1319 error channels to the \a mode specified.
1320 This mode will be used the next time start() is called. For example:
1321
1322 \snippet code/src_corelib_io_qprocess.cpp 0
1323
1324 \sa processChannelMode(), ProcessChannelMode, setReadChannel()
1325*/
1326void QProcess::setProcessChannelMode(ProcessChannelMode mode)
1327{
1328 Q_D(QProcess);
1329 d->processChannelMode = mode;
1330}
1331
1332/*!
1333 \since 5.2
1334
1335 Returns the channel mode of the QProcess standard input channel.
1336
1337 \sa setInputChannelMode(), InputChannelMode
1338*/
1339QProcess::InputChannelMode QProcess::inputChannelMode() const
1340{
1341 Q_D(const QProcess);
1342 return d->inputChannelMode;
1343}
1344
1345/*!
1346 \since 5.2
1347
1348 Sets the channel mode of the QProcess standard input
1349 channel to the \a mode specified.
1350 This mode will be used the next time start() is called.
1351
1352 \sa inputChannelMode(), InputChannelMode
1353*/
1354void QProcess::setInputChannelMode(InputChannelMode mode)
1355{
1356 Q_D(QProcess);
1357 d->inputChannelMode = mode;
1358}
1359
1360/*!
1361 Returns the current read channel of the QProcess.
1362
1363 \sa setReadChannel()
1364*/
1365QProcess::ProcessChannel QProcess::readChannel() const
1366{
1367 Q_D(const QProcess);
1368 return ProcessChannel(d->currentReadChannel);
1369}
1370
1371/*!
1372 Sets the current read channel of the QProcess to the given \a
1373 channel. The current input channel is used by the functions
1374 read(), readAll(), readLine(), and getChar(). It also determines
1375 which channel triggers QProcess to emit readyRead().
1376
1377 \sa readChannel()
1378*/
1379void QProcess::setReadChannel(ProcessChannel channel)
1380{
1381 QIODevice::setCurrentReadChannel(int(channel));
1382}
1383
1384/*!
1385 Closes the read channel \a channel. After calling this function,
1386 QProcess will no longer receive data on the channel. Any data that
1387 has already been received is still available for reading.
1388
1389 Call this function to save memory, if you are not interested in
1390 the output of the process.
1391
1392 \sa closeWriteChannel(), setReadChannel()
1393*/
1394void QProcess::closeReadChannel(ProcessChannel channel)
1395{
1396 Q_D(QProcess);
1397
1398 if (channel == StandardOutput)
1399 d->stdoutChannel.closed = true;
1400 else
1401 d->stderrChannel.closed = true;
1402}
1403
1404/*!
1405 Schedules the write channel of QProcess to be closed. The channel
1406 will close once all data has been written to the process. After
1407 calling this function, any attempts to write to the process will
1408 fail.
1409
1410 Closing the write channel is necessary for programs that read
1411 input data until the channel has been closed. For example, the
1412 program "more" is used to display text data in a console on both
1413 Unix and Windows. But it will not display the text data until
1414 QProcess's write channel has been closed. Example:
1415
1416 \snippet code/src_corelib_io_qprocess.cpp 1
1417
1418 The write channel is implicitly opened when start() is called.
1419
1420 \sa closeReadChannel()
1421*/
1422void QProcess::closeWriteChannel()
1423{
1424 Q_D(QProcess);
1425 d->stdinChannel.closed = true; // closing
1426 if (d->writeBuffer.isEmpty())
1427 d->closeWriteChannel();
1428}
1429
1430/*!
1431 \since 4.2
1432
1433 Redirects the process' standard input to the file indicated by \a
1434 fileName. When an input redirection is in place, the QProcess
1435 object will be in read-only mode (calling write() will result in
1436 error).
1437
1438 To make the process read EOF right away, pass nullDevice() here.
1439 This is cleaner than using closeWriteChannel() before writing any
1440 data, because it can be set up prior to starting the process.
1441
1442 If the file \a fileName does not exist at the moment start() is
1443 called or is not readable, starting the process will fail.
1444
1445 Calling setStandardInputFile() after the process has started has no
1446 effect.
1447
1448 \sa setStandardOutputFile(), setStandardErrorFile(),
1449 setStandardOutputProcess()
1450*/
1451void QProcess::setStandardInputFile(const QString &fileName)
1452{
1453 Q_D(QProcess);
1454 d->stdinChannel = fileName;
1455}
1456
1457/*!
1458 \since 4.2
1459
1460 Redirects the process' standard output to the file \a
1461 fileName. When the redirection is in place, the standard output
1462 read channel is closed: reading from it using read() will always
1463 fail, as will readAllStandardOutput().
1464
1465 To discard all standard output from the process, pass nullDevice()
1466 here. This is more efficient than simply never reading the standard
1467 output, as no QProcess buffers are filled.
1468
1469 If the file \a fileName doesn't exist at the moment start() is
1470 called, it will be created. If it cannot be created, the starting
1471 will fail.
1472
1473 If the file exists and \a mode is QIODevice::Truncate, the file
1474 will be truncated. Otherwise (if \a mode is QIODevice::Append),
1475 the file will be appended to.
1476
1477 Calling setStandardOutputFile() after the process has started has
1478 no effect.
1479
1480 \sa setStandardInputFile(), setStandardErrorFile(),
1481 setStandardOutputProcess()
1482*/
1483void QProcess::setStandardOutputFile(const QString &fileName, OpenMode mode)
1484{
1485 Q_ASSERT(mode == Append || mode == Truncate);
1486 Q_D(QProcess);
1487
1488 d->stdoutChannel = fileName;
1489 d->stdoutChannel.append = mode == Append;
1490}
1491
1492/*!
1493 \since 4.2
1494
1495 Redirects the process' standard error to the file \a
1496 fileName. When the redirection is in place, the standard error
1497 read channel is closed: reading from it using read() will always
1498 fail, as will readAllStandardError(). The file will be appended to
1499 if \a mode is Append, otherwise, it will be truncated.
1500
1501 See setStandardOutputFile() for more information on how the file
1502 is opened.
1503
1504 Note: if setProcessChannelMode() was called with an argument of
1505 QProcess::MergedChannels, this function has no effect.
1506
1507 \sa setStandardInputFile(), setStandardOutputFile(),
1508 setStandardOutputProcess()
1509*/
1510void QProcess::setStandardErrorFile(const QString &fileName, OpenMode mode)
1511{
1512 Q_ASSERT(mode == Append || mode == Truncate);
1513 Q_D(QProcess);
1514
1515 d->stderrChannel = fileName;
1516 d->stderrChannel.append = mode == Append;
1517}
1518
1519/*!
1520 \since 4.2
1521
1522 Pipes the standard output stream of this process to the \a
1523 destination process' standard input.
1524
1525 The following shell command:
1526 \snippet code/src_corelib_io_qprocess.cpp 2
1527
1528 Can be accomplished with QProcess with the following code:
1529 \snippet code/src_corelib_io_qprocess.cpp 3
1530*/
1531void QProcess::setStandardOutputProcess(QProcess *destination)
1532{
1533 QProcessPrivate *dfrom = d_func();
1534 QProcessPrivate *dto = destination->d_func();
1535 dfrom->stdoutChannel.pipeTo(other: dto);
1536 dto->stdinChannel.pipeFrom(other: dfrom);
1537}
1538
1539#if defined(Q_OS_WIN) || defined(Q_CLANG_QDOC)
1540
1541/*!
1542 \since 4.7
1543
1544 Returns the additional native command line arguments for the program.
1545
1546 \note This function is available only on the Windows platform.
1547
1548 \sa setNativeArguments()
1549*/
1550QString QProcess::nativeArguments() const
1551{
1552 Q_D(const QProcess);
1553 return d->nativeArguments;
1554}
1555
1556/*!
1557 \since 4.7
1558 \overload
1559
1560 Sets additional native command line \a arguments for the program.
1561
1562 On operating systems where the system API for passing command line
1563 \a arguments to a subprocess natively uses a single string, one can
1564 conceive command lines which cannot be passed via QProcess's portable
1565 list-based API. In such cases this function must be used to set a
1566 string which is \e appended to the string composed from the usual
1567 argument list, with a delimiting space.
1568
1569 \note This function is available only on the Windows platform.
1570
1571 \sa nativeArguments()
1572*/
1573void QProcess::setNativeArguments(const QString &arguments)
1574{
1575 Q_D(QProcess);
1576 d->nativeArguments = arguments;
1577}
1578
1579/*!
1580 \since 5.7
1581
1582 Returns a previously set \c CreateProcess modifier function.
1583
1584 \note This function is available only on the Windows platform.
1585
1586 \sa setCreateProcessArgumentsModifier()
1587 \sa QProcess::CreateProcessArgumentModifier
1588*/
1589QProcess::CreateProcessArgumentModifier QProcess::createProcessArgumentsModifier() const
1590{
1591 Q_D(const QProcess);
1592 return d->modifyCreateProcessArgs;
1593}
1594
1595/*!
1596 \since 5.7
1597
1598 Sets the \a modifier for the \c CreateProcess Win32 API call.
1599 Pass \c QProcess::CreateProcessArgumentModifier() to remove a previously set one.
1600
1601 \note This function is available only on the Windows platform and requires
1602 C++11.
1603
1604 \sa QProcess::CreateProcessArgumentModifier
1605*/
1606void QProcess::setCreateProcessArgumentsModifier(CreateProcessArgumentModifier modifier)
1607{
1608 Q_D(QProcess);
1609 d->modifyCreateProcessArgs = modifier;
1610}
1611
1612#endif
1613
1614/*!
1615 If QProcess has been assigned a working directory, this function returns
1616 the working directory that the QProcess will enter before the program has
1617 started. Otherwise, (i.e., no directory has been assigned,) an empty
1618 string is returned, and QProcess will use the application's current
1619 working directory instead.
1620
1621 \sa setWorkingDirectory()
1622*/
1623QString QProcess::workingDirectory() const
1624{
1625 Q_D(const QProcess);
1626 return d->workingDirectory;
1627}
1628
1629/*!
1630 Sets the working directory to \a dir. QProcess will start the
1631 process in this directory. The default behavior is to start the
1632 process in the working directory of the calling process.
1633
1634 \note On QNX, this may cause all application threads to
1635 temporarily freeze.
1636
1637 \sa workingDirectory(), start()
1638*/
1639void QProcess::setWorkingDirectory(const QString &dir)
1640{
1641 Q_D(QProcess);
1642 d->workingDirectory = dir;
1643}
1644
1645#if QT_DEPRECATED_SINCE(5, 15)
1646/*!
1647 \deprecated
1648 Use processId() instead.
1649
1650 Returns the native process identifier for the running process, if
1651 available. If no process is currently running, \c 0 is returned.
1652
1653 \note Unlike \l processId(), pid() returns an integer on Unix and a pointer on Windows.
1654
1655 \sa Q_PID, processId()
1656*/
1657Q_PID QProcess::pid() const // ### Qt 6 remove or rename this method to processInformation()
1658{
1659 Q_D(const QProcess);
1660 return d->pid;
1661}
1662#endif
1663
1664/*!
1665 \since 5.3
1666
1667 Returns the native process identifier for the running process, if
1668 available. If no process is currently running, \c 0 is returned.
1669 */
1670qint64 QProcess::processId() const
1671{
1672 Q_D(const QProcess);
1673#ifdef Q_OS_WIN
1674 return d->pid ? d->pid->dwProcessId : 0;
1675#else
1676 return d->pid;
1677#endif
1678}
1679
1680/*! \reimp
1681
1682 This function operates on the current read channel.
1683
1684 \sa readChannel(), setReadChannel()
1685*/
1686bool QProcess::canReadLine() const
1687{
1688 return QIODevice::canReadLine();
1689}
1690
1691/*!
1692 Closes all communication with the process and kills it. After calling this
1693 function, QProcess will no longer emit readyRead(), and data can no
1694 longer be read or written.
1695*/
1696void QProcess::close()
1697{
1698 Q_D(QProcess);
1699 emit aboutToClose();
1700 while (waitForBytesWritten(msecs: -1))
1701 ;
1702 kill();
1703 waitForFinished(msecs: -1);
1704 d->setWriteChannelCount(0);
1705 QIODevice::close();
1706}
1707
1708/*! \reimp
1709
1710 Returns \c true if the process is not running, and no more data is available
1711 for reading; otherwise returns \c false.
1712*/
1713bool QProcess::atEnd() const
1714{
1715 return QIODevice::atEnd();
1716}
1717
1718/*! \reimp
1719*/
1720bool QProcess::isSequential() const
1721{
1722 return true;
1723}
1724
1725/*! \reimp
1726*/
1727qint64 QProcess::bytesAvailable() const
1728{
1729 return QIODevice::bytesAvailable();
1730}
1731
1732/*! \reimp
1733*/
1734qint64 QProcess::bytesToWrite() const
1735{
1736 qint64 size = QIODevice::bytesToWrite();
1737#ifdef Q_OS_WIN
1738 size += d_func()->pipeWriterBytesToWrite();
1739#endif
1740 return size;
1741}
1742
1743/*!
1744 Returns the type of error that occurred last.
1745
1746 \sa state()
1747*/
1748QProcess::ProcessError QProcess::error() const
1749{
1750 Q_D(const QProcess);
1751 return d->processError;
1752}
1753
1754/*!
1755 Returns the current state of the process.
1756
1757 \sa stateChanged(), error()
1758*/
1759QProcess::ProcessState QProcess::state() const
1760{
1761 Q_D(const QProcess);
1762 return d->processState;
1763}
1764
1765/*!
1766 \deprecated
1767 Sets the environment that QProcess will pass to the child process.
1768 The parameter \a environment is a list of key=value pairs.
1769
1770 For example, the following code adds the environment variable \c{TMPDIR}:
1771
1772 \snippet qprocess-environment/main.cpp 0
1773
1774 \note This function is less efficient than the setProcessEnvironment()
1775 function.
1776
1777 \sa environment(), setProcessEnvironment(), systemEnvironment()
1778*/
1779void QProcess::setEnvironment(const QStringList &environment)
1780{
1781 setProcessEnvironment(QProcessEnvironmentPrivate::fromList(list: environment));
1782}
1783
1784/*!
1785 \deprecated
1786 Returns the environment that QProcess will pass to its child
1787 process, or an empty QStringList if no environment has been set
1788 using setEnvironment(). If no environment has been set, the
1789 environment of the calling process will be used.
1790
1791 \sa processEnvironment(), setEnvironment(), systemEnvironment()
1792*/
1793QStringList QProcess::environment() const
1794{
1795 Q_D(const QProcess);
1796 return d->environment.toStringList();
1797}
1798
1799/*!
1800 \since 4.6
1801 Sets the \a environment that QProcess will pass to the child process.
1802
1803 For example, the following code adds the environment variable \c{TMPDIR}:
1804
1805 \snippet qprocess-environment/main.cpp 1
1806
1807 Note how, on Windows, environment variable names are case-insensitive.
1808
1809 \sa processEnvironment(), QProcessEnvironment::systemEnvironment(), setEnvironment()
1810*/
1811void QProcess::setProcessEnvironment(const QProcessEnvironment &environment)
1812{
1813 Q_D(QProcess);
1814 d->environment = environment;
1815}
1816
1817/*!
1818 \since 4.6
1819 Returns the environment that QProcess will pass to its child
1820 process, or an empty object if no environment has been set using
1821 setEnvironment() or setProcessEnvironment(). If no environment has
1822 been set, the environment of the calling process will be used.
1823
1824 \sa setProcessEnvironment(), setEnvironment(), QProcessEnvironment::isEmpty()
1825*/
1826QProcessEnvironment QProcess::processEnvironment() const
1827{
1828 Q_D(const QProcess);
1829 return d->environment;
1830}
1831
1832/*!
1833 Blocks until the process has started and the started() signal has
1834 been emitted, or until \a msecs milliseconds have passed.
1835
1836 Returns \c true if the process was started successfully; otherwise
1837 returns \c false (if the operation timed out or if an error
1838 occurred).
1839
1840 This function can operate without an event loop. It is
1841 useful when writing non-GUI applications and when performing
1842 I/O operations in a non-GUI thread.
1843
1844 \warning Calling this function from the main (GUI) thread
1845 might cause your user interface to freeze.
1846
1847 If msecs is -1, this function will not time out.
1848
1849 \note On some UNIX operating systems, this function may return true but
1850 the process may later report a QProcess::FailedToStart error.
1851
1852 \sa started(), waitForReadyRead(), waitForBytesWritten(), waitForFinished()
1853*/
1854bool QProcess::waitForStarted(int msecs)
1855{
1856 Q_D(QProcess);
1857 if (d->processState == QProcess::Starting)
1858 return d->waitForStarted(msecs);
1859
1860 return d->processState == QProcess::Running;
1861}
1862
1863/*! \reimp
1864*/
1865bool QProcess::waitForReadyRead(int msecs)
1866{
1867 Q_D(QProcess);
1868
1869 if (d->processState == QProcess::NotRunning)
1870 return false;
1871 if (d->currentReadChannel == QProcess::StandardOutput && d->stdoutChannel.closed)
1872 return false;
1873 if (d->currentReadChannel == QProcess::StandardError && d->stderrChannel.closed)
1874 return false;
1875 return d->waitForReadyRead(msecs);
1876}
1877
1878/*! \reimp
1879*/
1880bool QProcess::waitForBytesWritten(int msecs)
1881{
1882 Q_D(QProcess);
1883 if (d->processState == QProcess::NotRunning)
1884 return false;
1885 if (d->processState == QProcess::Starting) {
1886 QElapsedTimer stopWatch;
1887 stopWatch.start();
1888 bool started = waitForStarted(msecs);
1889 if (!started)
1890 return false;
1891 msecs = qt_subtract_from_timeout(timeout: msecs, elapsed: stopWatch.elapsed());
1892 }
1893
1894 return d->waitForBytesWritten(msecs);
1895}
1896
1897/*!
1898 Blocks until the process has finished and the finished() signal
1899 has been emitted, or until \a msecs milliseconds have passed.
1900
1901 Returns \c true if the process finished; otherwise returns \c false (if
1902 the operation timed out, if an error occurred, or if this QProcess
1903 is already finished).
1904
1905 This function can operate without an event loop. It is
1906 useful when writing non-GUI applications and when performing
1907 I/O operations in a non-GUI thread.
1908
1909 \warning Calling this function from the main (GUI) thread
1910 might cause your user interface to freeze.
1911
1912 If msecs is -1, this function will not time out.
1913
1914 \sa finished(), waitForStarted(), waitForReadyRead(), waitForBytesWritten()
1915*/
1916bool QProcess::waitForFinished(int msecs)
1917{
1918 Q_D(QProcess);
1919 if (d->processState == QProcess::NotRunning)
1920 return false;
1921 if (d->processState == QProcess::Starting) {
1922 QElapsedTimer stopWatch;
1923 stopWatch.start();
1924 bool started = waitForStarted(msecs);
1925 if (!started)
1926 return false;
1927 msecs = qt_subtract_from_timeout(timeout: msecs, elapsed: stopWatch.elapsed());
1928 }
1929
1930 return d->waitForFinished(msecs);
1931}
1932
1933/*!
1934 Sets the current state of the QProcess to the \a state specified.
1935
1936 \sa state()
1937*/
1938void QProcess::setProcessState(ProcessState state)
1939{
1940 Q_D(QProcess);
1941 if (d->processState == state)
1942 return;
1943 d->processState = state;
1944 emit stateChanged(state, QPrivateSignal());
1945}
1946
1947/*!
1948 This function is called in the child process context just before the
1949 program is executed on Unix or \macos (i.e., after \c fork(), but before
1950 \c execve()). Reimplement this function to do last minute initialization
1951 of the child process. Example:
1952
1953 \snippet code/src_corelib_io_qprocess.cpp 4
1954
1955 You cannot exit the process (by calling exit(), for instance) from
1956 this function. If you need to stop the program before it starts
1957 execution, your workaround is to emit finished() and then call
1958 exit().
1959
1960 \warning This function is called by QProcess on Unix and \macos
1961 only. On Windows and QNX, it is not called.
1962*/
1963void QProcess::setupChildProcess()
1964{
1965}
1966
1967/*! \reimp
1968*/
1969qint64 QProcess::readData(char *data, qint64 maxlen)
1970{
1971 Q_D(QProcess);
1972 Q_UNUSED(data);
1973 if (!maxlen)
1974 return 0;
1975 if (d->processState == QProcess::NotRunning)
1976 return -1; // EOF
1977 return 0;
1978}
1979
1980/*! \reimp
1981*/
1982qint64 QProcess::writeData(const char *data, qint64 len)
1983{
1984 Q_D(QProcess);
1985
1986 if (d->stdinChannel.closed) {
1987#if defined QPROCESS_DEBUG
1988 qDebug("QProcess::writeData(%p \"%s\", %lld) == 0 (write channel closing)",
1989 data, qt_prettyDebug(data, len, 16).constData(), len);
1990#endif
1991 return 0;
1992 }
1993
1994#if defined(Q_OS_WIN)
1995 if (!d->stdinWriteTrigger) {
1996 d->stdinWriteTrigger = new QTimer;
1997 d->stdinWriteTrigger->setSingleShot(true);
1998 QObjectPrivate::connect(d->stdinWriteTrigger, &QTimer::timeout,
1999 d, &QProcessPrivate::_q_canWrite);
2000 }
2001#endif
2002
2003 d->writeBuffer.append(data, size: len);
2004#ifdef Q_OS_WIN
2005 if (!d->stdinWriteTrigger->isActive())
2006 d->stdinWriteTrigger->start();
2007#else
2008 if (d->stdinChannel.notifier)
2009 d->stdinChannel.notifier->setEnabled(true);
2010#endif
2011#if defined QPROCESS_DEBUG
2012 qDebug("QProcess::writeData(%p \"%s\", %lld) == %lld (written to buffer)",
2013 data, qt_prettyDebug(data, len, 16).constData(), len, len);
2014#endif
2015 return len;
2016}
2017
2018/*!
2019 Regardless of the current read channel, this function returns all
2020 data available from the standard output of the process as a
2021 QByteArray.
2022
2023 \sa readyReadStandardOutput(), readAllStandardError(), readChannel(), setReadChannel()
2024*/
2025QByteArray QProcess::readAllStandardOutput()
2026{
2027 ProcessChannel tmp = readChannel();
2028 setReadChannel(StandardOutput);
2029 QByteArray data = readAll();
2030 setReadChannel(tmp);
2031 return data;
2032}
2033
2034/*!
2035 Regardless of the current read channel, this function returns all
2036 data available from the standard error of the process as a
2037 QByteArray.
2038
2039 \sa readyReadStandardError(), readAllStandardOutput(), readChannel(), setReadChannel()
2040*/
2041QByteArray QProcess::readAllStandardError()
2042{
2043 ProcessChannel tmp = readChannel();
2044 setReadChannel(StandardError);
2045 QByteArray data = readAll();
2046 setReadChannel(tmp);
2047 return data;
2048}
2049
2050/*!
2051 Starts the given \a program in a new process, passing the command line
2052 arguments in \a arguments.
2053
2054 The QProcess object will immediately enter the Starting state. If the
2055 process starts successfully, QProcess will emit started(); otherwise,
2056 errorOccurred() will be emitted.
2057
2058 \note Processes are started asynchronously, which means the started()
2059 and errorOccurred() signals may be delayed. Call waitForStarted() to make
2060 sure the process has started (or has failed to start) and those signals
2061 have been emitted.
2062
2063 \note No further splitting of the arguments is performed.
2064
2065 \b{Windows:} The arguments are quoted and joined into a command line
2066 that is compatible with the \c CommandLineToArgvW() Windows function.
2067 For programs that have different command line quoting requirements,
2068 you need to use setNativeArguments(). One notable program that does
2069 not follow the \c CommandLineToArgvW() rules is cmd.exe and, by
2070 consequence, all batch scripts.
2071
2072 The OpenMode is set to \a mode.
2073
2074 If the QProcess object is already running a process, a warning may be
2075 printed at the console, and the existing process will continue running
2076 unaffected.
2077
2078 \sa processId(), started(), waitForStarted(), setNativeArguments()
2079*/
2080void QProcess::start(const QString &program, const QStringList &arguments, OpenMode mode)
2081{
2082 Q_D(QProcess);
2083 if (d->processState != NotRunning) {
2084 qWarning(msg: "QProcess::start: Process is already running");
2085 return;
2086 }
2087 if (program.isEmpty()) {
2088 d->setErrorAndEmit(error: QProcess::FailedToStart, description: tr(s: "No program defined"));
2089 return;
2090 }
2091
2092 d->program = program;
2093 d->arguments = arguments;
2094
2095 d->start(mode);
2096}
2097
2098/*!
2099 \since 5.1
2100 \overload
2101
2102 Starts the program set by setProgram() with arguments set by setArguments().
2103 The OpenMode is set to \a mode.
2104
2105 \sa open(), setProgram(), setArguments()
2106 */
2107void QProcess::start(OpenMode mode)
2108{
2109 Q_D(QProcess);
2110 if (d->processState != NotRunning) {
2111 qWarning(msg: "QProcess::start: Process is already running");
2112 return;
2113 }
2114 if (d->program.isEmpty()) {
2115 d->setErrorAndEmit(error: QProcess::FailedToStart, description: tr(s: "No program defined"));
2116 return;
2117 }
2118
2119 d->start(mode);
2120}
2121
2122/*!
2123 \since 5.10
2124
2125 Starts the program set by setProgram() with arguments set by setArguments()
2126 in a new process, and detaches from it. Returns \c true on success;
2127 otherwise returns \c false. If the calling process exits, the
2128 detached process will continue to run unaffected.
2129
2130 \b{Unix:} The started process will run in its own session and act
2131 like a daemon.
2132
2133 The process will be started in the directory set by setWorkingDirectory().
2134 If workingDirectory() is empty, the working directory is inherited
2135 from the calling process.
2136
2137 \note On QNX, this may cause all application threads to
2138 temporarily freeze.
2139
2140 If the function is successful then *\a pid is set to the process identifier
2141 of the started process. Note that the child process may exit and the PID
2142 may become invalid without notice. Furthermore, after the child process
2143 exits, the same PID may be recycled and used by a completely different
2144 process. User code should be careful when using this variable, especially
2145 if one intends to forcibly terminate the process by operating system means.
2146
2147 Only the following property setters are supported by startDetached():
2148 \list
2149 \li setArguments()
2150 \li setCreateProcessArgumentsModifier()
2151 \li setNativeArguments()
2152 \li setProcessEnvironment()
2153 \li setProgram()
2154 \li setStandardErrorFile()
2155 \li setStandardInputFile()
2156 \li setStandardOutputFile()
2157 \li setWorkingDirectory()
2158 \endlist
2159 All other properties of the QProcess object are ignored.
2160
2161 \note The called process inherits the console window of the calling
2162 process. To suppress console output, redirect standard/error output to
2163 QProcess::nullDevice().
2164
2165 \sa start()
2166 \sa startDetached(const QString &program, const QStringList &arguments,
2167 const QString &workingDirectory, qint64 *pid)
2168 \sa startDetached(const QString &command)
2169*/
2170bool QProcess::startDetached(qint64 *pid)
2171{
2172 Q_D(QProcess);
2173 if (d->processState != NotRunning) {
2174 qWarning(msg: "QProcess::startDetached: Process is already running");
2175 return false;
2176 }
2177 if (d->program.isEmpty()) {
2178 d->setErrorAndEmit(error: QProcess::FailedToStart, description: tr(s: "No program defined"));
2179 return false;
2180 }
2181 return d->startDetached(pPid: pid);
2182}
2183
2184/*!
2185 Starts the program set by setProgram() with arguments set by setArguments().
2186 The OpenMode is set to \a mode.
2187
2188 This method is an alias for start(), and exists only to fully implement
2189 the interface defined by QIODevice.
2190
2191 Returns \c true if the program has been started.
2192
2193 \sa start(), setProgram(), setArguments()
2194*/
2195bool QProcess::open(OpenMode mode)
2196{
2197 Q_D(QProcess);
2198 if (d->processState != NotRunning) {
2199 qWarning(msg: "QProcess::start: Process is already running");
2200 return false;
2201 }
2202 if (d->program.isEmpty()) {
2203 qWarning(msg: "QProcess::start: program not set");
2204 return false;
2205 }
2206
2207 d->start(mode);
2208 return true;
2209}
2210
2211void QProcessPrivate::start(QIODevice::OpenMode mode)
2212{
2213 Q_Q(QProcess);
2214#if defined QPROCESS_DEBUG
2215 qDebug() << "QProcess::start(" << program << ',' << arguments << ',' << mode << ')';
2216#endif
2217
2218 if (stdinChannel.type != QProcessPrivate::Channel::Normal)
2219 mode &= ~QIODevice::WriteOnly; // not open for writing
2220 if (stdoutChannel.type != QProcessPrivate::Channel::Normal &&
2221 (stderrChannel.type != QProcessPrivate::Channel::Normal ||
2222 processChannelMode == QProcess::MergedChannels))
2223 mode &= ~QIODevice::ReadOnly; // not open for reading
2224 if (mode == 0)
2225 mode = QIODevice::Unbuffered;
2226 if ((mode & QIODevice::ReadOnly) == 0) {
2227 if (stdoutChannel.type == QProcessPrivate::Channel::Normal)
2228 q->setStandardOutputFile(fileName: q->nullDevice());
2229 if (stderrChannel.type == QProcessPrivate::Channel::Normal
2230 && processChannelMode != QProcess::MergedChannels)
2231 q->setStandardErrorFile(fileName: q->nullDevice());
2232 }
2233
2234 q->QIODevice::open(mode);
2235
2236 if (q->isReadable() && processChannelMode != QProcess::MergedChannels)
2237 setReadChannelCount(2);
2238
2239 stdinChannel.closed = false;
2240 stdoutChannel.closed = false;
2241 stderrChannel.closed = false;
2242
2243 exitCode = 0;
2244 exitStatus = QProcess::NormalExit;
2245 processError = QProcess::UnknownError;
2246 errorString.clear();
2247 startProcess();
2248}
2249
2250/*!
2251 \since 5.15
2252
2253 Splits the string \a command into a list of tokens, and returns
2254 the list.
2255
2256 Tokens with spaces can be surrounded by double quotes; three
2257 consecutive double quotes represent the quote character itself.
2258*/
2259QStringList QProcess::splitCommand(QStringView command)
2260{
2261 QStringList args;
2262 QString tmp;
2263 int quoteCount = 0;
2264 bool inQuote = false;
2265
2266 // handle quoting. tokens can be surrounded by double quotes
2267 // "hello world". three consecutive double quotes represent
2268 // the quote character itself.
2269 for (int i = 0; i < command.size(); ++i) {
2270 if (command.at(n: i) == QLatin1Char('"')) {
2271 ++quoteCount;
2272 if (quoteCount == 3) {
2273 // third consecutive quote
2274 quoteCount = 0;
2275 tmp += command.at(n: i);
2276 }
2277 continue;
2278 }
2279 if (quoteCount) {
2280 if (quoteCount == 1)
2281 inQuote = !inQuote;
2282 quoteCount = 0;
2283 }
2284 if (!inQuote && command.at(n: i).isSpace()) {
2285 if (!tmp.isEmpty()) {
2286 args += tmp;
2287 tmp.clear();
2288 }
2289 } else {
2290 tmp += command.at(n: i);
2291 }
2292 }
2293 if (!tmp.isEmpty())
2294 args += tmp;
2295
2296 return args;
2297}
2298
2299/*!
2300 \obsolete
2301 \overload
2302
2303 Starts the command \a command in a new process.
2304 The OpenMode is set to \a mode.
2305
2306 \a command is a single string of text containing both the program name
2307 and its arguments. The arguments are separated by one or more spaces.
2308 For example:
2309
2310 \snippet code/src_corelib_io_qprocess.cpp 5
2311
2312 Arguments containing spaces must be quoted to be correctly supplied to
2313 the new process. For example:
2314
2315 \snippet code/src_corelib_io_qprocess.cpp 6
2316
2317 Literal quotes in the \a command string are represented by triple quotes.
2318 For example:
2319
2320 \snippet code/src_corelib_io_qprocess.cpp 7
2321
2322 After the \a command string has been split and unquoted, this function
2323 behaves like the overload which takes the arguments as a string list.
2324
2325 You can disable this overload by defining \c
2326 QT_NO_PROCESS_COMBINED_ARGUMENT_START when you compile your applications.
2327 This can be useful if you want to ensure that you are not splitting arguments
2328 unintentionally, for example. In virtually all cases, using the other overload
2329 is the preferred method.
2330
2331 On operating systems where the system API for passing command line
2332 arguments to a subprocess natively uses a single string (Windows), one can
2333 conceive command lines which cannot be passed via QProcess's portable
2334 list-based API. In these rare cases you need to use setProgram() and
2335 setNativeArguments() instead of this function.
2336
2337 \sa splitCommand()
2338
2339*/
2340#if !defined(QT_NO_PROCESS_COMBINED_ARGUMENT_START)
2341void QProcess::start(const QString &command, OpenMode mode)
2342{
2343 QStringList args = splitCommand(command);
2344 if (args.isEmpty()) {
2345 Q_D(QProcess);
2346 d->setErrorAndEmit(error: QProcess::FailedToStart, description: tr(s: "No program defined"));
2347 return;
2348 }
2349
2350 const QString prog = args.takeFirst();
2351
2352 start(program: prog, arguments: args, mode);
2353}
2354#endif
2355
2356/*!
2357 \since 5.0
2358
2359 Returns the program the process was last started with.
2360
2361 \sa start()
2362*/
2363QString QProcess::program() const
2364{
2365 Q_D(const QProcess);
2366 return d->program;
2367}
2368
2369/*!
2370 \since 5.1
2371
2372 Set the \a program to use when starting the process.
2373 This function must be called before start().
2374
2375 \sa start(), setArguments(), program()
2376*/
2377void QProcess::setProgram(const QString &program)
2378{
2379 Q_D(QProcess);
2380 if (d->processState != NotRunning) {
2381 qWarning(msg: "QProcess::setProgram: Process is already running");
2382 return;
2383 }
2384 d->program = program;
2385}
2386
2387/*!
2388 \since 5.0
2389
2390 Returns the command line arguments the process was last started with.
2391
2392 \sa start()
2393*/
2394QStringList QProcess::arguments() const
2395{
2396 Q_D(const QProcess);
2397 return d->arguments;
2398}
2399
2400/*!
2401 \since 5.1
2402
2403 Set the \a arguments to pass to the called program when starting the process.
2404 This function must be called before start().
2405
2406 \sa start(), setProgram(), arguments()
2407*/
2408void QProcess::setArguments(const QStringList &arguments)
2409{
2410 Q_D(QProcess);
2411 if (d->processState != NotRunning) {
2412 qWarning(msg: "QProcess::setProgram: Process is already running");
2413 return;
2414 }
2415 d->arguments = arguments;
2416}
2417
2418/*!
2419 Attempts to terminate the process.
2420
2421 The process may not exit as a result of calling this function (it is given
2422 the chance to prompt the user for any unsaved files, etc).
2423
2424 On Windows, terminate() posts a WM_CLOSE message to all top-level windows
2425 of the process and then to the main thread of the process itself. On Unix
2426 and \macos the \c SIGTERM signal is sent.
2427
2428 Console applications on Windows that do not run an event loop, or whose
2429 event loop does not handle the WM_CLOSE message, can only be terminated by
2430 calling kill().
2431
2432 \sa kill()
2433*/
2434void QProcess::terminate()
2435{
2436 Q_D(QProcess);
2437 d->terminateProcess();
2438}
2439
2440/*!
2441 Kills the current process, causing it to exit immediately.
2442
2443 On Windows, kill() uses TerminateProcess, and on Unix and \macos, the
2444 SIGKILL signal is sent to the process.
2445
2446 \sa terminate()
2447*/
2448void QProcess::kill()
2449{
2450 Q_D(QProcess);
2451 d->killProcess();
2452}
2453
2454/*!
2455 Returns the exit code of the last process that finished.
2456
2457 This value is not valid unless exitStatus() returns NormalExit.
2458*/
2459int QProcess::exitCode() const
2460{
2461 Q_D(const QProcess);
2462 return d->exitCode;
2463}
2464
2465/*!
2466 \since 4.1
2467
2468 Returns the exit status of the last process that finished.
2469
2470 On Windows, if the process was terminated with TerminateProcess() from
2471 another application, this function will still return NormalExit
2472 unless the exit code is less than 0.
2473*/
2474QProcess::ExitStatus QProcess::exitStatus() const
2475{
2476 Q_D(const QProcess);
2477 return d->exitStatus;
2478}
2479
2480/*!
2481 Starts the program \a program with the arguments \a arguments in a
2482 new process, waits for it to finish, and then returns the exit
2483 code of the process. Any data the new process writes to the
2484 console is forwarded to the calling process.
2485
2486 The environment and working directory are inherited from the calling
2487 process.
2488
2489 Argument handling is identical to the respective start() overload.
2490
2491 If the process cannot be started, -2 is returned. If the process
2492 crashes, -1 is returned. Otherwise, the process' exit code is
2493 returned.
2494
2495 \sa start()
2496*/
2497int QProcess::execute(const QString &program, const QStringList &arguments)
2498{
2499 QProcess process;
2500 process.setProcessChannelMode(ForwardedChannels);
2501 process.start(program, arguments);
2502 if (!process.waitForFinished(msecs: -1) || process.error() == FailedToStart)
2503 return -2;
2504 return process.exitStatus() == QProcess::NormalExit ? process.exitCode() : -1;
2505}
2506
2507/*!
2508 \obsolete
2509 \overload
2510
2511 Starts the program \a command in a new process, waits for it to finish,
2512 and then returns the exit code.
2513
2514 Argument handling is identical to the respective start() overload.
2515
2516 After the \a command string has been split and unquoted, this function
2517 behaves like the overload which takes the arguments as a string list.
2518
2519 \sa start(), splitCommand()
2520*/
2521int QProcess::execute(const QString &command)
2522{
2523 QStringList args = splitCommand(command);
2524 if (args.isEmpty())
2525 return -2;
2526 QString program = args.takeFirst();
2527 return execute(program, arguments: args);
2528}
2529
2530/*!
2531 \overload startDetached()
2532
2533 Starts the program \a program with the arguments \a arguments in a
2534 new process, and detaches from it. Returns \c true on success;
2535 otherwise returns \c false. If the calling process exits, the
2536 detached process will continue to run unaffected.
2537
2538 Argument handling is identical to the respective start() overload.
2539
2540 The process will be started in the directory \a workingDirectory.
2541 If \a workingDirectory is empty, the working directory is inherited
2542 from the calling process.
2543
2544 If the function is successful then *\a pid is set to the process
2545 identifier of the started process.
2546
2547 \sa start()
2548*/
2549bool QProcess::startDetached(const QString &program,
2550 const QStringList &arguments,
2551 const QString &workingDirectory,
2552 qint64 *pid)
2553{
2554 QProcess process;
2555 process.setProgram(program);
2556 process.setArguments(arguments);
2557 process.setWorkingDirectory(workingDirectory);
2558 return process.startDetached(pid);
2559}
2560
2561/*!
2562 \internal
2563*/
2564bool QProcess::startDetached(const QString &program,
2565 const QStringList &arguments)
2566{
2567 QProcess process;
2568 process.setProgram(program);
2569 process.setArguments(arguments);
2570 return process.startDetached();
2571}
2572
2573/*!
2574 \obsolete
2575 \overload startDetached()
2576
2577 Starts the command \a command in a new process, and detaches from it.
2578 Returns \c true on success; otherwise returns \c false.
2579
2580 Argument handling is identical to the respective start() overload.
2581
2582 After the \a command string has been split and unquoted, this function
2583 behaves like the overload which takes the arguments as a string list.
2584
2585 \sa start(const QString &command, QIODevice::OpenMode mode), splitCommand()
2586*/
2587bool QProcess::startDetached(const QString &command)
2588{
2589 QStringList args = splitCommand(command);
2590 if (args.isEmpty())
2591 return false;
2592
2593 QProcess process;
2594 process.setProgram(args.takeFirst());
2595 process.setArguments(args);
2596 return process.startDetached();
2597}
2598
2599QT_BEGIN_INCLUDE_NAMESPACE
2600#if defined(Q_OS_MACX)
2601# include <crt_externs.h>
2602# define environ (*_NSGetEnviron())
2603#elif defined(QT_PLATFORM_UIKIT)
2604 static char *qt_empty_environ[] = { 0 };
2605#define environ qt_empty_environ
2606#elif !defined(Q_OS_WIN)
2607 extern char **environ;
2608#endif
2609QT_END_INCLUDE_NAMESPACE
2610
2611/*!
2612 \since 4.1
2613
2614 Returns the environment of the calling process as a list of
2615 key=value pairs. Example:
2616
2617 \snippet code/src_corelib_io_qprocess.cpp 8
2618
2619 This function does not cache the system environment. Therefore, it's
2620 possible to obtain an updated version of the environment if low-level C
2621 library functions like \tt setenv or \tt putenv have been called.
2622
2623 However, note that repeated calls to this function will recreate the
2624 list of environment variables, which is a non-trivial operation.
2625
2626 \note For new code, it is recommended to use QProcessEnvironment::systemEnvironment()
2627
2628 \sa QProcessEnvironment::systemEnvironment(), setProcessEnvironment()
2629*/
2630QStringList QProcess::systemEnvironment()
2631{
2632 QStringList tmp;
2633 char *entry = nullptr;
2634 int count = 0;
2635 while ((entry = environ[count++]))
2636 tmp << QString::fromLocal8Bit(str: entry);
2637 return tmp;
2638}
2639
2640/*!
2641 \fn QProcessEnvironment QProcessEnvironment::systemEnvironment()
2642
2643 \since 4.6
2644
2645 \brief The systemEnvironment function returns the environment of
2646 the calling process.
2647
2648 It is returned as a QProcessEnvironment. This function does not
2649 cache the system environment. Therefore, it's possible to obtain
2650 an updated version of the environment if low-level C library
2651 functions like \tt setenv or \tt putenv have been called.
2652
2653 However, note that repeated calls to this function will recreate the
2654 QProcessEnvironment object, which is a non-trivial operation.
2655
2656 \sa QProcess::systemEnvironment()
2657*/
2658
2659/*!
2660 \since 5.2
2661
2662 \brief The null device of the operating system.
2663
2664 The returned file path uses native directory separators.
2665
2666 \sa QProcess::setStandardInputFile(), QProcess::setStandardOutputFile(),
2667 QProcess::setStandardErrorFile()
2668*/
2669QString QProcess::nullDevice()
2670{
2671#ifdef Q_OS_WIN
2672 return QStringLiteral("\\\\.\\NUL");
2673#elif defined(_PATH_DEVNULL)
2674 return QStringLiteral(_PATH_DEVNULL);
2675#else
2676 return QStringLiteral("/dev/null");
2677#endif
2678}
2679
2680/*!
2681 \typedef Q_PID
2682 \relates QProcess
2683
2684 Typedef for the identifiers used to represent processes on the underlying
2685 platform. On Unix, this corresponds to \l qint64; on Windows, it
2686 corresponds to \c{_PROCESS_INFORMATION*}.
2687
2688 \sa QProcess::pid()
2689*/
2690
2691#endif // QT_CONFIG(process)
2692
2693QT_END_NAMESPACE
2694
2695#include "moc_qprocess.cpp"
2696

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