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

Provided by KDAB

Privacy Policy
Learn to use CMake with our Intro Training
Find out more

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