1QProcess(3qt)                                                    QProcess(3qt)
2
3
4

NAME

6       QProcess - Used to start external programs and to communicate with them
7

SYNOPSIS

9       #include <qprocess.h>
10
11       Inherits QObject.
12
13   Public Members
14       QProcess ( QObject * parent = 0, const char * name = 0 )
15       QProcess ( const QString & arg0, QObject * parent = 0, const char *
16           name = 0 )
17       QProcess ( const QStringList & args, QObject * parent = 0, const char *
18           name = 0 )
19       ~QProcess ()
20       QStringList arguments () const
21       void clearArguments ()
22       virtual void setArguments ( const QStringList & args )
23       virtual void addArgument ( const QString & arg )
24       QDir workingDirectory () const
25       virtual void setWorkingDirectory ( const QDir & dir )
26       enum Communication { Stdin = 0x01, Stdout = 0x02, Stderr = 0x04,
27           DupStderr = 0x08 }
28       void setCommunication ( int commFlags )
29       int communication () const
30       virtual bool start ( QStringList * env = 0 )
31       virtual bool launch ( const QString & buf, QStringList * env = 0 )
32       virtual bool launch ( const QByteArray & buf, QStringList * env = 0 )
33       bool isRunning () const
34       bool normalExit () const
35       int exitStatus () const
36       virtual QByteArray readStdout ()
37       virtual QByteArray readStderr ()
38       bool canReadLineStdout () const
39       bool canReadLineStderr () const
40       virtual QString readLineStdout ()
41       virtual QString readLineStderr ()
42       PID processIdentifier ()
43
44   Public Slots
45       void tryTerminate () const
46       void kill () const
47       virtual void writeToStdin ( const QByteArray & buf )
48       virtual void writeToStdin ( const QString & buf )
49       virtual void closeStdin ()
50
51   Signals
52       void readyReadStdout ()
53       void readyReadStderr ()
54       void processExited ()
55       void wroteToStdin ()
56       void launchFinished ()
57

DESCRIPTION

