1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
|
<?xml version="1.0" encoding="iso-8859-1"?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "DTD/xhtml1-strict.dtd">
<html><head><title>QProcess Class Reference</title><style>h3.fn,span.fn { margin-left: 1cm; text-indent: -1cm }
a:link { color: #004faf; text-decoration: none }
a:visited { color: #672967; text-decoration: none }
td.postheader { font-family: sans-serif }
tr.address { font-family: sans-serif }
body { background: #ffffff; color: black; }
</style></head><body><table border="0" cellpadding="0" cellspacing="0" width="100%"><tr /><td align="left" valign="top" width="32"><img align="left" border="0" height="32" src="images/rb-logo.png" width="32" /></td><td width="1">  </td><td class="postheader" valign="center"><a href="index.html"><font color="#004faf">Home</font></a> · <a href="classes.html"><font color="#004faf">All Classes</font></a> · <a href="modules.html"><font color="#004faf">Modules</font></a></td></table><h1 align="center">QProcess Class Reference<br /><sup><sup>[<a href="qtcore.html">QtCore</a> module]</sup></sup></h1><p>The QProcess class is used to start external programs and to
communicate with them. <a href="#details">More...</a></p>
<p>Inherits <a href="qiodevice.html">QIODevice</a>.</p><h3>Types</h3><ul><li><div class="fn" />enum <b><a href="qprocess.html#ExitStatus-enum">ExitStatus</a></b> { NormalExit, CrashExit }</li><li><div class="fn" />enum <b><a href="qprocess.html#ProcessChannel-enum">ProcessChannel</a></b> { StandardOutput, StandardError }</li><li><div class="fn" />enum <b><a href="qprocess.html#ProcessChannelMode-enum">ProcessChannelMode</a></b> { SeparateChannels, MergedChannels, ForwardedChannels }</li><li><div class="fn" />enum <b><a href="qprocess.html#ProcessError-enum">ProcessError</a></b> { FailedToStart, Crashed, Timedout, ReadError, WriteError, UnknownError }</li><li><div class="fn" />enum <b><a href="qprocess.html#ProcessState-enum">ProcessState</a></b> { NotRunning, Starting, Running }</li></ul><h3>Methods</h3><ul><li><div class="fn" /><b><a href="qprocess.html#QProcess">__init__</a></b> (<i>self</i>, QObject <i>parent</i> = None)</li><li><div class="fn" />bool <b><a href="qprocess.html#atEnd">atEnd</a></b> (<i>self</i>)</li><li><div class="fn" />int <b><a href="qprocess.html#bytesAvailable">bytesAvailable</a></b> (<i>self</i>)</li><li><div class="fn" />int <b><a href="qprocess.html#bytesToWrite">bytesToWrite</a></b> (<i>self</i>)</li><li><div class="fn" />bool <b><a href="qprocess.html#canReadLine">canReadLine</a></b> (<i>self</i>)</li><li><div class="fn" /><b><a href="qprocess.html#close">close</a></b> (<i>self</i>)</li><li><div class="fn" /><b><a href="qprocess.html#closeReadChannel">closeReadChannel</a></b> (<i>self</i>, ProcessChannel <i>channel</i>)</li><li><div class="fn" /><b><a href="qprocess.html#closeWriteChannel">closeWriteChannel</a></b> (<i>self</i>)</li><li><div class="fn" />QStringList <b><a href="qprocess.html#environment">environment</a></b> (<i>self</i>)</li><li><div class="fn" />ProcessError <b><a href="qprocess.html#error">error</a></b> (<i>self</i>)</li><li><div class="fn" />int <b><a href="qprocess.html#exitCode">exitCode</a></b> (<i>self</i>)</li><li><div class="fn" />ExitStatus <b><a href="qprocess.html#exitStatus">exitStatus</a></b> (<i>self</i>)</li><li><div class="fn" />bool <b><a href="qprocess.html#isSequential">isSequential</a></b> (<i>self</i>)</li><li><div class="fn" /><b><a href="qprocess.html#kill">kill</a></b> (<i>self</i>)</li><li><div class="fn" />int <b><a href="qprocess.html#pid">pid</a></b> (<i>self</i>)</li><li><div class="fn" />ProcessChannelMode <b><a href="qprocess.html#processChannelMode">processChannelMode</a></b> (<i>self</i>)</li><li><div class="fn" />QProcessEnvironment <b><a href="qprocess.html#processEnvironment">processEnvironment</a></b> (<i>self</i>)</li><li><div class="fn" />QByteArray <b><a href="qprocess.html#readAllStandardError">readAllStandardError</a></b> (<i>self</i>)</li><li><div class="fn" />QByteArray <b><a href="qprocess.html#readAllStandardOutput">readAllStandardOutput</a></b> (<i>self</i>)</li><li><div class="fn" />ProcessChannel <b><a href="qprocess.html#readChannel">readChannel</a></b> (<i>self</i>)</li><li><div class="fn" />ProcessChannelMode <b><a href="qprocess.html#readChannelMode">readChannelMode</a></b> (<i>self</i>)</li><li><div class="fn" />object <b><a href="qprocess.html#readData">readData</a></b> (<i>self</i>, int <i>maxlen</i>)</li><li><div class="fn" /><b><a href="qprocess.html#setEnvironment">setEnvironment</a></b> (<i>self</i>, QStringList <i>environment</i>)</li><li><div class="fn" /><b><a href="qprocess.html#setProcessChannelMode">setProcessChannelMode</a></b> (<i>self</i>, ProcessChannelMode <i>mode</i>)</li><li><div class="fn" /><b><a href="qprocess.html#setProcessEnvironment">setProcessEnvironment</a></b> (<i>self</i>, QProcessEnvironment <i>environment</i>)</li><li><div class="fn" /><b><a href="qprocess.html#setProcessState">setProcessState</a></b> (<i>self</i>, ProcessState <i>state</i>)</li><li><div class="fn" /><b><a href="qprocess.html#setReadChannel">setReadChannel</a></b> (<i>self</i>, ProcessChannel <i>channel</i>)</li><li><div class="fn" /><b><a href="qprocess.html#setReadChannelMode">setReadChannelMode</a></b> (<i>self</i>, ProcessChannelMode <i>mode</i>)</li><li><div class="fn" /><b><a href="qprocess.html#setStandardErrorFile">setStandardErrorFile</a></b> (<i>self</i>, QString <i>fileName</i>, QIODevice.OpenMode <i>mode</i> = QIODevice.Truncate)</li><li><div class="fn" /><b><a href="qprocess.html#setStandardInputFile">setStandardInputFile</a></b> (<i>self</i>, QString <i>fileName</i>)</li><li><div class="fn" /><b><a href="qprocess.html#setStandardOutputFile">setStandardOutputFile</a></b> (<i>self</i>, QString <i>fileName</i>, QIODevice.OpenMode <i>mode</i> = QIODevice.Truncate)</li><li><div class="fn" /><b><a href="qprocess.html#setStandardOutputProcess">setStandardOutputProcess</a></b> (<i>self</i>, QProcess <i>destination</i>)</li><li><div class="fn" /><b><a href="qprocess.html#setupChildProcess">setupChildProcess</a></b> (<i>self</i>)</li><li><div class="fn" /><b><a href="qprocess.html#setWorkingDirectory">setWorkingDirectory</a></b> (<i>self</i>, QString <i>dir</i>)</li><li><div class="fn" /><b><a href="qprocess.html#start">start</a></b> (<i>self</i>, QString <i>program</i>, QStringList <i>arguments</i>, QIODevice.OpenMode <i>mode</i> = QIODevice.ReadWrite)</li><li><div class="fn" /><b><a href="qprocess.html#start-2">start</a></b> (<i>self</i>, QString <i>program</i>, QIODevice.OpenMode <i>mode</i> = QIODevice.ReadWrite)</li><li><div class="fn" />ProcessState <b><a href="qprocess.html#state">state</a></b> (<i>self</i>)</li><li><div class="fn" /><b><a href="qprocess.html#terminate">terminate</a></b> (<i>self</i>)</li><li><div class="fn" />bool <b><a href="qprocess.html#waitForBytesWritten">waitForBytesWritten</a></b> (<i>self</i>, int <i>msecs</i> = 30000)</li><li><div class="fn" />bool <b><a href="qprocess.html#waitForFinished">waitForFinished</a></b> (<i>self</i>, int <i>msecs</i> = 30000)</li><li><div class="fn" />bool <b><a href="qprocess.html#waitForReadyRead">waitForReadyRead</a></b> (<i>self</i>, int <i>msecs</i> = 30000)</li><li><div class="fn" />bool <b><a href="qprocess.html#waitForStarted">waitForStarted</a></b> (<i>self</i>, int <i>msecs</i> = 30000)</li><li><div class="fn" />QString <b><a href="qprocess.html#workingDirectory">workingDirectory</a></b> (<i>self</i>)</li><li><div class="fn" />int <b><a href="qprocess.html#writeData">writeData</a></b> (<i>self</i>, bytes <i>data</i>)</li></ul><h3>Static Methods</h3><ul><li><div class="fn" />int <b><a href="qprocess.html#execute">execute</a></b> (QString <i>program</i>, QStringList <i>arguments</i>)</li><li><div class="fn" />int <b><a href="qprocess.html#execute-2">execute</a></b> (QString <i>program</i>)</li><li><div class="fn" />(bool, int <i>pid</i>) <b><a href="qprocess.html#startDetached">startDetached</a></b> (QString <i>program</i>, QStringList <i>arguments</i>, QString <i>workingDirectory</i>)</li><li><div class="fn" />bool <b><a href="qprocess.html#startDetached-2">startDetached</a></b> (QString <i>program</i>, QStringList <i>arguments</i>)</li><li><div class="fn" />bool <b><a href="qprocess.html#startDetached-3">startDetached</a></b> (QString <i>program</i>)</li><li><div class="fn" />QStringList <b><a href="qprocess.html#systemEnvironment">systemEnvironment</a></b> ()</li></ul><h3>Qt Signals</h3><ul><li><div class="fn" />void <b><a href="qprocess.html#error-2">error</a></b> ( ::QProcess::ProcessError)</li><li><div class="fn" />void <b><a href="qprocess.html#finished">finished</a></b> (int, ::QProcess::ExitStatus)</li><li><div class="fn" />void <b><a href="qprocess.html#finished-2">finished</a></b> (int)</li><li><div class="fn" />void <b><a href="qprocess.html#readyReadStandardError">readyReadStandardError</a></b> ()</li><li><div class="fn" />void <b><a href="qprocess.html#readyReadStandardOutput">readyReadStandardOutput</a></b> ()</li><li><div class="fn" />void <b><a href="qprocess.html#started">started</a></b> ()</li><li><div class="fn" />void <b><a href="qprocess.html#stateChanged">stateChanged</a></b> ( ::QProcess::ProcessState)</li></ul><a name="details" /><hr /><h2>Detailed Description</h2><p>The QProcess class is used to start external programs and to
communicate with them.</p>
<a id="running-a-process" name="running-a-process" />
<h3>Running a Process</h3>
<p>To start a process, pass the name and command line arguments of
the program you want to run as arguments to <a href="qprocess.html#start">start</a>(). Arguments are supplied as
individual strings in a <a href="qstringlist.html">QStringList</a>.</p>
<p>For example, the following code snippet runs the analog clock
example in the Motif style on X11 platforms by passing strings
containing "-style" and "motif" as two items in the list of
arguments:</p>
<pre class="cpp">
<span class="type"><a href="qobject.html">QObject</a></span> <span class="operator">*</span>parent;
...
<span class="type"><a href="qstring.html">QString</a></span> program <span class="operator">=</span> <span class="string">"./path/to/Qt/examples/widgets/analogclock"</span>;
<span class="type"><a href="qstringlist.html">QStringList</a></span> arguments;
arguments <span class="operator"><</span><span class="operator"><</span> <span class="string">"-style"</span> <span class="operator"><</span><span class="operator"><</span> <span class="string">"motif"</span>;
<span class="type">QProcess</span> <span class="operator">*</span>myProcess <span class="operator">=</span> <span class="keyword">new</span> <span class="type">QProcess</span>(parent);
myProcess<span class="operator">-</span><span class="operator">></span>start(program<span class="operator">,</span> arguments);
</pre>
<p>QProcess then enters the <a href="qprocess.html#ProcessState-enum">Starting</a> state, and when the
program has started, QProcess enters the <a href="qprocess.html#ProcessState-enum">Running</a> state and emits
<a href="qprocess.html#started">started</a>().</p>
<p>QProcess allows you to treat a process as a sequential I/O
device. You can write to and read from the process just as you
would access a network connection using <a href="qtcpsocket.html">QTcpSocket</a>. You can then write to the
process's standard input by calling <a href="qiodevice.html#write">write</a>(), and read the standard output by
calling <a href="qiodevice.html#read">read</a>(), <a href="qiodevice.html#readLine">readLine</a>(), and <a href="qiodevice.html#getChar">getChar</a>(). Because it inherits
<a href="qiodevice.html">QIODevice</a>, QProcess can also be used
as an input source for <a href="qxmlreader.html">QXmlReader</a>, or
for generating data to be uploaded using <a href="qftp.html">QFtp</a>.</p>
<p><b>Note:</b> On VxWorks, Windows CE and Symbian, reading and
writing to a process is not supported.</p>
<p>When the process exits, QProcess reenters the <a href="qprocess.html#ProcessState-enum">NotRunning</a> state (the initial
state), and emits <a href="qprocess.html#finished">finished</a>().</p>
<p>The <a href="qprocess.html#finished">finished</a>() signal
provides the exit code and exit status of the process as arguments,
and you can also call <a href="qprocess.html#exitCode">exitCode</a>() to obtain the exit code of
the last process that finished, and <a href="qprocess.html#exitStatus">exitStatus</a>() to obtain its exit
status. If an error occurs at any point in time, QProcess will emit
the <a href="qprocess.html#error">error</a>() signal. You can also
call <a href="qprocess.html#error">error</a>() to find the type of
error that occurred last, and <a href="qprocess.html#state">state</a>() to find the current process
state.</p>
<a id="communicating-via-channels" name="communicating-via-channels" />
<h3>Communicating via Channels</h3>
<p>Processes have two predefined output channels: The standard
output channel (<tt>stdout</tt>) supplies regular console output,
and the standard error channel (<tt>stderr</tt>) usually supplies
the errors that are printed by the process. These channels
represent two separate streams of data. You can toggle between them
by calling <a href="qprocess.html#setReadChannel">setReadChannel</a>(). QProcess emits
<a href="qiodevice.html#readyRead">readyRead</a>() when data is
available on the current read channel. It also emits <a href="qprocess.html#readyReadStandardOutput">readyReadStandardOutput</a>()
when new standard output data is available, and when new standard
error data is available, <a href="qprocess.html#readyReadStandardError">readyReadStandardError</a>()
is emitted. Instead of calling <a href="qiodevice.html#read">read</a>(), <a href="qiodevice.html#readLine">readLine</a>(), or <a href="qiodevice.html#getChar">getChar</a>(), you can explicitly read all
data from either of the two channels by calling <a href="qprocess.html#readAllStandardOutput">readAllStandardOutput</a>()
or <a href="qprocess.html#readAllStandardError">readAllStandardError</a>().</p>
<p>The terminology for the channels can be misleading. Be aware
that the process's output channels correspond to QProcess's
<i>read</i> channels, whereas the process's input channels
correspond to QProcess's <i>write</i> channels. This is because
what we read using QProcess is the process's output, and what we
write becomes the process's input.</p>
<p>QProcess can merge the two output channels, so that standard
output and standard error data from the running process both use
the standard output channel. Call <a href="qprocess.html#setProcessChannelMode">setProcessChannelMode</a>()
with <a href="qprocess.html#ProcessChannelMode-enum">MergedChannels</a> before
starting the process to activative this feature. You also have the
option of forwarding the output of the running process to the
calling, main process, by passing <a href="qprocess.html#ProcessChannelMode-enum">ForwardedChannels</a> as
the argument.</p>
<p>Certain processes need special environment settings in order to
operate. You can set environment variables for your process by
calling <a href="qprocess.html#setEnvironment">setEnvironment</a>(). To set a
working directory, call <a href="qprocess.html#setWorkingDirectory">setWorkingDirectory</a>(). By
default, processes are run in the current working directory of the
calling process.</p>
<p><b>Note:</b> On VxWorks, communicating via channels with a
process is not supported.</p>
<p><b>Note:</b> On Symbian, setting environment or working
directory is not supported. The working directory will always be
the private directory of the running process.</p>
<p><b>Note:</b> On QNX, setting the working directory may cause all
application threads, with the exception of the QProcess caller
thread, to temporarily freeze, owing to a limitation in the
operating system.</p>
<a id="synchronous-process-api" name="synchronous-process-api" />
<h3>Synchronous Process API</h3>
<p>QProcess provides a set of functions which allow it to be used
without an event loop, by suspending the calling thread until
certain signals are emitted:</p>
<ul>
<li><a href="qprocess.html#waitForStarted">waitForStarted</a>()
blocks until the process has started.</li>
<li><a href="qprocess.html#waitForReadyRead">waitForReadyRead</a>()
blocks until new data is available for reading on the current read
channel.</li>
<li><a href="qprocess.html#waitForBytesWritten">waitForBytesWritten</a>()
blocks until one payload of data has been written to the
process.</li>
<li><a href="qprocess.html#waitForFinished">waitForFinished</a>()
blocks until the process has finished.</li>
</ul>
<p>Calling these functions from the main thread (the thread that
calls <a href="qapplication.html#exec">QApplication.exec</a>())
may cause your user interface to freeze.</p>
<p>The following example runs <tt>gzip</tt> to compress the string
"Qt rocks!", without an event loop:</p>
<pre class="cpp">
<span class="type">QProcess</span> gzip;
gzip<span class="operator">.</span>start(<span class="string">"gzip"</span><span class="operator">,</span> <span class="type"><a href="qstringlist.html">QStringList</a></span>() <span class="operator"><</span><span class="operator"><</span> <span class="string">"-c"</span>);
<span class="keyword">if</span> (<span class="operator">!</span>gzip<span class="operator">.</span>waitForStarted())
<span class="keyword">return</span> <span class="keyword">false</span>;
gzip<span class="operator">.</span>write(<span class="string">"Qt rocks!"</span>);
gzip<span class="operator">.</span>closeWriteChannel();
<span class="keyword">if</span> (<span class="operator">!</span>gzip<span class="operator">.</span>waitForFinished())
<span class="keyword">return</span> <span class="keyword">false</span>;
<span class="type"><a href="qbytearray.html">QByteArray</a></span> result <span class="operator">=</span> gzip<span class="operator">.</span>readAll();
</pre>
<a id="notes-for-windows-users" name="notes-for-windows-users" />
<h3>Notes for Windows Users</h3>
<p>Some Windows commands (for example, <tt>dir</tt>) are not
provided by separate applications, but by the command interpreter
itself. If you attempt to use QProcess to execute these commands
directly, it won't work. One possible solution is to execute the
command interpreter itself (<tt>cmd.exe</tt> on some Windows
systems), and ask the interpreter to execute the desired
command.</p>
<a id="notes-for-vxworks-users" name="notes-for-vxworks-users" />
<h3>Notes for VxWorks Users</h3>
<p>QProcess support is only available on RTP mode, and only a
limited functionality is provided. When using QProcess to launch Qt
applications, the launched application has to have the following
code:</p>
<pre class="cpp">
<span class="preprocessor">#include <signal.h></span>
</pre>
<p>Add following to your class constructor:</p>
<pre class="cpp">
<span class="type"><a href="qobject.html">QObject</a></span><span class="operator">.</span><a href="qobject.html#connect">connect</a>(<span class="type"><a href="qapplication.html">QApplication</a></span><span class="operator">.</span>instance()<span class="operator">,</span> SIGNAL(unixSignal(<span class="type">int</span>))<span class="operator">,</span> qApp<span class="operator">,</span> SLOT(quit()));
<span class="type"><a href="qcoreapplication.html">QCoreApplication</a></span><span class="operator">.</span>watchUnixSignal(SIGKILL<span class="operator">,</span> <span class="keyword">true</span>);
<span class="type"><a href="qcoreapplication.html">QCoreApplication</a></span><span class="operator">.</span>watchUnixSignal(SIGTERM<span class="operator">,</span> <span class="keyword">true</span>);
</pre>
<a id="symbian-platform-security-requirements" name="symbian-platform-security-requirements" />
<h3>Symbian Platform Security Requirements</h3>
<p>On Symbian, processes which use the functions <a href="qprocess.html#kill">kill</a>() or <a href="qprocess.html#terminate">terminate</a>() must have the
<tt>PowerMgmt</tt> platform security capability. If the client
process lacks this capability, these functions will fail.</p>
<p>Platform security capabilities are added via the <a href="qmake-variable-reference.html#target-capability">TARGET.CAPABILITY</a>
qmake variable.</p>
<hr /><h2>Type Documentation</h2><h3 class="fn"><a name="ExitStatus-enum" />QProcess.ExitStatus</h3><p>This enum describes the different exit statuses of <a href="qprocess.html">QProcess</a>.</p>
<table class="valuelist">
<tr class="odd" valign="top">
<th class="tblConst">Constant</th>
<th class="tblval">Value</th>
<th class="tbldscr">Description</th>
</tr>
<tr>
<td class="topAlign"><tt>QProcess.NormalExit</tt></td>
<td class="topAlign"><tt>0</tt></td>
<td class="topAlign">The process exited normally.</td>
</tr>
<tr>
<td class="topAlign"><tt>QProcess.CrashExit</tt></td>
<td class="topAlign"><tt>1</tt></td>
<td class="topAlign">The process crashed.</td>
</tr>
</table>
<p><b>See also</b> <a href="qprocess.html#exitStatus">exitStatus</a>().</p>
<h3 class="fn"><a name="ProcessChannel-enum" />QProcess.ProcessChannel</h3><p>This enum describes the process channels used by the running
process. Pass one of these values to <a href="qprocess.html#setReadChannel">setReadChannel</a>() to set the
current read channel of <a href="qprocess.html">QProcess</a>.</p>
<table class="valuelist">
<tr class="odd" valign="top">
<th class="tblConst">Constant</th>
<th class="tblval">Value</th>
<th class="tbldscr">Description</th>
</tr>
<tr>
<td class="topAlign"><tt>QProcess.StandardOutput</tt></td>
<td class="topAlign"><tt>0</tt></td>
<td class="topAlign">The standard output (stdout) of the running
process.</td>
</tr>
<tr>
<td class="topAlign"><tt>QProcess.StandardError</tt></td>
<td class="topAlign"><tt>1</tt></td>
<td class="topAlign">The standard error (stderr) of the running
process.</td>
</tr>
</table>
<p><b>See also</b> <a href="qprocess.html#setReadChannel">setReadChannel</a>().</p>
<h3 class="fn"><a name="ProcessChannelMode-enum" />QProcess.ProcessChannelMode</h3><p>This enum describes the process channel modes of <a href="qprocess.html">QProcess</a>. Pass one of these values to <a href="qprocess.html#setProcessChannelMode">setProcessChannelMode</a>()
to set the current read channel mode.</p>
<table class="valuelist">
<tr class="odd" valign="top">
<th class="tblConst">Constant</th>
<th class="tblval">Value</th>
<th class="tbldscr">Description</th>
</tr>
<tr>
<td class="topAlign"><tt>QProcess.SeparateChannels</tt></td>
<td class="topAlign"><tt>0</tt></td>
<td class="topAlign"><a href="qprocess.html">QProcess</a> manages
the output of the running process, keeping standard output and
standard error data in separate internal buffers. You can select
the <a href="qprocess.html">QProcess</a>'s current read channel by
calling <a href="qprocess.html#setReadChannel">setReadChannel</a>(). This is the
default channel mode of <a href="qprocess.html">QProcess</a>.</td>
</tr>
<tr>
<td class="topAlign"><tt>QProcess.MergedChannels</tt></td>
<td class="topAlign"><tt>1</tt></td>
<td class="topAlign"><a href="qprocess.html">QProcess</a> merges
the output of the running process into the standard output channel
(<tt>stdout</tt>). The standard error channel (<tt>stderr</tt>)
will not receive any data. The standard output and standard error
data of the running process are interleaved.</td>
</tr>
<tr>
<td class="topAlign"><tt>QProcess.ForwardedChannels</tt></td>
<td class="topAlign"><tt>2</tt></td>
<td class="topAlign"><a href="qprocess.html">QProcess</a> forwards
the output of the running process onto the main process. Anything
the child process writes to its standard output and standard error
will be written to the standard output and standard error of the
main process.</td>
</tr>
</table>
<p><b>See also</b> <a href="qprocess.html#setProcessChannelMode">setProcessChannelMode</a>().</p>
<h3 class="fn"><a name="ProcessError-enum" />QProcess.ProcessError</h3><p>This enum describes the different types of errors that are
reported by <a href="qprocess.html">QProcess</a>.</p>
<table class="valuelist">
<tr class="odd" valign="top">
<th class="tblConst">Constant</th>
<th class="tblval">Value</th>
<th class="tbldscr">Description</th>
</tr>
<tr>
<td class="topAlign"><tt>QProcess.FailedToStart</tt></td>
<td class="topAlign"><tt>0</tt></td>
<td class="topAlign">The process failed to start. Either the
invoked program is missing, or you may have insufficient
permissions to invoke the program.</td>
</tr>
<tr>
<td class="topAlign"><tt>QProcess.Crashed</tt></td>
<td class="topAlign"><tt>1</tt></td>
<td class="topAlign">The process crashed some time after starting
successfully.</td>
</tr>
<tr>
<td class="topAlign"><tt>QProcess.Timedout</tt></td>
<td class="topAlign"><tt>2</tt></td>
<td class="topAlign">The last waitFor...() function timed out. The
state of <a href="qprocess.html">QProcess</a> is unchanged, and you
can try calling waitFor...() again.</td>
</tr>
<tr>
<td class="topAlign"><tt>QProcess.WriteError</tt></td>
<td class="topAlign"><tt>4</tt></td>
<td class="topAlign">An error occurred when attempting to write to
the process. For example, the process may not be running, or it may
have closed its input channel.</td>
</tr>
<tr>
<td class="topAlign"><tt>QProcess.ReadError</tt></td>
<td class="topAlign"><tt>3</tt></td>
<td class="topAlign">An error occurred when attempting to read from
the process. For example, the process may not be running.</td>
</tr>
<tr>
<td class="topAlign"><tt>QProcess.UnknownError</tt></td>
<td class="topAlign"><tt>5</tt></td>
<td class="topAlign">An unknown error occurred. This is the default
return value of <a href="qprocess.html#error">error</a>().</td>
</tr>
</table>
<p><b>See also</b> <a href="qprocess.html#error">error</a>().</p>
<h3 class="fn"><a name="ProcessState-enum" />QProcess.ProcessState</h3><p>This enum describes the different states of <a href="qprocess.html">QProcess</a>.</p>
<table class="valuelist">
<tr class="odd" valign="top">
<th class="tblConst">Constant</th>
<th class="tblval">Value</th>
<th class="tbldscr">Description</th>
</tr>
<tr>
<td class="topAlign"><tt>QProcess.NotRunning</tt></td>
<td class="topAlign"><tt>0</tt></td>
<td class="topAlign">The process is not running.</td>
</tr>
<tr>
<td class="topAlign"><tt>QProcess.Starting</tt></td>
<td class="topAlign"><tt>1</tt></td>
<td class="topAlign">The process is starting, but the program has
not yet been invoked.</td>
</tr>
<tr>
<td class="topAlign"><tt>QProcess.Running</tt></td>
<td class="topAlign"><tt>2</tt></td>
<td class="topAlign">The process is running and is ready for
reading and writing.</td>
</tr>
</table>
<p><b>See also</b> <a href="qprocess.html#state">state</a>().</p>
<hr /><h2>Method Documentation</h2><h3 class="fn"><a name="QProcess" />QProcess.__init__ (<i>self</i>, <a href="qobject.html">QObject</a> <i>parent</i> = None)</h3><p>The <i>parent</i> argument, if not None, causes <i>self</i> to be owned by Qt instead of PyQt.</p><p>Constructs a <a href="qprocess.html">QProcess</a> object with
the given <i>parent</i>.</p>
<h3 class="fn"><a name="atEnd" />bool QProcess.atEnd (<i>self</i>)</h3><p>Reimplemented from <a href="qiodevice.html#atEnd">QIODevice.atEnd</a>().</p>
<p>Returns true if the process is not running, and no more data is
available for reading; otherwise returns false.</p>
<h3 class="fn"><a name="bytesAvailable" />int QProcess.bytesAvailable (<i>self</i>)</h3><p>Reimplemented from <a href="qiodevice.html#bytesAvailable">QIODevice.bytesAvailable</a>().</p>
<h3 class="fn"><a name="bytesToWrite" />int QProcess.bytesToWrite (<i>self</i>)</h3><p>Reimplemented from <a href="qiodevice.html#bytesToWrite">QIODevice.bytesToWrite</a>().</p>
<h3 class="fn"><a name="canReadLine" />bool QProcess.canReadLine (<i>self</i>)</h3><p>Reimplemented from <a href="qiodevice.html#canReadLine">QIODevice.canReadLine</a>().</p>
<p>This function operates on the current read channel.</p>
<p><b>See also</b> <a href="qprocess.html#readChannel">readChannel</a>() and <a href="qprocess.html#setReadChannel">setReadChannel</a>().</p>
<h3 class="fn"><a name="close" />QProcess.close (<i>self</i>)</h3><p>Reimplemented from <a href="qiodevice.html#close">QIODevice.close</a>().</p>
<p>Closes all communication with the process and kills it. After
calling this function, <a href="qprocess.html">QProcess</a> will no
longer emit <a href="qiodevice.html#readyRead">readyRead</a>(), and
data can no longer be read or written.</p>
<h3 class="fn"><a name="closeReadChannel" />QProcess.closeReadChannel (<i>self</i>, <a href="qprocess.html#ProcessChannel-enum">ProcessChannel</a> <i>channel</i>)</h3><p>Closes the read channel <i>channel</i>. After calling this
function, <a href="qprocess.html">QProcess</a> will no longer
receive data on the channel. Any data that has already been
received is still available for reading.</p>
<p>Call this function to save memory, if you are not interested in
the output of the process.</p>
<p><b>See also</b> <a href="qprocess.html#closeWriteChannel">closeWriteChannel</a>() and
<a href="qprocess.html#setReadChannel">setReadChannel</a>().</p>
<h3 class="fn"><a name="closeWriteChannel" />QProcess.closeWriteChannel (<i>self</i>)</h3><p>Schedules the write channel of <a href="qprocess.html">QProcess</a> to be closed. The channel will close
once all data has been written to the process. After calling this
function, any attempts to write to the process will fail.</p>
<p>Closing the write channel is necessary for programs that read
input data until the channel has been closed. For example, the
program "more" is used to display text data in a console on both
Unix and Windows. But it will not display the text data until
<a href="qprocess.html">QProcess</a>'s write channel has been
closed. Example:</p>
<pre class="cpp">
<span class="type"><a href="qprocess.html">QProcess</a></span> more;
more<span class="operator">.</span>start(<span class="string">"more"</span>);
more<span class="operator">.</span>write(<span class="string">"Text to display"</span>);
more<span class="operator">.</span>closeWriteChannel();
<span class="comment">// QProcess will emit readyRead() once "more" starts printing</span>
</pre>
<p>The write channel is implicitly opened when <a href="qprocess.html#start">start</a>() is called.</p>
<p><b>See also</b> <a href="qprocess.html#closeReadChannel">closeReadChannel</a>().</p>
<h3 class="fn"><a name="environment" />QStringList QProcess.environment (<i>self</i>)</h3><p>This function is deprecated.</p>
<p>Returns the environment that <a href="qprocess.html">QProcess</a> will use when starting a process, or
an empty <a href="qstringlist.html">QStringList</a> if no
environment has been set using <a href="qprocess.html#setEnvironment">setEnvironment</a>() or
setEnvironmentHash(). If no environment has been set, the
environment of the calling process will be used.</p>
<p><b>Note:</b> The environment settings are ignored on Windows CE
and Symbian, as there is no concept of an environment.</p>
<p><b>See also</b> <a href="qprocess.html#processEnvironment">processEnvironment</a>(),
<a href="qprocess.html#setEnvironment">setEnvironment</a>(), and
<a href="qprocess.html#systemEnvironment">systemEnvironment</a>().</p>
<h3 class="fn"><a name="error" /><a href="qprocess.html#ProcessError-enum">ProcessError</a> QProcess.error (<i>self</i>)</h3><p>Returns the type of error that occurred last.</p>
<p><b>See also</b> <a href="qprocess.html#state">state</a>().</p>
<h3 class="fn"><a name="execute" />int QProcess.execute (QString <i>program</i>, QStringList <i>arguments</i>)</h3><p>Starts the program <i>program</i> with the arguments
<i>arguments</i> in a new process, waits for it to finish, and then
returns the exit code of the process. Any data the new process
writes to the console is forwarded to the calling process.</p>
<p>The environment and working directory are inherited from the
calling process.</p>
<p>On Windows, arguments that contain spaces are wrapped in
quotes.</p>
<p>If the process cannot be started, -2 is returned. If the process
crashes, -1 is returned. Otherwise, the process' exit code is
returned.</p>
<h3 class="fn"><a name="execute-2" />int QProcess.execute (QString <i>program</i>)</h3><p>This is an overloaded function.</p>
<p>Starts the program <i>program</i> in a new process.
<i>program</i> is a single string of text containing both the
program name and its arguments. The arguments are separated by one
or more spaces.</p>
<h3 class="fn"><a name="exitCode" />int QProcess.exitCode (<i>self</i>)</h3><p>Returns the exit code of the last process that finished.</p>
<h3 class="fn"><a name="exitStatus" /><a href="qprocess.html#ExitStatus-enum">ExitStatus</a> QProcess.exitStatus (<i>self</i>)</h3><p>Returns the exit status of the last process that finished.</p>
<p>On Windows, if the process was terminated with
TerminateProcess() from another application this function will
still return <a href="qprocess.html#ExitStatus-enum">NormalExit</a>
unless the exit code is less than 0.</p>
<p>This function was introduced in Qt 4.1.</p>
<h3 class="fn"><a name="isSequential" />bool QProcess.isSequential (<i>self</i>)</h3><p>Reimplemented from <a href="qiodevice.html#isSequential">QIODevice.isSequential</a>().</p>
<h3 class="fn"><a name="kill" />QProcess.kill (<i>self</i>)</h3><p>This method is also a Qt slot with the C++ signature <tt>void kill()</tt>.</p><p>Kills the current process, causing it to exit immediately.</p>
<p>On Windows, kill() uses TerminateProcess, and on Unix and Mac OS
X, the SIGKILL signal is sent to the process.</p>
<p>On Symbian, this function requires platform security capability
<tt>PowerMgmt</tt>. If absent, the process will panic with
KERN-EXEC 46.</p>
<p><b>Note:</b> Killing running processes from other processes will
typically cause a panic in Symbian due to platform security.</p>
<p><b>See also</b> <a href="symbian-platform-security-requirements.html">Symbian Platform
Security Requirements</a> and <a href="qprocess.html#terminate">terminate</a>().</p>
<h3 class="fn"><a name="pid" />int QProcess.pid (<i>self</i>)</h3><p>Returns the native process identifier for the running process,
if available. If no process is currently running, 0 is
returned.</p>
<h3 class="fn"><a name="processChannelMode" /><a href="qprocess.html#ProcessChannelMode-enum">ProcessChannelMode</a> QProcess.processChannelMode (<i>self</i>)</h3><p>Returns the channel mode of the <a href="qprocess.html">QProcess</a> standard output and standard error
channels.</p>
<p>This function was introduced in Qt 4.2.</p>
<p><b>See also</b> <a href="qprocess.html#setProcessChannelMode">setProcessChannelMode</a>(),
<a href="qprocess.html#ProcessChannelMode-enum">ProcessChannelMode</a>, and
<a href="qprocess.html#setReadChannel">setReadChannel</a>().</p>
<h3 class="fn"><a name="processEnvironment" /><a href="qprocessenvironment.html">QProcessEnvironment</a> QProcess.processEnvironment (<i>self</i>)</h3><p>Returns the environment that <a href="qprocess.html">QProcess</a> will use when starting a process, or
an empty object if no environment has been set using <a href="qprocess.html#setEnvironment">setEnvironment</a>() or <a href="qprocess.html#setProcessEnvironment">setProcessEnvironment</a>().
If no environment has been set, the environment of the calling
process will be used.</p>
<p><b>Note:</b> The environment settings are ignored on Windows CE,
as there is no concept of an environment.</p>
<p>This function was introduced in Qt 4.6.</p>
<p><b>See also</b> <a href="qprocess.html#setProcessEnvironment">setProcessEnvironment</a>(),
<a href="qprocess.html#setEnvironment">setEnvironment</a>(), and
<a href="qprocessenvironment.html#isEmpty">QProcessEnvironment.isEmpty</a>().</p>
<h3 class="fn"><a name="readAllStandardError" /><a href="qbytearray.html">QByteArray</a> QProcess.readAllStandardError (<i>self</i>)</h3><p>Regardless of the current read channel, this function returns
all data available from the standard error of the process as a
<a href="qbytearray.html">QByteArray</a>.</p>
<p><b>See also</b> <a href="qprocess.html#readyReadStandardError">readyReadStandardError</a>(),
<a href="qprocess.html#readAllStandardOutput">readAllStandardOutput</a>(),
<a href="qprocess.html#readChannel">readChannel</a>(), and <a href="qprocess.html#setReadChannel">setReadChannel</a>().</p>
<h3 class="fn"><a name="readAllStandardOutput" /><a href="qbytearray.html">QByteArray</a> QProcess.readAllStandardOutput (<i>self</i>)</h3><p>Regardless of the current read channel, this function returns
all data available from the standard output of the process as a
<a href="qbytearray.html">QByteArray</a>.</p>
<p><b>See also</b> <a href="qprocess.html#readyReadStandardOutput">readyReadStandardOutput</a>(),
<a href="qprocess.html#readAllStandardError">readAllStandardError</a>(),
<a href="qprocess.html#readChannel">readChannel</a>(), and <a href="qprocess.html#setReadChannel">setReadChannel</a>().</p>
<h3 class="fn"><a name="readChannel" /><a href="qprocess.html#ProcessChannel-enum">ProcessChannel</a> QProcess.readChannel (<i>self</i>)</h3><p>Returns the current read channel of the <a href="qprocess.html">QProcess</a>.</p>
<p><b>See also</b> <a href="qprocess.html#setReadChannel">setReadChannel</a>().</p>
<h3 class="fn"><a name="readChannelMode" /><a href="qprocess.html#ProcessChannelMode-enum">ProcessChannelMode</a> QProcess.readChannelMode (<i>self</i>)</h3><h3 class="fn"><a name="readData" />object QProcess.readData (<i>self</i>, int <i>maxlen</i>)</h3><p>Reimplemented from <a href="qiodevice.html#readData">QIODevice.readData</a>().</p>
<h3 class="fn"><a name="setEnvironment" />QProcess.setEnvironment (<i>self</i>, QStringList <i>environment</i>)</h3><p>This function is deprecated.</p>
<p>Sets the environment that <a href="qprocess.html">QProcess</a>
will use when starting a process to the <i>environment</i>
specified which consists of a list of key=value pairs.</p>
<p>For example, the following code adds the <tt>C:\\BIN</tt>
directory to the list of executable paths (<tt>PATHS</tt>) on
Windows:</p>
<pre class="cpp">
<span class="type"><a href="qprocess.html">QProcess</a></span> process;
<span class="type"><a href="qstringlist.html">QStringList</a></span> env <span class="operator">=</span> <span class="type"><a href="qprocess.html">QProcess</a></span><span class="operator">.</span>systemEnvironment();
env <span class="operator"><</span><span class="operator"><</span> <span class="string">"TMPDIR=C:\\MyApp\\temp"</span>; <span class="comment">// Add an environment variable</span>
env<span class="operator">.</span>replaceInStrings(<span class="type"><a href="qregexp.html">QRegExp</a></span>(<span class="string">"^PATH=(.*)"</span><span class="operator">,</span> <span class="type"><a href="qt.html">Qt</a></span><span class="operator">.</span>CaseInsensitive)<span class="operator">,</span> <span class="string">"PATH=\\1;C:\\Bin"</span>);
process<span class="operator">.</span>setEnvironment(env);
process<span class="operator">.</span>start(<span class="string">"myapp"</span>);
</pre>
<p><b>Note:</b> This function is less efficient than the <a href="qprocess.html#setProcessEnvironment">setProcessEnvironment</a>()
function.</p>
<p><b>See also</b> <a href="qprocess.html#environment">environment</a>(), <a href="qprocess.html#setProcessEnvironment">setProcessEnvironment</a>(),
and <a href="qprocess.html#systemEnvironment">systemEnvironment</a>().</p>
<h3 class="fn"><a name="setProcessChannelMode" />QProcess.setProcessChannelMode (<i>self</i>, <a href="qprocess.html#ProcessChannelMode-enum">ProcessChannelMode</a> <i>mode</i>)</h3><p>Sets the channel mode of the <a href="qprocess.html">QProcess</a> standard output and standard error
channels to the <i>mode</i> specified. This mode will be used the
next time <a href="qprocess.html#start">start</a>() is called. For
example:</p>
<pre class="cpp">
<span class="type"><a href="qprocess.html">QProcess</a></span> builder;
builder<span class="operator">.</span>setProcessChannelMode(<span class="type"><a href="qprocess.html">QProcess</a></span><span class="operator">.</span>MergedChannels);
builder<span class="operator">.</span>start(<span class="string">"make"</span><span class="operator">,</span> <span class="type"><a href="qstringlist.html">QStringList</a></span>() <span class="operator"><</span><span class="operator"><</span> <span class="string">"-j2"</span>);
<span class="keyword">if</span> (<span class="operator">!</span>builder<span class="operator">.</span>waitForFinished())
<a href="qtcore.html#qDebug">qDebug</a>() <span class="operator"><</span><span class="operator"><</span> <span class="string">"Make failed:"</span> <span class="operator"><</span><span class="operator"><</span> builder<span class="operator">.</span>errorString();
<span class="keyword">else</span>
<a href="qtcore.html#qDebug">qDebug</a>() <span class="operator"><</span><span class="operator"><</span> <span class="string">"Make output:"</span> <span class="operator"><</span><span class="operator"><</span> builder<span class="operator">.</span>readAll();
</pre>
<p>This function was introduced in Qt 4.2.</p>
<p><b>See also</b> <a href="qprocess.html#processChannelMode">processChannelMode</a>(),
<a href="qprocess.html#ProcessChannelMode-enum">ProcessChannelMode</a>, and
<a href="qprocess.html#setReadChannel">setReadChannel</a>().</p>
<h3 class="fn"><a name="setProcessEnvironment" />QProcess.setProcessEnvironment (<i>self</i>, <a href="qprocessenvironment.html">QProcessEnvironment</a> <i>environment</i>)</h3><p>Sets the environment that <a href="qprocess.html">QProcess</a>
will use when starting a process to the <i>environment</i>
object.</p>
<p>For example, the following code adds the <tt>C:\\BIN</tt>
directory to the list of executable paths (<tt>PATHS</tt>) on
Windows and sets <tt>TMPDIR</tt>:</p>
<pre class="cpp">
<span class="type"><a href="qprocess.html">QProcess</a></span> process;
<span class="type"><a href="qprocessenvironment.html">QProcessEnvironment</a></span> env <span class="operator">=</span> <span class="type"><a href="qprocessenvironment.html">QProcessEnvironment</a></span><span class="operator">.</span>systemEnvironment();
env<span class="operator">.</span>insert(<span class="string">"TMPDIR"</span><span class="operator">,</span> <span class="string">"C:\\MyApp\\temp"</span>); <span class="comment">// Add an environment variable</span>
env<span class="operator">.</span>insert(<span class="string">"PATH"</span><span class="operator">,</span> env<span class="operator">.</span>value(<span class="string">"Path"</span>) <span class="operator">+</span> <span class="string">";C:\\Bin"</span>);
process<span class="operator">.</span>setProcessEnvironment(env);
process<span class="operator">.</span>start(<span class="string">"myapp"</span>);
</pre>
<p>Note how, on Windows, environment variable names are
case-insensitive.</p>
<p>This function was introduced in Qt 4.6.</p>
<p><b>See also</b> <a href="qprocess.html#processEnvironment">processEnvironment</a>(),
<a href="qprocessenvironment.html#systemEnvironment">QProcessEnvironment.systemEnvironment</a>(),
and <a href="qprocess.html#setEnvironment">setEnvironment</a>().</p>
<h3 class="fn"><a name="setProcessState" />QProcess.setProcessState (<i>self</i>, <a href="qprocess.html#ProcessState-enum">ProcessState</a> <i>state</i>)</h3><p>Sets the current state of the <a href="qprocess.html">QProcess</a> to the <i>state</i> specified.</p>
<p><b>See also</b> <a href="qprocess.html#state">state</a>().</p>
<h3 class="fn"><a name="setReadChannel" />QProcess.setReadChannel (<i>self</i>, <a href="qprocess.html#ProcessChannel-enum">ProcessChannel</a> <i>channel</i>)</h3><p>Sets the current read channel of the <a href="qprocess.html">QProcess</a> to the given <i>channel</i>. The
current input channel is used by the functions <a href="qiodevice.html#read">read</a>(), <a href="qiodevice.html#readAll">readAll</a>(), <a href="qiodevice.html#readLine">readLine</a>(), and <a href="qiodevice.html#getChar">getChar</a>(). It also determines which
channel triggers <a href="qprocess.html">QProcess</a> to emit
<a href="qiodevice.html#readyRead">readyRead</a>().</p>
<p><b>See also</b> <a href="qprocess.html#readChannel">readChannel</a>().</p>
<h3 class="fn"><a name="setReadChannelMode" />QProcess.setReadChannelMode (<i>self</i>, <a href="qprocess.html#ProcessChannelMode-enum">ProcessChannelMode</a> <i>mode</i>)</h3><h3 class="fn"><a name="setStandardErrorFile" />QProcess.setStandardErrorFile (<i>self</i>, QString <i>fileName</i>, <a href="qiodevice-openmode.html">QIODevice.OpenMode</a> <i>mode</i> = QIODevice.Truncate)</h3><p>Redirects the process' standard error to the file
<i>fileName</i>. When the redirection is in place, the standard
error read channel is closed: reading from it using <a href="qiodevice.html#read">read</a>() will always fail, as will <a href="qprocess.html#readAllStandardError">readAllStandardError</a>().
The file will be appended to if <i>mode</i> is Append, otherwise,
it will be truncated.</p>
<p>See <a href="qprocess.html#setStandardOutputFile">setStandardOutputFile</a>()
for more information on how the file is opened.</p>
<p>Note: if <a href="qprocess.html#setProcessChannelMode">setProcessChannelMode</a>()
was called with an argument of <a href="qprocess.html#ProcessChannelMode-enum">QProcess.MergedChannels</a>,
this function has no effect.</p>
<p>This function was introduced in Qt 4.2.</p>
<p><b>See also</b> <a href="qprocess.html#setStandardInputFile">setStandardInputFile</a>(),
<a href="qprocess.html#setStandardOutputFile">setStandardOutputFile</a>(),
and <a href="qprocess.html#setStandardOutputProcess">setStandardOutputProcess</a>().</p>
<h3 class="fn"><a name="setStandardInputFile" />QProcess.setStandardInputFile (<i>self</i>, QString <i>fileName</i>)</h3><p>Redirects the process' standard input to the file indicated by
<i>fileName</i>. When an input redirection is in place, the
<a href="qprocess.html">QProcess</a> object will be in read-only
mode (calling <a href="qiodevice.html#write">write</a>() will
result in error).</p>
<p>If the file <i>fileName</i> does not exist at the moment
<a href="qprocess.html#start">start</a>() is called or is not
readable, starting the process will fail.</p>
<p>Calling setStandardInputFile() after the process has started has
no effect.</p>
<p>This function was introduced in Qt 4.2.</p>
<p><b>See also</b> <a href="qprocess.html#setStandardOutputFile">setStandardOutputFile</a>(),
<a href="qprocess.html#setStandardErrorFile">setStandardErrorFile</a>(),
and <a href="qprocess.html#setStandardOutputProcess">setStandardOutputProcess</a>().</p>
<h3 class="fn"><a name="setStandardOutputFile" />QProcess.setStandardOutputFile (<i>self</i>, QString <i>fileName</i>, <a href="qiodevice-openmode.html">QIODevice.OpenMode</a> <i>mode</i> = QIODevice.Truncate)</h3><p>Redirects the process' standard output to the file
<i>fileName</i>. When the redirection is in place, the standard
output read channel is closed: reading from it using <a href="qiodevice.html#read">read</a>() will always fail, as will <a href="qprocess.html#readAllStandardOutput">readAllStandardOutput</a>().</p>
<p>If the file <i>fileName</i> doesn't exist at the moment <a href="qprocess.html#start">start</a>() is called, it will be created. If
it cannot be created, the starting will fail.</p>
<p>If the file exists and <i>mode</i> is <a href="qiodevice.html#OpenModeFlag-enum">QIODevice.Truncate</a>, the
file will be truncated. Otherwise (if <i>mode</i> is <a href="qiodevice.html#OpenModeFlag-enum">QIODevice.Append</a>), the file
will be appended to.</p>
<p>Calling setStandardOutputFile() after the process has started
has no effect.</p>
<p>This function was introduced in Qt 4.2.</p>
<p><b>See also</b> <a href="qprocess.html#setStandardInputFile">setStandardInputFile</a>(),
<a href="qprocess.html#setStandardErrorFile">setStandardErrorFile</a>(),
and <a href="qprocess.html#setStandardOutputProcess">setStandardOutputProcess</a>().</p>
<h3 class="fn"><a name="setStandardOutputProcess" />QProcess.setStandardOutputProcess (<i>self</i>, <a href="qprocess.html">QProcess</a> <i>destination</i>)</h3><p>Pipes the standard output stream of this process to the
<i>destination</i> process' standard input.</p>
<p>The following shell command:</p>
<pre class="cpp">
command1 <span class="operator">|</span> command2
</pre>
<p>Can be accomplished with QProcesses with the following code:</p>
<pre class="cpp">
<span class="type"><a href="qprocess.html">QProcess</a></span> process1;
<span class="type"><a href="qprocess.html">QProcess</a></span> process2;
process1<span class="operator">.</span>setStandardOutputProcess(<span class="operator">&</span>process2);
process1<span class="operator">.</span>start(<span class="string">"command1"</span>);
process2<span class="operator">.</span>start(<span class="string">"command2"</span>);
</pre>
<p>This function was introduced in Qt 4.2.</p>
<h3 class="fn"><a name="setupChildProcess" />QProcess.setupChildProcess (<i>self</i>)</h3><p>This function is called in the child process context just before
the program is executed on Unix or Mac OS X (i.e., after
<i>fork()</i>, but before <i>execve()</i>). Reimplement this
function to do last minute initialization of the child process.
Example:</p>
<pre class="cpp">
<span class="keyword">class</span> SandboxProcess : <span class="keyword">public</span> <span class="type"><a href="qprocess.html">QProcess</a></span>
{
<span class="operator">.</span><span class="operator">.</span><span class="operator">.</span>
<span class="keyword">protected</span>:
<span class="type">void</span> setupChildProcess();
<span class="operator">.</span><span class="operator">.</span><span class="operator">.</span>
};
<span class="type">void</span> SandboxProcess<span class="operator">.</span>setupChildProcess()
{
<span class="comment">// Drop all privileges in the child process, and enter</span>
<span class="comment">// a chroot jail.</span>
<span class="preprocessor">#if defined Q_OS_UNIX</span>
<span class="operator">.</span>setgroups(<span class="number">0</span><span class="operator">,</span> <span class="number">0</span>);
<span class="operator">.</span>chroot(<span class="string">"/etc/safe"</span>);
<span class="operator">.</span>chdir(<span class="string">"/"</span>);
<span class="operator">.</span>setgid(safeGid);
<span class="operator">.</span>setuid(safeUid);
<span class="operator">.</span>umask(<span class="number">0</span>);
<span class="preprocessor">#endif</span>
}
</pre>
<p>You cannot exit the process (by calling exit(), for instance)
from this function. If you need to stop the program before it
starts execution, your workaround is to emit <a href="qprocess.html#finished">finished</a>() and then call exit().</p>
<p><b>Warning:</b> This function is called by <a href="qprocess.html">QProcess</a> on Unix and Mac OS X only. On Windows
and QNX, it is not called.</p>
<h3 class="fn"><a name="setWorkingDirectory" />QProcess.setWorkingDirectory (<i>self</i>, QString <i>dir</i>)</h3><p>Sets the working directory to <i>dir</i>. <a href="qprocess.html">QProcess</a> will start the process in this
directory. The default behavior is to start the process in the
working directory of the calling process.</p>
<p><b>Note:</b> The working directory setting is ignored on
Symbian; the private directory of the process is considered its
working directory.</p>
<p><b>Note:</b> On QNX, this may cause all application threads to
temporarily freeze.</p>
<p><b>See also</b> <a href="qprocess.html#workingDirectory">workingDirectory</a>() and
<a href="qprocess.html#start">start</a>().</p>
<h3 class="fn"><a name="start" />QProcess.start (<i>self</i>, QString <i>program</i>, QStringList <i>arguments</i>, <a href="qiodevice-openmode.html">QIODevice.OpenMode</a> <i>mode</i> = QIODevice.ReadWrite)</h3><p>Starts the given <i>program</i> in a new process, if none is
already running, passing the command line arguments in
<i>arguments</i>. The <a href="qiodevice.html#OpenModeFlag-enum">OpenMode</a> is set to
<i>mode</i>.</p>
<p>The <a href="qprocess.html">QProcess</a> object will immediately
enter the Starting state. If the process starts successfully,
<a href="qprocess.html">QProcess</a> will emit <a href="qprocess.html#started">started</a>(); otherwise, <a href="qprocess.html#error">error</a>() will be emitted. If the <a href="qprocess.html">QProcess</a> object is already running a process, a
warning may be printed at the console, and the existing process
will continue running.</p>
<p><b>Note:</b> Processes are started asynchronously, which means
the <a href="qprocess.html#started">started</a>() and <a href="qprocess.html#error">error</a>() signals may be delayed. Call
<a href="qprocess.html#waitForStarted">waitForStarted</a>() to make
sure the process has started (or has failed to start) and those
signals have been emitted.</p>
<p><b>Note:</b> No further splitting of the arguments is
performed.</p>
<p><b>Windows:</b> Arguments that contain spaces are wrapped in
quotes.</p>
<p><b>See also</b> <a href="qprocess.html#pid">pid</a>(), <a href="qprocess.html#started">started</a>(), and <a href="qprocess.html#waitForStarted">waitForStarted</a>().</p>
<h3 class="fn"><a name="start-2" />QProcess.start (<i>self</i>, QString <i>program</i>, <a href="qiodevice-openmode.html">QIODevice.OpenMode</a> <i>mode</i> = QIODevice.ReadWrite)</h3><p>This is an overloaded function.</p>
<p>Starts the program <i>program</i> in a new process, if one is
not already running. <i>program</i> is a single string of text
containing both the program name and its arguments. The arguments
are separated by one or more spaces. For example:</p>
<pre class="cpp">
<span class="type"><a href="qprocess.html">QProcess</a></span> process;
process<span class="operator">.</span>start(<span class="string">"del /s *.txt"</span>);
<span class="comment">// same as process.start("del", QStringList() << "/s" << "*.txt");</span>
<span class="operator">.</span><span class="operator">.</span><span class="operator">.</span>
</pre>
<p>The <i>program</i> string can also contain quotes, to ensure
that arguments containing spaces are correctly supplied to the new
process. For example:</p>
<pre class="cpp">
<span class="type"><a href="qprocess.html">QProcess</a></span> process;
process<span class="operator">.</span>start(<span class="string">"dir \"My Documents\""</span>);
</pre>
<p>If the <a href="qprocess.html">QProcess</a> object is already
running a process, a warning may be printed at the console, and the
existing process will continue running.</p>
<p>Note that, on Windows, quotes need to be both escaped and
quoted. For example, the above code would be specified in the
following way to ensure that <tt>"My Documents"</tt> is used as the
argument to the <tt>dir</tt> executable:</p>
<pre class="cpp">
<span class="type"><a href="qprocess.html">QProcess</a></span> process;
process<span class="operator">.</span>start(<span class="string">"dir \"\"\"My Documents\"\"\""</span>);
</pre>
<p>The <a href="qiodevice.html#OpenModeFlag-enum">OpenMode</a> is
set to <i>mode</i>.</p>
<h3 class="fn"><a name="startDetached" />(bool, int <i>pid</i>) QProcess.startDetached (QString <i>program</i>, QStringList <i>arguments</i>, QString <i>workingDirectory</i>)</h3><p>Starts the program <i>program</i> with the arguments
<i>arguments</i> in a new process, and detaches from it. Returns
true on success; otherwise returns false. If the calling process
exits, the detached process will continue to live.</p>
<p>Note that arguments that contain spaces are not passed to the
process as separate arguments.</p>
<p><b>Unix:</b> The started process will run in its own session and
act like a daemon.</p>
<p><b>Windows:</b> Arguments that contain spaces are wrapped in
quotes. The started process will run as a regular standalone
process.</p>
<p>The process will be started in the directory
<i>workingDirectory</i>.</p>
<p><b>Note:</b> On QNX, this may cause all application threads to
temporarily freeze.</p>
<p><b>Note:</b> On VxWorks, this will start RTP process always with
priority set to 220.</p>
<p>If the function is successful then *<i>pid</i> is set to the
process identifier of the started process.</p>
<h3 class="fn"><a name="startDetached-2" />bool QProcess.startDetached (QString <i>program</i>, QStringList <i>arguments</i>)</h3><p>Starts the program <i>program</i> with the given
<i>arguments</i> in a new process, and detaches from it. Returns
true on success; otherwise returns false. If the calling process
exits, the detached process will continue to live.</p>
<p><b>Note:</b> Arguments that contain spaces are not passed to the
process as separate arguments.</p>
<p><b>Unix:</b> The started process will run in its own session and
act like a daemon.</p>
<p><b>Windows:</b> Arguments that contain spaces are wrapped in
quotes. The started process will run as a regular standalone
process.</p>
<h3 class="fn"><a name="startDetached-3" />bool QProcess.startDetached (QString <i>program</i>)</h3><p>This is an overloaded function.</p>
<p>Starts the program <i>program</i> in a new process.
<i>program</i> is a single string of text containing both the
program name and its arguments. The arguments are separated by one
or more spaces.</p>
<p>The <i>program</i> string can also contain quotes, to ensure
that arguments containing spaces are correctly supplied to the new
process.</p>
<h3 class="fn"><a name="state" /><a href="qprocess.html#ProcessState-enum">ProcessState</a> QProcess.state (<i>self</i>)</h3><p>Returns the current state of the process.</p>
<p><b>See also</b> <a href="qprocess.html#stateChanged">stateChanged</a>() and <a href="qprocess.html#error">error</a>().</p>
<h3 class="fn"><a name="systemEnvironment" />QStringList QProcess.systemEnvironment ()</h3><p>Returns the environment of the calling process as a list of
key=value pairs. Example:</p>
<pre class="cpp">
<span class="type"><a href="qstringlist.html">QStringList</a></span> environment <span class="operator">=</span> <span class="type"><a href="qprocess.html">QProcess</a></span><span class="operator">.</span>systemEnvironment();
<span class="comment">// environment = {"PATH=/usr/bin:/usr/local/bin",</span>
<span class="comment">// "USER=greg", "HOME=/home/greg"}</span>
</pre>
<p>This function does not cache the system environment. Therefore,
it's possible to obtain an updated version of the environment if
low-level C library functions like <tt>setenv</tt> ot
<tt>putenv</tt> have been called.</p>
<p>However, note that repeated calls to this function will recreate
the list of environment variables, which is a non-trivial
operation.</p>
<p><b>Note:</b> For new code, it is recommended to use <a href="qprocessenvironment.html#systemEnvironment">QProcessEnvironment.systemEnvironment</a>()</p>
<p>This function was introduced in Qt 4.1.</p>
<p><b>See also</b> <a href="qprocessenvironment.html#systemEnvironment">QProcessEnvironment.systemEnvironment</a>(),
<a href="qprocess.html#environment">environment</a>(), and <a href="qprocess.html#setEnvironment">setEnvironment</a>().</p>
<h3 class="fn"><a name="terminate" />QProcess.terminate (<i>self</i>)</h3><p>This method is also a Qt slot with the C++ signature <tt>void terminate()</tt>.</p><p>Attempts to terminate the process.</p>
<p>The process may not exit as a result of calling this function
(it is given the chance to prompt the user for any unsaved files,
etc).</p>
<p>On Windows, terminate() posts a WM_CLOSE message to all toplevel
windows of the process and then to the main thread of the process
itself. On Unix and Mac OS X the SIGTERM signal is sent.</p>
<p>Console applications on Windows that do not run an event loop,
or whose event loop does not handle the WM_CLOSE message, can only
be terminated by calling <a href="qprocess.html#kill">kill</a>().</p>
<p>On Symbian, this function requires platform security capability
<tt>PowerMgmt</tt>. If absent, the process will panic with
KERN-EXEC 46.</p>
<p><b>Note:</b> Terminating running processes from other processes
will typically cause a panic in Symbian due to platform
security.</p>
<p><b>See also</b> <a href="symbian-platform-security-requirements.html">Symbian Platform
Security Requirements</a> and <a href="qprocess.html#kill">kill</a>().</p>
<h3 class="fn"><a name="waitForBytesWritten" />bool QProcess.waitForBytesWritten (<i>self</i>, int <i>msecs</i> = 30000)</h3><p>Reimplemented from <a href="qiodevice.html#waitForBytesWritten">QIODevice.waitForBytesWritten</a>().</p>
<h3 class="fn"><a name="waitForFinished" />bool QProcess.waitForFinished (<i>self</i>, int <i>msecs</i> = 30000)</h3><p>Blocks until the process has finished and the <a href="qprocess.html#finished">finished</a>() signal has been emitted, or
until <i>msecs</i> milliseconds have passed.</p>
<p>Returns true if the process finished; otherwise returns false
(if the operation timed out, if an error occurred, or if this
<a href="qprocess.html">QProcess</a> is already finished).</p>
<p>This function can operate without an event loop. It is useful
when writing non-GUI applications and when performing I/O
operations in a non-GUI thread.</p>
<p><b>Warning:</b> Calling this function from the main (GUI) thread
might cause your user interface to freeze.</p>
<p>If msecs is -1, this function will not time out.</p>
<p><b>See also</b> <a href="qprocess.html#finished">finished</a>(),
<a href="qprocess.html#waitForStarted">waitForStarted</a>(),
<a href="qprocess.html#waitForReadyRead">waitForReadyRead</a>(),
and <a href="qprocess.html#waitForBytesWritten">waitForBytesWritten</a>().</p>
<h3 class="fn"><a name="waitForReadyRead" />bool QProcess.waitForReadyRead (<i>self</i>, int <i>msecs</i> = 30000)</h3><p>Reimplemented from <a href="qiodevice.html#waitForReadyRead">QIODevice.waitForReadyRead</a>().</p>
<h3 class="fn"><a name="waitForStarted" />bool QProcess.waitForStarted (<i>self</i>, int <i>msecs</i> = 30000)</h3><p>Blocks until the process has started and the <a href="qprocess.html#started">started</a>() signal has been emitted, or
until <i>msecs</i> milliseconds have passed.</p>
<p>Returns true if the process was started successfully; otherwise
returns false (if the operation timed out or if an error
occurred).</p>
<p>This function can operate without an event loop. It is useful
when writing non-GUI applications and when performing I/O
operations in a non-GUI thread.</p>
<p><b>Warning:</b> Calling this function from the main (GUI) thread
might cause your user interface to freeze.</p>
<p>If msecs is -1, this function will not time out.</p>
<p><b>See also</b> <a href="qprocess.html#started">started</a>(),
<a href="qprocess.html#waitForReadyRead">waitForReadyRead</a>(),
<a href="qprocess.html#waitForBytesWritten">waitForBytesWritten</a>(), and
<a href="qprocess.html#waitForFinished">waitForFinished</a>().</p>
<h3 class="fn"><a name="workingDirectory" />QString QProcess.workingDirectory (<i>self</i>)</h3><p>If <a href="qprocess.html">QProcess</a> has been assigned a
working directory, this function returns the working directory that
the <a href="qprocess.html">QProcess</a> will enter before the
program has started. Otherwise, (i.e., no directory has been
assigned,) an empty string is returned, and <a href="qprocess.html">QProcess</a> will use the application's current
working directory instead.</p>
<p><b>See also</b> <a href="qprocess.html#setWorkingDirectory">setWorkingDirectory</a>().</p>
<h3 class="fn"><a name="writeData" />int QProcess.writeData (<i>self</i>, bytes <i>data</i>)</h3><p>Reimplemented from <a href="qiodevice.html#writeData">QIODevice.writeData</a>().</p>
<hr /><h2>Qt Signal Documentation</h2><h3 class="fn"><a name="error-2" />void error ( ::QProcess::ProcessError)</h3><p>This is the default overload of this signal.</p><p>This signal is emitted when an error occurs with the process.
The specified <i>error</i> describes the type of error that
occurred.</p>
<h3 class="fn"><a name="finished" />void finished (int, ::QProcess::ExitStatus)</h3><p>This is the default overload of this signal.</p><p>This signal is emitted when the process finishes.
<i>exitCode</i> is the exit code of the process, and
<i>exitStatus</i> is the exit status. After the process has
finished, the buffers in <a href="qprocess.html">QProcess</a> are
still intact. You can still read any data that the process may have
written before it finished.</p>
<p><b>See also</b> <a href="qprocess.html#exitStatus">exitStatus</a>().</p>
<h3 class="fn"><a name="finished-2" />void finished (int)</h3><h3 class="fn"><a name="readyReadStandardError" />void readyReadStandardError ()</h3><p>This is the default overload of this signal.</p><p>This signal is emitted when the process has made new data
available through its standard error channel (<tt>stderr</tt>). It
is emitted regardless of the current <a href="qprocess.html#readChannel">read channel</a>.</p>
<p><b>See also</b> <a href="qprocess.html#readAllStandardError">readAllStandardError</a>() and
<a href="qprocess.html#readChannel">readChannel</a>().</p>
<h3 class="fn"><a name="readyReadStandardOutput" />void readyReadStandardOutput ()</h3><p>This is the default overload of this signal.</p><p>This signal is emitted when the process has made new data
available through its standard output channel (<tt>stdout</tt>). It
is emitted regardless of the current <a href="qprocess.html#readChannel">read channel</a>.</p>
<p><b>See also</b> <a href="qprocess.html#readAllStandardOutput">readAllStandardOutput</a>()
and <a href="qprocess.html#readChannel">readChannel</a>().</p>
<h3 class="fn"><a name="started" />void started ()</h3><p>This is the default overload of this signal.</p><p>This signal is emitted by <a href="qprocess.html">QProcess</a>
when the process has started, and <a href="qprocess.html#state">state</a>() returns <a href="qprocess.html#ProcessState-enum">Running</a>.</p>
<h3 class="fn"><a name="stateChanged" />void stateChanged ( ::QProcess::ProcessState)</h3><p>This is the default overload of this signal.</p><p>This signal is emitted whenever the state of <a href="qprocess.html">QProcess</a> changes. The <i>newState</i> argument
is the state <a href="qprocess.html">QProcess</a> changed to.</p>
<address><hr /><div align="center"><table border="0" cellspacing="0" width="100%"><tr class="address"><td align="left" width="25%">PyQt 4.12.1 for X11</td><td align="center" width="50%">Copyright © <a href="http://www.riverbankcomputing.com">Riverbank Computing Ltd</a> and <a href="http://www.qt.io">The Qt Company</a> 2015</td><td align="right" width="25%">Qt 4.8.7</td></tr></table></div></address></body></html>
|
