1
/****************************************************************************
2
** $Id: jprocess.cpp,v 1.4 2003/04/23 10:48:33 justin Exp $
4
** Implementation of QProcess class
8
** Copyright (C) 1992-2000 Trolltech AS. All rights reserved.
10
** This file is part of the kernel module of the Qt GUI Toolkit.
12
** This file may be distributed under the terms of the Q Public License
13
** as defined by Trolltech AS of Norway and appearing in the file
14
** LICENSE.QPL included in the packaging of this file.
16
** This file may be distributed and/or modified under the terms of the
17
** GNU General Public License version 2 as published by the Free Software
18
** Foundation and appearing in the file LICENSE.GPL included in the
19
** packaging of this file.
21
** Licensees holding valid Qt Enterprise Edition or Qt Professional Edition
22
** licenses may use this file in accordance with the Qt Commercial License
23
** Agreement provided with the Software.
25
** This file is provided AS IS with NO WARRANTY OF ANY KIND, INCLUDING THE
26
** WARRANTY OF DESIGN, MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE.
28
** See http://www.trolltech.com/pricing.html or email sales@trolltech.com for
29
** information about Qt Commercial License Agreements.
30
** See http://www.trolltech.com/qpl/ for QPL licensing information.
31
** See http://www.trolltech.com/gpl/ for GPL licensing information.
33
** Contact info@trolltech.com if any conditions of this licensing are
36
**********************************************************************/
45
#include "qapplication.h"
48
//#define QT_QPROCESS_DEBUG
52
\class QProcess qprocess.h
54
\brief The QProcess class is used to start external programs and
55
to communicate with them.
61
You can write to the started program's standard input, and can
62
read the program's standard output and standard error. You can
63
pass command line arguments to the program either in the
64
constructor or with setArguments() or addArgument(). The program's
65
working directory can be set with setWorkingDirectory(). If you
66
need to set up environment variables pass them to the start() or
67
launch() functions (see below). The processExited() signal is
68
emitted if the program exits. The program's exit status is
69
available from exitStatus(), although you could simply call
70
normalExit() to see if the program terminated normally.
72
There are two different ways to start a process. If you just want
73
to run a program, optionally passing data to its standard input at
74
the beginning, use one of the launch() functions. If you want full
75
control of the program's standard input (especially if you don't
76
know all the data you want to send to standard input at the
77
beginning), use the start() function.
79
If you use start() you can write to the program's standard input
80
using writeToStdin() and you can close the standard input with
81
closeStdin(). The wroteToStdin() signal is emitted if the data
82
sent to standard input has been written. You can read from the
83
program's standard output using readStdout() or readLineStdout().
84
These functions return an empty QByteArray if there is no data to
85
read. The readyReadStdout() signal is emitted when there is data
86
available to be read from standard output. Standard error has a
87
set of functions that correspond to the standard output functions,
88
i.e. readStderr(), readLineStderr() and readyReadStderr().
90
If you use one of the launch() functions the data you pass will be
91
sent to the program's standard input which will be closed once all
92
the data has been written. You should \e not use writeToStdin() or
93
closeStdin() if you use launch(). If you need to send data to the
94
program's standard input after it has started running use start()
97
Both start() and launch() can accept a string list of strings each
98
of which has the format, key=value, where the keys are the names
99
of environment variables.
101
You can test to see if a program is running with isRunning(). The
102
program's process identifier is available from
103
processIdentifier(). If you want to terminate a running program
104
use tryTerminate(), but note that the program may ignore this. If
105
you \e really want to terminate the program, without it having any
106
chance to clean up, you can use kill().
108
As an example, suppose we want to start the \c uic command (a Qt
109
command line tool used with \e{Qt Designer}) and perform some
110
operations on the output (the \c uic outputs the code it generates
111
to standard output by default). Suppose further that we want to
112
run the program on the file "small_dialog.ui" with the command
113
line options "-tr i18n". On the command line we would write:
115
uic -tr i18n small_dialog.ui
118
\quotefile process/process.cpp
120
A code snippet for this with the QProcess class might look like
123
\skipto UicManager::UicManager()
124
\printline UicManager::UicManager()
126
\skipto proc = new QProcess( this );
127
\printline proc = new QProcess( this );
128
\skipto proc->addArgument( "uic" );
129
\printuntil this, SLOT(readFromStdout()) );
130
\skipto if ( !proc->start() ) {
131
\printuntil // error handling
136
\skipto void UicManager::readFromStdout()
137
\printuntil // Bear in mind that the data might be output in chunks.
141
Although you may need quotes for a file named on the command line
142
(e.g. if it contains spaces) you shouldn't use extra quotes for
143
arguments passed to addArgument() or setArguments().
145
The readyReadStdout() signal is emitted when there is new data on
146
standard output. This happens asynchronously: you don't know if
147
more data will arrive later.
149
In the above example you could connect the processExited() signal
150
to the slot UicManager::readFromStdout() instead. If you do so,
151
you will be certain that all the data is available when the slot
152
is called. On the other hand, you must wait until the process has
153
finished before doing any processing.
155
Note that if you are expecting a lot of output from the process,
156
you may hit platform-dependent limits to the pipe buffer size. The
157
solution is to make sure you connect to the output, e.g. the
158
readyReadStdout() and readyReadStderr() signals and read the data
159
as soon as it becomes available.
161
Note: Under Windows there are certain problems starting 16-bit applications
162
and capture their output. Microsoft recommends to use an intermediate
163
application to start 16-bit applications. See Knowledge Base article \link
164
http://support.microsoft.com/default.aspx?scid=KB;en-us;q150956 Q150956
165
\endlink for details on this and example code for an intermediate
172
\enum QProcess::Communication
174
This enum type defines the communication channels connected to the
177
\value Stdin Data can be written to the process's standard input.
179
\value Stdout Data can be read from the process's standard
182
\value Stderr Data can be read from the process's standard error.
184
\value DupStderr Both the process's standard error output \e and
185
its standard output are written to its standard output. (Like
186
Unix's dup2().) This means that nothing is sent to the standard
187
error output. This is especially useful if your application
188
requires that the output on standard output and on standard error
189
must be read in the same order that they are produced. This is a
190
flag, so to activate it you must pass \c{Stdout|Stderr|DupStderr},
191
or \c{Stdin|Stdout|Stderr|DupStderr} if you want to provide input,
192
to the setCommunication() call.
194
\sa setCommunication() communication()
198
Constructs a QProcess object. The \a parent and \a name parameters
199
are passed to the QObject constructor.
201
\sa setArguments() addArgument() start()
203
JProcess::JProcess( QObject *parent, const char *name )
204
: QObject( parent, name ), ioRedirection( FALSE ), notifyOnExit( FALSE ),
205
wroteToStdinConnected( FALSE ),
206
readStdoutCalled( FALSE ), readStderrCalled( FALSE ),
207
comms( Stdin|Stdout|Stderr )
213
Constructs a QProcess with \a arg0 as the command to be executed.
214
The \a parent and \a name parameters are passed to the QObject
217
The process is not started. You must call start() or launch() to
220
\sa setArguments() addArgument() start()
222
JProcess::JProcess( const QString& arg0, QObject *parent, const char *name )
223
: QObject( parent, name ), ioRedirection( FALSE ), notifyOnExit( FALSE ),
224
wroteToStdinConnected( FALSE ),
225
readStdoutCalled( FALSE ), readStderrCalled( FALSE ),
226
comms( Stdin|Stdout|Stderr )
233
Constructs a QProcess with \a args as the arguments of the
234
process. The first element in the list is the command to be
235
executed. The other elements in the list are the arguments to this
236
command. The \a parent and \a name parameters are passed to the
239
The process is not started. You must call start() or launch() to
242
\sa setArguments() addArgument() start()
244
JProcess::JProcess( const QStringList& args, QObject *parent, const char *name )
245
: QObject( parent, name ), ioRedirection( FALSE ), notifyOnExit( FALSE ),
246
wroteToStdinConnected( FALSE ),
247
readStdoutCalled( FALSE ), readStderrCalled( FALSE ),
248
comms( Stdin|Stdout|Stderr )
251
setArguments( args );
256
Returns the list of arguments that are set for the process.
257
Arguments can be specified with the constructor or with the
258
functions setArguments() and addArgument().
260
Note that if you want to iterate over the list, you should iterate
263
QStringList list = myProcess.arguments();
264
QStringList::Iterator it = list.begin();
265
while( it != list.end() ) {
271
\sa setArguments() addArgument()
273
QStringList JProcess::arguments() const
279
Clears the list of arguments that are set for the process.
281
\sa setArguments() addArgument()
283
void JProcess::clearArguments()
289
Sets \a args as the arguments for the process. The first element
290
in the list is the command to be executed. The other elements in
291
the list are the arguments to the command. Any previous arguments
294
QProcess does not perform argument substitutions; for example, if you
295
specify "*" or "$DISPLAY", these values are passed to the process
296
literally. If you want to have the same behavior as the shell
297
provides, you must do the substitutions yourself; i.e. instead of
298
specifying a "*" you must specify the list of all the filenames in
299
the current directory, and instead of "$DISPLAY" you must specify
300
the value of the environment variable \c DISPLAY.
302
Note for Windows users. The standard Windows shells, e.g. \c
303
command.com and \c cmd.exe, do not perform file globbing, i.e.
304
they do not convert a "*" on the command line into a list of files
305
in the current directory. For this reason most Windows
306
applications implement their own file globbing, and as a result of
307
this, specifying an argument of "*" for a Windows application is
308
likely to result in the application performing a file glob and
309
ending up with a list of filenames.
311
\sa arguments() addArgument()
313
void JProcess::setArguments( const QStringList& args )
319
Adds \a arg to the end of the list of arguments.
321
The first element in the list of arguments is the command to be
322
executed; the following elements are the command's arguments.
324
\sa arguments() setArguments()
326
void JProcess::addArgument( const QString& arg )
328
_arguments.append( arg );
333
Returns the working directory that was set with
334
setWorkingDirectory(), or the current directory if none has been
337
\sa setWorkingDirectory() QDir::current()
339
QDir JProcess::workingDirectory() const
345
Sets \a dir as the working directory for processes. This does not
346
affect running processes; only processes that are started
347
afterwards are affected.
349
Setting the working directory is especially useful for processes
350
that try to access files with relative paths.
352
\sa workingDirectory() start()
354
void JProcess::setWorkingDirectory( const QDir& dir )
361
Returns the communication required with the process, i.e. some
362
combination of the \c Communication flags.
364
\sa setCommunication()
366
int JProcess::communication() const
372
Sets \a commFlags as the communication required with the process.
374
\a commFlags is a bitwise OR of the flags defined by the \c
377
The default is \c{Stdin|Stdout|Stderr}.
381
void JProcess::setCommunication( int commFlags )
387
Returns TRUE if the process has exited normally; otherwise returns
388
FALSE. This implies that this function returns FALSE if the
389
process is still running.
391
\sa isRunning() exitStatus() processExited()
393
bool JProcess::normalExit() const
395
// isRunning() has the side effect that it determines the exit status!
403
Returns the exit status of the process or 0 if the process is
404
still running. This function returns immediately and does not wait
405
until the process is finished.
407
If normalExit() is FALSE (e.g. if the program was killed or
408
crashed), this function returns 0, so you should check the return
409
value of normalExit() before relying on this value.
411
\sa normalExit() processExited()
413
int JProcess::exitStatus() const
415
// isRunning() has the side effect that it determines the exit status!
424
Reads the data that the process has written to standard output.
425
When new data is written to standard output, the class emits the
426
signal readyReadStdout().
428
If there is no data to read, this function returns a QByteArray of
429
size 0: it does not wait until there is something to read.
431
\sa readyReadStdout() readLineStdout() readStderr() writeToStdin()
433
QByteArray JProcess::readStdout()
435
if ( readStdoutCalled ) {
438
readStdoutCalled = TRUE;
440
QByteArray buf = bufStdout()->copy();
441
consumeBufStdout( -1 ); // consume everything
443
readStdoutCalled = FALSE;
448
Reads the data that the process has written to standard error.
449
When new data is written to standard error, the class emits the
450
signal readyReadStderr().
452
If there is no data to read, this function returns a QByteArray of
453
size 0: it does not wait until there is something to read.
455
\sa readyReadStderr() readLineStderr() readStdout() writeToStdin()
457
QByteArray JProcess::readStderr()
459
if ( readStderrCalled ) {
462
readStderrCalled = TRUE;
464
QByteArray buf = bufStderr()->copy();
465
consumeBufStderr( -1 ); // consume everything
467
readStderrCalled = FALSE;
472
Reads a line of text from standard output, excluding any trailing
473
newline or carriage return characters, and returns it. Returns
474
QString::null if canReadLineStdout() returns FALSE.
476
\sa canReadLineStdout() readyReadStdout() readStdout() readLineStderr()
478
QString JProcess::readLineStdout()
482
if ( scanNewline( TRUE, &a ) ) {
487
} else if ( canReadLineStdout() ) {
488
s = QString( *bufStdout() );
489
consumeBufStdout( -1 ); // consume everything
495
Reads a line of text from standard error, excluding any trailing
496
newline or carriage return characters and returns it. Returns
497
QString::null if canReadLineStderr() returns FALSE.
499
\sa canReadLineStderr() readyReadStderr() readStderr() readLineStdout()
501
QString JProcess::readLineStderr()
505
if ( scanNewline( FALSE, &a ) ) {
510
} else if ( canReadLineStderr() ) {
511
s = QString( *bufStderr() );
512
consumeBufStderr( -1 ); // consume everything
518
This private function scans for any occurrence of \n or \r\n in the
519
buffer \e buf. It stores the text in the byte array \a store if it is
522
bool JProcess::scanNewline( bool stdOut, QByteArray *store )
529
uint n = buf->size();
531
for ( i=0; i<n; i++ ) {
532
if ( buf->at(i) == '\n' ) {
541
if ( lineLength>0 && buf->at(lineLength-1) == '\r' )
542
lineLength--; // (if there are two \r, let one stay)
543
store->resize( lineLength );
544
memcpy( store->data(), buf->data(), lineLength );
546
consumeBufStdout( i+1 );
548
consumeBufStderr( i+1 );
554
\fn void QProcess::launchFinished()
556
This signal is emitted when the process was started with launch().
557
If the start was successful, this signal is emitted after all the
558
data has been written to standard input. If the start failed, then
559
this signal is emitted immediately.
561
This signal is especially useful if you want to know when you can
562
safely delete the QProcess object when you are not intrested in
563
reading from standard output or standard error.
565
\sa launch() QObject::deleteLater()
569
Runs the process and writes the data \a buf to the process's
570
standard input. If all the data is written to standard input,
571
standard input is closed. The command is searched for in the path
572
for executable programs; you can also use an absolute path in the
575
If \a env is null, then the process is started with the same
576
environment as the starting process. If \a env is non-null, then
577
the values in the string list are interpreted as environment
578
setttings of the form \c {key=value} and the process is started
579
with these environment settings. For convenience, there is a small
580
exception to this rule under Unix: if \a env does not contain any
581
settings for the environment variable \c LD_LIBRARY_PATH, then
582
this variable is inherited from the starting process.
584
Returns TRUE if the process could be started; otherwise returns
587
Note that you should not use the slots writeToStdin() and
588
closeStdin() on processes started with launch(), since the result
589
is not well-defined. If you need these slots, use start() instead.
591
The process may or may not read the \a buf data sent to its
594
You can call this function even when a process that was started
595
with this instance is still running. Be aware that if you do this
596
the standard input of the process that was launched first will be
597
closed, with any pending data being deleted, and the process will
598
be left to run out of your control. Similarly, if the process
599
could not be started the standard input will be closed and the
600
pending data deleted. (On operating systems that have zombie
601
processes, Qt will also wait() on the old process.)
603
The object emits the signal launchFinished() when this function
604
call is finished. If the start was successful, this signal is
605
emitted after all the data has been written to standard input. If
606
the start failed, then this signal is emitted immediately.
608
\sa start() launchFinished();
610
bool JProcess::launch( const QByteArray& buf, QStringList *env )
612
if ( start( env ) ) {
613
if ( !buf.isEmpty() ) {
614
connect( this, SIGNAL(wroteToStdin()),
615
this, SLOT(closeStdinLaunch()) );
619
emit launchFinished();
623
emit launchFinished();
631
The data \a buf is written to standard input with writeToStdin()
632
using the QString::local8Bit() representation of the strings.
634
bool JProcess::launch( const QString& buf, QStringList *env )
636
if ( start( env ) ) {
637
if ( !buf.isEmpty() ) {
638
connect( this, SIGNAL(wroteToStdin()),
639
this, SLOT(closeStdinLaunch()) );
643
emit launchFinished();
647
emit launchFinished();
653
This private slot is used by the launch() functions to close standard input.
655
void JProcess::closeStdinLaunch()
657
disconnect( this, SIGNAL(wroteToStdin()),
658
this, SLOT(closeStdinLaunch()) );
660
emit launchFinished();
665
\fn void QProcess::readyReadStdout()
667
This signal is emitted when the process has written data to
668
standard output. You can read the data with readStdout().
670
Note that this signal is only emitted when there is new data and
671
not when there is old, but unread data. In the slot connected to
672
this signal, you should always read everything that is available
673
at that moment to make sure that you don't lose any data.
675
\sa readStdout() readLineStdout() readyReadStderr()
679
\fn void QProcess::readyReadStderr()
681
This signal is emitted when the process has written data to
682
standard error. You can read the data with readStderr().
684
Note that this signal is only emitted when there is new data and
685
not when there is old, but unread data. In the slot connected to
686
this signal, you should always read everything that is available
687
at that moment to make sure that you don't lose any data.
689
\sa readStderr() readLineStderr() readyReadStdout()
693
\fn void QProcess::processExited()
695
This signal is emitted when the process has exited.
697
\sa isRunning() normalExit() exitStatus() start() launch()
701
\fn void QProcess::wroteToStdin()
703
This signal is emitted if the data sent to standard input (via
704
writeToStdin()) was actually written to the process. This does not
705
imply that the process really read the data, since this class only
706
detects when it was able to write the data to the operating
707
system. But it is now safe to close standard input without losing
710
\sa writeToStdin() closeStdin()
717
The string \a buf is handled as text using the
718
QString::local8Bit() representation.
720
void JProcess::writeToStdin( const QString& buf )
722
QByteArray tmp = buf.local8Bit();
723
tmp.resize( buf.length() );
729
* Under Windows the implementation is not so nice: it is not that easy to
730
* detect when one of the signals should be emitted; therefore there are some
731
* timers that query the information.
732
* To keep it a little efficient, use the timers only when they are needed.
733
* They are needed, if you are interested in the signals. So use
734
* connectNotify() and disconnectNotify() to keep track of your interest.
738
void JProcess::connectNotify( const char * signal )
740
#if defined(QT_QPROCESS_DEBUG)
741
qDebug( "QProcess::connectNotify(): signal %s has been connected", signal );
743
if ( !ioRedirection )
744
if ( qstrcmp( signal, SIGNAL(readyReadStdout()) )==0 ||
745
qstrcmp( signal, SIGNAL(readyReadStderr()) )==0
747
#if defined(QT_QPROCESS_DEBUG)
748
qDebug( "QProcess::connectNotify(): set ioRedirection to TRUE" );
750
setIoRedirection( TRUE );
753
if ( !notifyOnExit && qstrcmp( signal, SIGNAL(processExited()) )==0 ) {
754
#if defined(QT_QPROCESS_DEBUG)
755
qDebug( "QProcess::connectNotify(): set notifyOnExit to TRUE" );
757
setNotifyOnExit( TRUE );
760
if ( !wroteToStdinConnected && qstrcmp( signal, SIGNAL(wroteToStdin()) )==0 ) {
761
#if defined(QT_QPROCESS_DEBUG)
762
qDebug( "QProcess::connectNotify(): set wroteToStdinConnected to TRUE" );
764
setWroteStdinConnected( TRUE );
771
void JProcess::disconnectNotify( const char * )
773
if ( ioRedirection &&
774
receivers( SIGNAL(readyReadStdout()) ) ==0 &&
775
receivers( SIGNAL(readyReadStderr()) ) ==0
777
#if defined(QT_QPROCESS_DEBUG)
778
qDebug( "QProcess::disconnectNotify(): set ioRedirection to FALSE" );
780
setIoRedirection( FALSE );
782
if ( notifyOnExit && receivers( SIGNAL(processExited()) ) == 0 ) {
783
#if defined(QT_QPROCESS_DEBUG)
784
qDebug( "QProcess::disconnectNotify(): set notifyOnExit to FALSE" );
786
setNotifyOnExit( FALSE );
788
if ( wroteToStdinConnected && receivers( SIGNAL(wroteToStdin()) ) == 0 ) {
789
#if defined(QT_QPROCESS_DEBUG)
790
qDebug( "QProcess::disconnectNotify(): set wroteToStdinConnected to FALSE" );
792
setWroteStdinConnected( FALSE );
796
#endif // QT_NO_PROCESS
added
removed
src/tools/openpgp/gpgproc/jprocess.cpp