59       The QProcess class is used to start external programs and to
60       communicate with them.
61
62       You can write to the started program's standard input, and can read the
63       program's standard output and standard error. You can pass command line
64       arguments to the program either in the constructor or with
65       setArguments() or addArgument(). The program's working directory can be
66       set with setWorkingDirectory(). If you need to set up environment
67       variables pass them to the start() or launch() functions (see below).
68       The processExited() signal is emitted if the program exits. The
69       program's exit status is available from exitStatus(), although you
70       could simply call normalExit() to see if the program terminated
71       normally.
72
73       There are two different ways to start a process. If you just want to
74       run a program, optionally passing data to its standard input at the
75       beginning, use one of the launch() functions. If you want full control
76       of the program's standard input (especially if you don't know all the
77       data you want to send to standard input at the beginning), use the
78       start() function.
79
80       If you use start() you can write to the program's standard input using
81       writeToStdin() and you can close the standard input with closeStdin().
82       The wroteToStdin() signal is emitted if the data sent to standard input
83       has been written. You can read from the program's standard output using
84       readStdout() or readLineStdout(). These functions return an empty
85       QByteArray if there is no data to read. The readyReadStdout() signal is
86       emitted when there is data available to be read from standard output.
87       Standard error has a set of functions that correspond to the standard
88       output functions, i.e. readStderr(), readLineStderr() and
89       readyReadStderr().
90
91       If you use one of the launch() functions the data you pass will be sent
92       to the program's standard input which will be closed once all the data
93       has been written. You should not use writeToStdin() or closeStdin() if
94       you use launch(). If you need to send data to the program's standard
95       input after it has started running use start() instead of launch().
96
97       Both start() and launch() can accept a string list of strings each of
98       which has the format, key=value, where the keys are the names of
99       environment variables.
100
101       You can test to see if a program is running with isRunning(). The
102       program's process identifier is available from processIdentifier(). If
103       you want to terminate a running program use tryTerminate(), but note
104       that the program may ignore this. If you really want to terminate the
105       program, without it having any chance to clean up, you can use kill().
106
107       As an example, suppose we want to start the uic command (a Qt command
108       line tool used with Qt Designer) and perform some operations on the
109       output (the uic outputs the code it generates to standard output by
110       default). Suppose further that we want to run the program on the file
111       "small_dialog.ui" with the command line options "-tr i18n". On the
112       command line we would write:
113
114           uic -tr i18n small_dialog.ui
115
116       A code snippet for this with the QProcess class might look like this:
117
118           UicManager::UicManager()
119           {
120
121               proc = new QProcess( this );
122
123               proc->addArgument( "uic" );
124               proc->addArgument( "-tr" );
125               proc->addArgument( "i18n" );
126               proc->addArgument( "small_dialog.ui" );
127               connect( proc, SIGNAL(readyReadStdout()),
128                       this, SLOT(readFromStdout()) );
129
130               if ( !proc->start() ) {
131                   // error handling
132
133               }
134           }
135
136           void UicManager::readFromStdout()
137           {
138               // Read and process the data.
139               // Bear in mind that the data might be output in chunks.
140
141           }
142
143       Although you may need quotes for a file named on the command line (e.g.
144       if it contains spaces) you shouldn't use extra quotes for arguments
145       passed to addArgument() or setArguments().
146
147       The readyReadStdout() signal is emitted when there is new data on
148       standard output. This happens asynchronously: you don't know if more
149       data will arrive later.
150
151       In the above example you could connect the processExited() signal to
152       the slot UicManager::readFromStdout() instead. If you do so, you will
153       be certain that all the data is available when the slot is called. On
154       the other hand, you must wait until the process has finished before
155       doing any processing.
156
157       Note that if you are expecting a lot of output from the process, you
158       may hit platform-dependent limits to the pipe buffer size. The solution
159       is to make sure you connect to the output, e.g. the readyReadStdout()
160       and readyReadStderr() signals and read the data as soon as it becomes
161       available.
162
163       Please note that QProcess does not emulate a shell. This means that
164       QProcess does not do any expansion of arguments: a '*' is passed as a
165       '*' to the program and is not replaced by all the files, a '$HOME' is
166       also passed literally and is not replaced by the environment variable
167       HOME and the special characters for IO redirection ('>', '|', etc.) are
168       also passed literally and do not have the special meaning as they have
169       in a shell.
170
171       Also note that QProcess does not emulate a terminal. This means that
172       certain programs which need direct terminal control, do not work as
173       expected with QProcess. Such programs include console email programs
174       (like pine and mutt) but also programs which require the user to enter
175       a password (like su and ssh).
176

Notes for Windows users

178       Some Windows commands, for example, dir, are not provided by separate
179       applications, but by the command interpreter. If you attempt to use
180       QProcess to execute these commands directly it won't work. One possible
181       solution is to execute the command interpreter itself (cmd.exe on some
182       Windows systems), and ask the interpreter to execute the desired
183       command.
184
185       Under Windows there are certain problems starting 16-bit applications
186       and capturing their output. Microsoft recommends using an intermediate
187       application to start 16-bit applications.
188
189       See also QSocket, Input/Output and Networking, and Miscellaneous
190       Classes.
191
192   Member Type Documentation

QProcess::Communication

194       This enum type defines the communication channels connected to the
195       process.
196
197       QProcess::Stdin - Data can be written to the process's standard input.
198
199       QProcess::Stdout - Data can be read from the process's standard output.
200
201       QProcess::Stderr - Data can be read from the process's standard error.
202
203       QProcess::DupStderr - Both the process's standard error output and its
204       standard output are written to its standard output. (Like Unix's
205       dup2().) This means that nothing is sent to the standard error output.
206       This is especially useful if your application requires that the output
207       on standard output and on standard error must be read in the same order
208       that they are produced. This is a flag, so to activate it you must pass
209       Stdout|Stderr|DupStderr, or Stdin|Stdout|Stderr|DupStderr if you want
210       to provide input, to the setCommunication() call.
211
212       See also setCommunication() and communication().
213

MEMBER FUNCTION DOCUMENTATION

QProcess::QProcess ( QObject * parent = 0, const char * name = 0 )

216       Constructs a QProcess object. The parent and name parameters are passed
217       to the QObject constructor.
218
219       See also setArguments(), addArgument(), and start().
220

QProcess::QProcess ( const QString & arg0, QObject * parent = 0, const char *

222       name = 0 )
223       Constructs a QProcess with arg0 as the command to be executed. The
224       parent and name parameters are passed to the QObject constructor.
225
226       The process is not started. You must call start() or launch() to start
227       the process.
228
229       See also setArguments(), addArgument(), and start().
230

QProcess::QProcess ( const QStringList & args, QObject * parent = 0, const

232       char * name = 0 )
233       Constructs a QProcess with args as the arguments of the process. The
234       first element in the list is the command to be executed. The other
235       elements in the list are the arguments to this command. The parent and
236       name parameters are passed to the QObject constructor.
237
238       The process is not started. You must call start() or launch() to start
239       the process.
240
241       See also setArguments(), addArgument(), and start().
242

QProcess::~QProcess ()

244       Destroys the instance.
245
246       If the process is running, it is not terminated! The standard input,
247       standard output and standard error of the process are closed.
248
249       You can connect the destroyed() signal to the kill() slot, if you want
250       the process to be terminated automatically when the instance is
251       destroyed.
252
253       See also tryTerminate() and kill().
254

void QProcess::addArgument ( const QString & arg ) [virtual]

256       Adds arg to the end of the list of arguments.
257
258       The first element in the list of arguments is the command to be
259       executed; the following elements are the command's arguments.
260
261       See also arguments() and setArguments().
262
263       Example: process/process.cpp.
264

QStringList QProcess::arguments () const

266       Returns the list of arguments that are set for the process. Arguments
267       can be specified with the constructor or with the functions
268       setArguments() and addArgument().
269
270       Note that if you want to iterate over the list, you should iterate over
271       a copy, e.g.
272
273           QStringList list = myProcess.arguments();
274           QStringList::Iterator it = list.begin();
275           while( it != list.end() ) {
276               myProcessing( *it );
277               ++it;
278           }
279
280       See also setArguments() and addArgument().
281

bool QProcess::canReadLineStderr () const

283       Returns TRUE if it's possible to read an entire line of text from
284       standard error at this time; otherwise returns FALSE.
285
286       See also readLineStderr() and canReadLineStdout().
287

bool QProcess::canReadLineStdout () const

289       Returns TRUE if it's possible to read an entire line of text from
290       standard output at this time; otherwise returns FALSE.
291
292       See also readLineStdout() and canReadLineStderr().
293

void QProcess::clearArguments ()

295       Clears the list of arguments that are set for the process.
296
297       See also setArguments() and addArgument().
298

void QProcess::closeStdin () [virtual slot]

300       Closes the process's standard input.
301
302       This function also deletes any pending data that has not been written
303       to standard input.
304
305       See also wroteToStdin().
306

int QProcess::communication () const

308       Returns the communication required with the process, i.e. some
309       combination of the Communication flags.
310
311       See also setCommunication().
312

int QProcess::exitStatus () const

314       Returns the exit status of the process or 0 if the process is still
315       running. This function returns immediately and does not wait until the
316       process is finished.
317
318       If normalExit() is FALSE (e.g. if the program was killed or crashed),
319       this function returns 0, so you should check the return value of
320       normalExit() before relying on this value.
321
322       See also normalExit() and processExited().
323

bool QProcess::isRunning () const

325       Returns TRUE if the process is running; otherwise returns FALSE.
326
327       See also normalExit(), exitStatus(), and processExited().
328

void QProcess::kill () const [slot]

330       Terminates the process. This is not a safe way to end a process since
331       the process will not be able to do any cleanup. tryTerminate() is
332       safer, but processes can ignore a tryTerminate().
333
334       The nice way to end a process and to be sure that it is finished, is to
335       do something like this:
336
337               process->tryTerminate();
338               QTimer::singleShot( 5000, process, SLOT( kill() ) );
339
340       This tries to terminate the process the nice way. If the process is
341       still running after 5 seconds, it terminates the process the hard way.
342       The timeout should be chosen depending on the time the process needs to
343       do all its cleanup: use a higher value if the process is likely to do a
344       lot of computation or I/O on cleanup.
345
346       The slot returns immediately: it does not wait until the process has
347       finished. When the process terminates, the processExited() signal is
348       emitted.
349
350       See also tryTerminate() and processExited().
351

bool QProcess::launch ( const QByteArray & buf, QStringList * env = 0 )

353       [virtual]
354       Runs the process and writes the data buf to the process's standard
355       input. If all the data is written to standard input, standard input is
356       closed. The command is searched for in the path for executable
357       programs; you can also use an absolute path in the command itself.
358
359       If env is null, then the process is started with the same environment
360       as the starting process. If env is non-null, then the values in the
361       string list are interpreted as environment setttings of the form
362       key=value and the process is started with these environment settings.
363       For convenience, there is a small exception to this rule under Unix: if
364       env does not contain any settings for the environment variable
365       LD_LIBRARY_PATH, then this variable is inherited from the starting
366       process.
367
368       Returns TRUE if the process could be started; otherwise returns FALSE.
369
370       Note that you should not use the slots writeToStdin() and closeStdin()
371       on processes started with launch(), since the result is not well-
372       defined. If you need these slots, use start() instead.
373
374       The process may or may not read the buf data sent to its standard
375       input.
376
377       You can call this function even when a process that was started with
378       this instance is still running. Be aware that if you do this the
379       standard input of the process that was launched first will be closed,
380       with any pending data being deleted, and the process will be left to
381       run out of your control. Similarly, if the process could not be started
382       the standard input will be closed and the pending data deleted. (On
383       operating systems that have zombie processes, Qt will also wait() on
384       the old process.)
385
386       The object emits the signal launchFinished() when this function call is
387       finished. If the start was successful, this signal is emitted after all
388       the data has been written to standard input. If the start failed, then
389       this signal is emitted immediately.
390
391       See also start() and launchFinished().
392

bool QProcess::launch ( const QString & buf, QStringList * env = 0 ) [virtual]

394
395       This is an overloaded member function, provided for convenience. It
396       behaves essentially like the above function.
397
398       The data buf is written to standard input with writeToStdin() using the
399       QString::local8Bit() representation of the strings.
400

void QProcess::launchFinished () [signal]

402       This signal is emitted when the process was started with launch(). If
403       the start was successful, this signal is emitted after all the data has
404       been written to standard input. If the start failed, then this signal
405       is emitted immediately.
406
407       This signal is especially useful if you want to know when you can
408       safely delete the QProcess object when you are not interested in
409       reading from standard output or standard error.
410
411       See also launch() and QObject::deleteLater().
412

bool QProcess::normalExit () const

414       Returns TRUE if the process has exited normally; otherwise returns
415       FALSE. This implies that this function returns FALSE if the process is
416       still running.
417
418       See also isRunning(), exitStatus(), and processExited().
419

void QProcess::processExited () [signal]

421       This signal is emitted when the process has exited.
422
423       See also isRunning(), normalExit(), exitStatus(), start(), and
424       launch().
425
426       Example: process/process.cpp.
427

PID QProcess::processIdentifier ()

429       Returns platform dependent information about the process. This can be
430       used together with platform specific system calls.
431
432       Under Unix the return value is the PID of the process, or -1 if no
433       process belongs to this object.
434
435       Under Windows it is a pointer to the PROCESS_INFORMATION struct, or 0
436       if no process is belongs to this object.
437
438       Use of this function's return value is likely to be non-portable.
439

QString QProcess::readLineStderr () [virtual]

441       Reads a line of text from standard error, excluding any trailing
442       newline or carriage return characters and returns it. Returns
443       QString::null if canReadLineStderr() returns FALSE.
444
445       By default, the text is interpreted to be in Latin-1 encoding. If you
446       need other codecs, you can set a different codec with
447       QTextCodec::setCodecForCStrings().
448
449       See also canReadLineStderr(), readyReadStderr(), readStderr(), and
450       readLineStdout().
451

QString QProcess::readLineStdout () [virtual]

453       Reads a line of text from standard output, excluding any trailing
454       newline or carriage return characters, and returns it. Returns
455       QString::null if canReadLineStdout() returns FALSE.
456
457       By default, the text is interpreted to be in Latin-1 encoding. If you
458       need other codecs, you can set a different codec with
459       QTextCodec::setCodecForCStrings().
460
461       See also canReadLineStdout(), readyReadStdout(), readStdout(), and
462       readLineStderr().
463

QByteArray QProcess::readStderr () [virtual]

465       Reads the data that the process has written to standard error. When new
466       data is written to standard error, the class emits the signal
467       readyReadStderr().
468
469       If there is no data to read, this function returns a QByteArray of size
470       0: it does not wait until there is something to read.
471
472       See also readyReadStderr(), readLineStderr(), readStdout(), and
473       writeToStdin().
474

QByteArray QProcess::readStdout () [virtual]

476       Reads the data that the process has written to standard output. When
477       new data is written to standard output, the class emits the signal
478       readyReadStdout().
479
480       If there is no data to read, this function returns a QByteArray of size
481       0: it does not wait until there is something to read.
482
483       See also readyReadStdout(), readLineStdout(), readStderr(), and
484       writeToStdin().
485
486       Example: process/process.cpp.
487

void QProcess::readyReadStderr () [signal]

489       This signal is emitted when the process has written data to standard
490       error. You can read the data with readStderr().
491
492       Note that this signal is only emitted when there is new data and not
493       when there is old, but unread data. In the slot connected to this
494       signal, you should always read everything that is available at that
495       moment to make sure that you don't lose any data.
496
497       See also readStderr(), readLineStderr(), and readyReadStdout().
498

void QProcess::readyReadStdout () [signal]

500       This signal is emitted when the process has written data to standard
501       output. You can read the data with readStdout().
502
503       Note that this signal is only emitted when there is new data and not
504       when there is old, but unread data. In the slot connected to this
505       signal, you should always read everything that is available at that
506       moment to make sure that you don't lose any data.
507
508       See also readStdout(), readLineStdout(), and readyReadStderr().
509
510       Example: process/process.cpp.
511

void QProcess::setArguments ( const QStringList & args ) [virtual]

513       Sets args as the arguments for the process. The first element in the
514       list is the command to be executed. The other elements in the list are
515       the arguments to the command. Any previous arguments are deleted.
516
517       QProcess does not perform argument substitutions; for example, if you
518       specify "*" or "$DISPLAY", these values are passed to the process
519       literally. If you want to have the same behavior as the shell provides,
520       you must do the substitutions yourself; i.e. instead of specifying a
521       "*" you must specify the list of all the filenames in the current
522       directory, and instead of "$DISPLAY" you must specify the value of the
523       environment variable DISPLAY.
524
525       Note for Windows users. The standard Windows shells, e.g. command.com
526       and cmd.exe, do not perform file globbing, i.e. they do not convert a
527       "*" on the command line into a list of files in the current directory.
528       For this reason most Windows applications implement their own file
529       globbing, and as a result of this, specifying an argument of "*" for a
530       Windows application is likely to result in the application performing a
531       file glob and ending up with a list of filenames.
532
533       See also arguments() and addArgument().
534

void QProcess::setCommunication ( int commFlags )

536       Sets commFlags as the communication required with the process.
537
538       commFlags is a bitwise OR of the flags defined by the Communication
539       enum.
540
541       The default is Stdin|Stdout|Stderr.
542
543       See also communication().
544

void QProcess::setWorkingDirectory ( const QDir & dir ) [virtual]

546       Sets dir as the working directory for processes. This does not affect
547       running processes; only processes that are started afterwards are
548       affected.
549
550       Setting the working directory is especially useful for processes that
551       try to access files with relative paths.
552
553       See also workingDirectory() and start().
554

bool QProcess::start ( QStringList * env = 0 ) [virtual]

556       Tries to run a process for the command and arguments that were
557       specified with setArguments(), addArgument() or that were specified in
558       the constructor. The command is searched for in the path for executable
559       programs; you can also use an absolute path in the command itself.
560
561       If env is null, then the process is started with the same environment
562       as the starting process. If env is non-null, then the values in the
563       stringlist are interpreted as environment setttings of the form
564       key=value and the process is started in these environment settings. For
565       convenience, there is a small exception to this rule: under Unix, if
566       env does not contain any settings for the environment variable
567       LD_LIBRARY_PATH, then this variable is inherited from the starting
568       process; under Windows the same applies for the environment variable
569       PATH.
570
571       Returns TRUE if the process could be started; otherwise returns FALSE.
572
573       You can write data to the process's standard input with writeToStdin().
574       You can close standard input with closeStdin() and you can terminate
575       the process with tryTerminate(), or with kill().
576
577       You can call this function even if you've used this instance to create
578       a another process which is still running. In such cases, QProcess
579       closes the old process's standard input and deletes pending data, i.e.,
580       you lose all control over the old process, but the old process is not
581       terminated. This applies also if the process could not be started. (On
582       operating systems that have zombie processes, Qt will also wait() on
583       the old process.)
584
585       See also launch() and closeStdin().
586
587       Example: process/process.cpp.
588

void QProcess::tryTerminate () const [slot]

590       Asks the process to terminate. Processes can ignore this if they wish.
591       If you want to be certain that the process really terminates, you can
592       use kill() instead.
593
594       The slot returns immediately: it does not wait until the process has
595       finished. When the process terminates, the processExited() signal is
596       emitted.
597
598       See also kill() and processExited().
599

QDir QProcess::workingDirectory () const

601       Returns the working directory that was set with setWorkingDirectory(),
602       or the current directory if none has been explicitly set.
603
604       See also setWorkingDirectory() and QDir::current().
605

void QProcess::writeToStdin ( const QByteArray & buf ) [virtual slot]

607       Writes the data buf to the process's standard input. The process may or
608       may not read this data.
609
610       This function always returns immediately. The data you pass to
611       writeToStdin() is copied into an internal memory buffer in QProcess,
612       and when control goes back to the event loop, QProcess will starting
613       transferring data from this buffer to the running process. Sometimes
614       the data will be transferred in several payloads, depending on how much
615       data is read at a time by the process itself. When QProcess has
616       transferred all the data from its memory buffer to the running process,
617       it emits wroteToStdin().
618
619       Note that some operating systems use a buffer to transfer the data. As
620       a result, wroteToStdin() may be emitted before the running process has
621       actually read all the data.
622
623       See also wroteToStdin(), closeStdin(), readStdout(), and readStderr().
624

void QProcess::writeToStdin ( const QString & buf ) [virtual slot]

626       This is an overloaded member function, provided for convenience. It
627       behaves essentially like the above function.
628
629       The string buf is handled as text using the QString::local8Bit()
630       representation.
631

void QProcess::wroteToStdin () [signal]

633       This signal is emitted if the data sent to standard input (via
634       writeToStdin()) was actually written to the process. This does not
635       imply that the process really read the data, since this class only
636       detects when it was able to write the data to the operating system. But
637       it is now safe to close standard input without losing pending data.
638
639       See also writeToStdin() and closeStdin().
640
641

SEE ALSO

643       http://doc.trolltech.com/qprocess.html
644       http://www.trolltech.com/faq/tech.html
645
647       Copyright 1992-2007 Trolltech ASA, http://www.trolltech.com.  See the
648       license file included in the distribution for a complete license
649       statement.
650

AUTHOR

652       Generated automatically from the source code.
653

BUGS

655       If you find a bug in Qt, please report it as described in
656       http://doc.trolltech.com/bughowto.html.  Good bug reports help us to
657       help you. Thank you.
658
659       The definitive Qt documentation is provided in HTML format; it is
660       located at $QTDIR/doc/html and can be read using Qt Assistant or with a
661       web browser. This man page is provided as a convenience for those users
662       who prefer man pages, although this format is not officially supported
663       by Trolltech.
664
665       If you find errors in this manual page, please report them to qt-
666       bugs@trolltech.com.  Please include the name of the manual page
667       (qprocess.3qt) and the Qt version (3.3.8).
668
669
670
671Trolltech AS                    2 February 2007                  QProcess(3qt)
Impressum