1 /****************************************************************************

     2 **

     3 ** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies).

     4 ** All rights reserved.

     5 ** Contact: Nokia Corporation (qt-info@nokia.com)

     6 **

     7 ** This file is part of the Qt3Support module of the Qt Toolkit.

     8 **

     9 ** $QT_BEGIN_LICENSE:LGPL$

    10 ** No Commercial Usage

    11 ** This file contains pre-release code and may not be distributed.

    12 ** You may use this file in accordance with the terms and conditions

    13 ** contained in the Technology Preview License Agreement accompanying

    14 ** this package.

    15 **

    16 ** GNU Lesser General Public License Usage

    17 ** Alternatively, this file may be used under the terms of the GNU Lesser

    18 ** General Public License version 2.1 as published by the Free Software

    19 ** Foundation and appearing in the file LICENSE.LGPL included in the

    20 ** packaging of this file.  Please review the following information to

    21 ** ensure the GNU Lesser General Public License version 2.1 requirements

    22 ** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html.

    23 **

    24 ** In addition, as a special exception, Nokia gives you certain additional

    25 ** rights.  These rights are described in the Nokia Qt LGPL Exception

    26 ** version 1.1, included in the file LGPL_EXCEPTION.txt in this package.

    27 **

    28 ** If you have questions regarding the use of this file, please contact

    29 ** Nokia at qt-info@nokia.com.

    30 **

    31 **

    32 **

    33 **

    34 **

    35 **

    36 **

    37 **

    38 ** $QT_END_LICENSE$

    39 **

    40 ****************************************************************************/

    41 

    42 #include "q3process.h"

    43 

    44 #ifndef QT_NO_PROCESS

    45 

    46 #include "qapplication.h"

    47 #include "private/q3membuf_p.h"

    48 

    49 #include <stdio.h>

    50 #include <stdlib.h>

    51 

    52 QT_BEGIN_NAMESPACE

    53 

    54 //#define QT_Q3PROCESS_DEBUG

    55 

    56 

    57 /*!

    58     \class Q3Process

    59 

    60     \brief The Q3Process class is used to start external programs and

    61     to communicate with them.

    62 

    63     \compat

    64 

    65     You can write to the started program's standard input, and can

    66     read the program's standard output and standard error. You can

    67     pass command line arguments to the program either in the

    68     constructor or with setArguments() or addArgument(). The program's

    69     working directory can be set with setWorkingDirectory(). If you

    70     need to set up environment variables pass them to the start() or

    71     launch() functions (see below). The processExited() signal is

    72     emitted if the program exits. The program's exit status is

    73     available from exitStatus(), although you could simply call

    74     normalExit() to see if the program terminated normally.

    75 

    76     There are two different ways to start a process. If you just want

    77     to run a program, optionally passing data to its standard input at

    78     the beginning, use one of the launch() functions. If you want full

    79     control of the program's standard input (especially if you don't

    80     know all the data you want to send to standard input at the

    81     beginning), use the start() function.

    82 

    83     If you use start() you can write to the program's standard input

    84     using writeToStdin() and you can close the standard input with

    85     closeStdin(). The wroteToStdin() signal is emitted if the data

    86     sent to standard input has been written. You can read from the

    87     program's standard output using readStdout() or readLineStdout().

    88     These functions return an empty QByteArray if there is no data to

    89     read. The readyReadStdout() signal is emitted when there is data

    90     available to be read from standard output. Standard error has a

    91     set of functions that correspond to the standard output functions,

    92     i.e. readStderr(), readLineStderr() and readyReadStderr().

    93 

    94     If you use one of the launch() functions the data you pass will be

    95     sent to the program's standard input which will be closed once all

    96     the data has been written. You should \e not use writeToStdin() or

    97     closeStdin() if you use launch(). If you need to send data to the

    98     program's standard input after it has started running use start()

    99     instead of launch().

   100 

   101     Both start() and launch() can accept a string list of strings each

   102     of which has the format, key=value, where the keys are the names

   103     of environment variables.

   104 

   105     You can test to see if a program is running with isRunning(). The

   106     program's process identifier is available from

   107     processIdentifier(). If you want to terminate a running program

   108     use tryTerminate(), but note that the program may ignore this. If

   109     you \e really want to terminate the program, without it having any

   110     chance to clean up, you can use kill().

   111 

   112     Although you may need quotes for a file named on the command line

   113     (e.g. if it contains spaces) you shouldn't use extra quotes for

   114     arguments passed to addArgument() or setArguments().

   115 

   116     The readyReadStdout() signal is emitted when there is new data on

   117     standard output. This happens asynchronously: you don't know if

   118     more data will arrive later.

   119 

   120     In the above example you could connect the processExited() signal

   121     to the slot UicManager::readFromStdout() instead. If you do so,

   122     you will be certain that all the data is available when the slot

   123     is called. On the other hand, you must wait until the process has

   124     finished before doing any processing.

   125 

   126     Note that if you are expecting a lot of output from the process,

   127     you may hit platform-dependent limits to the pipe buffer size. The

   128     solution is to make sure you connect to the output, e.g. the

   129     readyReadStdout() and readyReadStderr() signals and read the data

   130     as soon as it becomes available.

   131 

   132     Please note that Q3Process does not emulate a shell. This means that

   133     Q3Process does not do any expansion of arguments: a '*' is passed as a '*'

   134     to the program and is \e not replaced by all the files, a '$HOME' is also

   135     passed literally and is \e not replaced by the environment variable HOME

   136     and the special characters for IO redirection ('>', '|', etc.) are also

   137     passed literally and do \e not have the special meaning as they have in a

   138     shell.

   139 

   140     Also note that Q3Process does not emulate a terminal. This means that

   141     certain programs which need direct terminal control, do not work as

   142     expected with Q3Process. Such programs include console email programs (like

   143     pine and mutt) but also programs which require the user to enter a password

   144     (like su and ssh).

   145 

   146     \section1 Notes for Windows users

   147 

   148     Some Windows commands, for example, \c dir, are not provided by

   149     separate applications, but by the command interpreter.

   150     If you attempt to use Q3Process to execute these commands directly

   151     it won't work. One possible solution is to execute the command

   152     interpreter itself (\c cmd.exe on some Windows systems), and ask

   153     the interpreter to execute the desired command.

   154 

   155     Under Windows there are certain problems starting 16-bit applications

   156     and capturing their output. Microsoft recommends using an intermediate

   157     application to start 16-bit applications.

   158 

   159     \sa Q3Socket

   160 */

   161 

   162 /*!

   163     \enum Q3Process::Communication

   164 

   165     This enum type defines the communication channels connected to the

   166     process.

   167 

   168     \value Stdin  Data can be written to the process's standard input.

   169 

   170     \value Stdout  Data can be read from the process's standard

   171     output.

   172 

   173     \value Stderr  Data can be read from the process's standard error.

   174 

   175     \value DupStderr  Both the process's standard error output \e and

   176     its standard output are written to its standard output. (Like

   177     Unix's dup2().) This means that nothing is sent to the standard

   178     error output. This is especially useful if your application

   179     requires that the output on standard output and on standard error

   180     must be read in the same order that they are produced. This is a

   181     flag, so to activate it you must pass \c{Stdout|Stderr|DupStderr},

   182     or \c{Stdin|Stdout|Stderr|DupStderr} if you want to provide input,

   183     to the setCommunication() call.

   184 

   185     \sa setCommunication() communication()

   186 */

   187 

   188 /*!

   189     Constructs a Q3Process object. The \a parent and \a name parameters

   190     are passed to the QObject constructor.

   191 

   192     \sa setArguments() addArgument() start()

   193 */

   194 Q3Process::Q3Process( QObject *parent, const char *name )

   195     : QObject( parent, name ), ioRedirection( false ), notifyOnExit( false ),

   196     wroteToStdinConnected( false ),

   197     readStdoutCalled( false ), readStderrCalled( false ),

   198     comms( Stdin|Stdout|Stderr )

   199 {

   200     init();

   201 }

   202 

   203 /*!

   204     Constructs a Q3Process with \a arg0 as the command to be executed.

   205     The \a parent and \a name parameters are passed to the QObject

   206     constructor.

   207 

   208     The process is not started. You must call start() or launch() to

   209     start the process.

   210 

   211     \sa setArguments() addArgument() start()

   212 */

   213 Q3Process::Q3Process( const QString& arg0, QObject *parent, const char *name )

   214     : QObject( parent, name ), ioRedirection( false ), notifyOnExit( false ),

   215     wroteToStdinConnected( false ),

   216     readStdoutCalled( false ), readStderrCalled( false ),

   217     comms( Stdin|Stdout|Stderr )

   218 {

   219     init();

   220     addArgument( arg0 );

   221 }

   222 

   223 /*!

   224     Constructs a Q3Process with \a args as the arguments of the

   225     process. The first element in the list is the command to be

   226     executed. The other elements in the list are the arguments to this

   227     command. The \a parent and \a name parameters are passed to the

   228     QObject constructor.

   229 

   230     The process is not started. You must call start() or launch() to

   231     start the process.

   232 

   233     \sa setArguments() addArgument() start()

   234 */

   235 Q3Process::Q3Process( const QStringList& args, QObject *parent, const char *name )

   236     : QObject( parent, name ), ioRedirection( false ), notifyOnExit( false ),

   237     wroteToStdinConnected( false ),

   238     readStdoutCalled( false ), readStderrCalled( false ),

   239     comms( Stdin|Stdout|Stderr )

   240 {

   241     init();

   242     setArguments( args );

   243 }

   244 

   245 /*!

   246     \fn Q3Process::~Q3Process()

   247 

   248     Destroys the instance.

   249 

   250     If the process is running, it is <b>not</b> terminated! The

   251     standard input, standard output and standard error of the process

   252     are closed.

   253 

   254     You can connect the destroyed() signal to the kill() slot, if you

   255     want the process to be terminated automatically when the instance

   256     is destroyed.

   257 

   258     \sa tryTerminate() kill()

   259 */

   260 

   261 /*!

   262     Returns the list of arguments that are set for the process.

   263     Arguments can be specified with the constructor or with the

   264     functions setArguments() and addArgument().

   265 

   266     Note that if you want to iterate over the list, you should iterate

   267     over a copy, e.g.

   268     \snippet doc/src/snippets/code/src_qt3support_other_q3process.cpp 0

   269 

   270     \sa setArguments() addArgument()

   271 */

   272 QStringList Q3Process::arguments() const

   273 {

   274     return _arguments;

   275 }

   276 

   277 /*!

   278     Clears the list of arguments that are set for the process.

   279 

   280     \sa setArguments() addArgument()

   281 */

   282 void Q3Process::clearArguments()

   283 {

   284     _arguments.clear();

   285 }

   286 

   287 /*!

   288     Sets \a args as the arguments for the process. The first element

   289     in the list is the command to be executed. The other elements in

   290     the list are the arguments to the command. Any previous arguments

   291     are deleted.

   292 

   293     Q3Process does not perform argument substitutions; for example, if you

   294     specify "*" or "$DISPLAY", these values are passed to the process

   295     literally. If you want to have the same behavior as the shell

   296     provides, you must do the substitutions yourself; i.e. instead of

   297     specifying a "*" you must specify the list of all the filenames in

   298     the current directory, and instead of "$DISPLAY" you must specify

   299     the value of the environment variable \c DISPLAY.

   300 

   301     Note for Windows users. The standard Windows shells, e.g. \c

   302     command.com and \c cmd.exe, do not perform file globbing, i.e.

   303     they do not convert a "*" on the command line into a list of files

   304     in the current directory. For this reason most Windows

   305     applications implement their own file globbing, and as a result of

   306     this, specifying an argument of "*" for a Windows application is

   307     likely to result in the application performing a file glob and

   308     ending up with a list of filenames.

   309 

   310     \sa arguments() addArgument()

   311 */

   312 void Q3Process::setArguments( const QStringList& args )

   313 {

   314     _arguments = args;

   315 }

   316 

   317 /*!

   318     Adds \a arg to the end of the list of arguments.

   319 

   320     The first element in the list of arguments is the command to be

   321     executed; the following elements are the command's arguments.

   322 

   323     \sa arguments() setArguments()

   324 */

   325 void Q3Process::addArgument( const QString& arg )

   326 {

   327     _arguments.append( arg );

   328 }

   329 

   330 #ifndef QT_NO_DIR

   331 /*!

   332     Returns the working directory that was set with

   333     setWorkingDirectory(), or the current directory if none has been

   334     explicitly set.

   335 

   336     \sa setWorkingDirectory() QDir::current()

   337 */

   338 QDir Q3Process::workingDirectory() const

   339 {

   340     return workingDir;

   341 }

   342 

   343 /*!

   344     Sets \a dir as the working directory for processes. This does not

   345     affect running processes; only processes that are started

   346     afterwards are affected.

   347 

   348     Setting the working directory is especially useful for processes

   349     that try to access files with relative paths.

   350 

   351     \sa workingDirectory() start()

   352 */

   353 void Q3Process::setWorkingDirectory( const QDir& dir )

   354 {

   355     workingDir = dir;

   356 }

   357 #endif //QT_NO_DIR

   358 

   359 /*!

   360     Returns the communication required with the process, i.e. some

   361     combination of the \c Communication flags.

   362 

   363     \sa setCommunication()

   364 */

   365 int Q3Process::communication() const

   366 {

   367     return comms;

   368 }

   369 

   370 /*!

   371     Sets \a commFlags as the communication required with the process.

   372 

   373     \a commFlags is a bitwise OR of the flags defined by the \c

   374     Communication enum.

   375 

   376     The default is \c{Stdin|Stdout|Stderr}.

   377 

   378     \sa communication()

   379 */

   380 void Q3Process::setCommunication( int commFlags )

   381 {

   382     comms = commFlags;

   383 }

   384 

   385 /*!

   386     Returns true if the process has exited normally; otherwise returns

   387     false. This implies that this function returns false if the

   388     process is still running.

   389 

   390     \sa isRunning() exitStatus() processExited()

   391 */

   392 bool Q3Process::normalExit() const

   393 {

   394     // isRunning() has the side effect that it determines the exit status!

   395     if ( isRunning() )

   396 	return false;

   397     else

   398 	return exitNormal;

   399 }

   400 

   401 /*!

   402     Returns the exit status of the process or 0 if the process is

   403     still running. This function returns immediately and does not wait

   404     until the process is finished.

   405 

   406     If normalExit() is false (e.g. if the program was killed or

   407     crashed), this function returns 0, so you should check the return

   408     value of normalExit() before relying on this value.

   409 

   410     \sa normalExit() processExited()

   411 */

   412 int Q3Process::exitStatus() const

   413 {

   414     // isRunning() has the side effect that it determines the exit status!

   415     if ( isRunning() )

   416 	return 0;

   417     else

   418 	return exitStat;

   419 }

   420 

   421 

   422 /*!

   423     Reads the data that the process has written to standard output.

   424     When new data is written to standard output, the class emits the

   425     signal readyReadStdout().

   426 

   427     If there is no data to read, this function returns a QByteArray of

   428     size 0: it does not wait until there is something to read.

   429 

   430     \sa readyReadStdout() readLineStdout() readStderr() writeToStdin()

   431 */

   432 QByteArray Q3Process::readStdout()

   433 {

   434     if ( readStdoutCalled ) {

   435 	return QByteArray();

   436     }

   437     readStdoutCalled = true;

   438     Q3Membuf *buf = membufStdout();

   439     readStdoutCalled = false;

   440 

   441     return buf->readAll();

   442 }

   443 

   444 /*!

   445     Reads the data that the process has written to standard error.

   446     When new data is written to standard error, the class emits the

   447     signal readyReadStderr().

   448 

   449     If there is no data to read, this function returns a QByteArray of

   450     size 0: it does not wait until there is something to read.

   451 

   452     \sa readyReadStderr() readLineStderr() readStdout() writeToStdin()

   453 */

   454 QByteArray Q3Process::readStderr()

   455 {

   456     if ( readStderrCalled ) {

   457 	return QByteArray();

   458     }

   459     readStderrCalled = true;

   460     Q3Membuf *buf = membufStderr();

   461     readStderrCalled = false;

   462 

   463     return buf->readAll();

   464 }

   465 

   466 /*!

   467     Reads a line of text from standard output, excluding any trailing

   468     newline or carriage return characters, and returns it. Returns

   469     an empty string if canReadLineStdout() returns false.

   470 

   471     By default, the text is interpreted to be in Latin-1 encoding. If you need

   472     other codecs, you can set a different codec with

   473     QTextCodec::setCodecForCStrings().

   474 

   475     \sa canReadLineStdout() readyReadStdout() readStdout() readLineStderr()

   476 */

   477 QString Q3Process::readLineStdout()

   478 {

   479     QByteArray a( 256 );

   480     Q3Membuf *buf = membufStdout();

   481     if ( !buf->scanNewline( &a ) ) {

   482       if ( !canReadLineStdout() )

   483 	return QString();

   484 

   485       if ( !buf->scanNewline( &a ) )

   486 	return QLatin1String(buf->readAll());

   487     }

   488 

   489     uint size = a.size();

   490     buf->consumeBytes( size, 0 );

   491 

   492     // get rid of terminating \n or \r\n

   493     if ( size>0 && a.at( size - 1 ) == '\n' ) {

   494       if ( size>1 && a.at( size - 2 ) == '\r' )

   495 	a.chop(2);

   496       else

   497 	a.chop(1);

   498     }

   499     return QString(QString::fromLatin1(a.constData()));

   500 }

   501 

   502 /*!

   503     Reads a line of text from standard error, excluding any trailing

   504     newline or carriage return characters and returns it. Returns

   505     an empty string if canReadLineStderr() returns false.

   506 

   507     By default, the text is interpreted to be in Latin-1 encoding. If you need

   508     other codecs, you can set a different codec with

   509     QTextCodec::setCodecForCStrings().

   510 

   511     \sa canReadLineStderr() readyReadStderr() readStderr() readLineStdout()

   512 */

   513 QString Q3Process::readLineStderr()

   514 {

   515     QByteArray a( 256 );

   516     Q3Membuf *buf = membufStderr();

   517     if ( !buf->scanNewline( &a ) ) {

   518       if ( !canReadLineStderr() )

   519 	return QString();

   520 

   521       if ( !buf->scanNewline( &a ) )

   522 	return QString( QString::fromLatin1( buf->readAll().constData() ) );

   523     }

   524 

   525     uint size = a.size();

   526     buf->consumeBytes( size, 0 );

   527 

   528     // get rid of terminating \n or \r\n

   529     if ( size>0 && a.at( size - 1 ) == '\n' ) {

   530       if ( size>1 && a.at( size - 2 ) == '\r' )

   531 	a.chop(2);

   532       else

   533 	a.chop(1);

   534     }

   535     return QString( QString::fromLatin1( a.constData() ) );

   536 }

   537 

   538 /*!

   539     \fn bool Q3Process::start( QStringList *env )

   540 

   541     Tries to run a process for the command and arguments that were

   542     specified with setArguments(), addArgument() or that were

   543     specified in the constructor. The command is searched for in the

   544     path for executable programs; you can also use an absolute path in

   545     the command itself.

   546 

   547     If \a env is null, then the process is started with the same

   548     environment as the starting process. If \a env is non-null, then

   549     the values in the stringlist are interpreted as environment

   550     setttings of the form \c {key=value} and the process is started in

   551     these environment settings. For convenience, there is a small

   552     exception to this rule: under Unix, if \a env does not contain any

   553     settings for the environment variable \c LD_LIBRARY_PATH, then

   554     this variable is inherited from the starting process; under

   555     Windows the same applies for the environment variable \c PATH.

   556 

   557     Returns true if the process could be started; otherwise returns

   558     false.

   559 

   560     You can write data to the process's standard input with

   561     writeToStdin(). You can close standard input with closeStdin() and

   562     you can terminate the process with tryTerminate(), or with kill().

   563 

   564     You can call this function even if you've used this instance to

   565     create a another process which is still running. In such cases,

   566     Q3Process closes the old process's standard input and deletes

   567     pending data, i.e., you lose all control over the old process, but

   568     the old process is not terminated. This applies also if the

   569     process could not be started. (On operating systems that have

   570     zombie processes, Qt will also wait() on the old process.)

   571 

   572     \sa launch() closeStdin()

   573 */

   574 

   575 /*!

   576     \fn void Q3Process::tryTerminate() const

   577 

   578     Asks the process to terminate. Processes can ignore this if they

   579     wish. If you want to be certain that the process really

   580     terminates, you can use kill() instead.

   581 

   582     The slot returns immediately: it does not wait until the process

   583     has finished. When the process terminates, the processExited()

   584     signal is emitted.

   585 

   586     \sa kill() processExited()

   587 */

   588 

   589 /*!

   590     \fn void Q3Process::kill() const

   591 

   592     Terminates the process. This is not a safe way to end a process

   593     since the process will not be able to do any cleanup.

   594     tryTerminate() is safer, but processes can ignore a

   595     tryTerminate().

   596 

   597     The nice way to end a process and to be sure that it is finished,

   598     is to do something like this:

   599     \snippet doc/src/snippets/code/src_qt3support_other_q3process_unix.cpp 0

   600 

   601     This tries to terminate the process the nice way. If the process

   602     is still running after 5 seconds, it terminates the process the

   603     hard way. The timeout should be chosen depending on the time the

   604     process needs to do all its cleanup: use a higher value if the

   605     process is likely to do a lot of computation or I/O on cleanup.

   606 

   607     The slot returns immediately: it does not wait until the process

   608     has finished. When the process terminates, the processExited()

   609     signal is emitted.

   610 

   611     \sa tryTerminate() processExited()

   612 */

   613 

   614 /*!

   615     \fn bool Q3Process::isRunning() const

   616 

   617     Returns true if the process is running; otherwise returns false.

   618 

   619     \sa normalExit() exitStatus() processExited()

   620 */

   621 

   622 /*!

   623     \fn bool Q3Process::canReadLineStdout() const

   624 

   625     Returns true if it's possible to read an entire line of text from

   626     standard output at this time; otherwise returns false.

   627 

   628     \sa readLineStdout() canReadLineStderr()

   629 */

   630 

   631 /*!

   632     \fn bool Q3Process::canReadLineStderr() const

   633 

   634     Returns true if it's possible to read an entire line of text from

   635     standard error at this time; otherwise returns false.

   636 

   637     \sa readLineStderr() canReadLineStdout()

   638 */

   639 

   640 /*!

   641     \fn void Q3Process::writeToStdin( const QByteArray& buf )

   642 

   643     Writes the data \a buf to the process's standard input. The

   644     process may or may not read this data.

   645 

   646     This function returns immediately; the Q3Process class might write

   647     the data at a later point (you must enter the event loop for this

   648     to occur). When all the data is written to the process, the signal

   649     wroteToStdin() is emitted. This does not mean that the process

   650     actually read the data, since this class only detects when it was

   651     able to write the data to the operating system.

   652 

   653     \sa wroteToStdin() closeStdin() readStdout() readStderr()

   654 */

   655 

   656 /*!

   657     \fn void Q3Process::closeStdin()

   658 

   659     Closes the process's standard input.

   660 

   661     This function also deletes any pending data that has not been

   662     written to standard input.

   663 

   664     \sa wroteToStdin()

   665 */

   666 

   667 /*!

   668     \fn Q3Process::PID Q3Process::processIdentifier()

   669 

   670     Returns platform dependent information about the process. This can

   671     be used together with platform specific system calls.

   672 

   673     Under Unix the return value is the PID of the process, or -1 if no

   674     process belongs to this object.

   675 

   676     Under Windows it is a pointer to the \c PROCESS_INFORMATION

   677     struct, or 0 if no process is belongs to this object.

   678 

   679     Use of this function's return value is likely to be non-portable.

   680 */

   681 

   682 /*!

   683     \fn void Q3Process::launchFinished()

   684 

   685     This signal is emitted when the process was started with launch().

   686     If the start was successful, this signal is emitted after all the

   687     data has been written to standard input. If the start failed, then

   688     this signal is emitted immediately.

   689 

   690     This signal is especially useful if you want to know when you can

   691     safely delete the Q3Process object when you are not interested in

   692     reading from standard output or standard error.

   693 

   694     \sa launch() QObject::deleteLater()

   695 */

   696 

   697 /*!

   698     Runs the process and writes the data \a buf to the process's

   699     standard input. If all the data is written to standard input,

   700     standard input is closed. The command is searched for in the path

   701     for executable programs; you can also use an absolute path in the

   702     command itself.

   703 

   704     If \a env is null, then the process is started with the same

   705     environment as the starting process. If \a env is non-null, then

   706     the values in the string list are interpreted as environment

   707     setttings of the form \c {key=value} and the process is started

   708     with these environment settings. For convenience, there is a small

   709     exception to this rule under Unix: if \a env does not contain any

   710     settings for the environment variable \c LD_LIBRARY_PATH, then

   711     this variable is inherited from the starting process.

   712 

   713     Returns true if the process could be started; otherwise returns

   714     false.

   715 

   716     Note that you should not use the slots writeToStdin() and

   717     closeStdin() on processes started with launch(), since the result

   718     is not well-defined. If you need these slots, use start() instead.

   719 

   720     The process may or may not read the \a buf data sent to its

   721     standard input.

   722 

   723     You can call this function even when a process that was started

   724     with this instance is still running. Be aware that if you do this

   725     the standard input of the process that was launched first will be

   726     closed, with any pending data being deleted, and the process will

   727     be left to run out of your control. Similarly, if the process

   728     could not be started the standard input will be closed and the

   729     pending data deleted. (On operating systems that have zombie

   730     processes, Qt will also wait() on the old process.)

   731 

   732     The object emits the signal launchFinished() when this function

   733     call is finished. If the start was successful, this signal is

   734     emitted after all the data has been written to standard input. If

   735     the start failed, then this signal is emitted immediately.

   736 

   737     \sa start() launchFinished()

   738 */

   739 bool Q3Process::launch( const QByteArray& buf, QStringList *env )

   740 {

   741     if ( start( env ) ) {

   742 	if ( !buf.isEmpty() ) {

   743 	    connect( this, SIGNAL(wroteToStdin()),

   744 		    this, SLOT(closeStdinLaunch()) );

   745 	    writeToStdin( buf );

   746 	} else {

   747 	    closeStdin();

   748 	    emit launchFinished();

   749 	}

   750 	return true;

   751     } else {

   752 	emit launchFinished();

   753 	return false;

   754     }

   755 }

   756 

   757 /*!

   758     \overload

   759 

   760     The data \a buf is written to standard input with writeToStdin()

   761     using the QString::local8Bit() representation of the strings.

   762 */

   763 bool Q3Process::launch( const QString& buf, QStringList *env )

   764 {

   765     if ( start( env ) ) {

   766 	if ( !buf.isEmpty() ) {

   767 	    connect( this, SIGNAL(wroteToStdin()),

   768 		    this, SLOT(closeStdinLaunch()) );

   769 	    writeToStdin( buf );

   770 	} else {

   771 	    closeStdin();

   772 	    emit launchFinished();

   773 	}

   774 	return true;

   775     } else {

   776 	emit launchFinished();

   777 	return false;

   778     }

   779 }

   780 

   781 /*

   782   This private slot is used by the launch() functions to close standard input.

   783 */

   784 void Q3Process::closeStdinLaunch()

   785 {

   786     disconnect( this, SIGNAL(wroteToStdin()),

   787 	    this, SLOT(closeStdinLaunch()) );

   788     closeStdin();

   789     emit launchFinished();

   790 }

   791 

   792 

   793 /*!

   794     \fn void Q3Process::readyReadStdout()

   795 

   796     This signal is emitted when the process has written data to

   797     standard output. You can read the data with readStdout().

   798 

   799     Note that this signal is only emitted when there is new data and

   800     not when there is old, but unread data. In the slot connected to

   801     this signal, you should always read everything that is available

   802     at that moment to make sure that you don't lose any data.

   803 

   804     \sa readStdout() readLineStdout() readyReadStderr()

   805 */

   806 

   807 /*!

   808     \fn void Q3Process::readyReadStderr()

   809 

   810     This signal is emitted when the process has written data to

   811     standard error. You can read the data with readStderr().

   812 

   813     Note that this signal is only emitted when there is new data and

   814     not when there is old, but unread data. In the slot connected to

   815     this signal, you should always read everything that is available

   816     at that moment to make sure that you don't lose any data.

   817 

   818     \sa readStderr() readLineStderr() readyReadStdout()

   819 */

   820 

   821 /*!

   822     \fn void Q3Process::processExited()

   823 

   824     This signal is emitted when the process has exited.

   825 

   826     \sa isRunning() normalExit() exitStatus() start() launch()

   827 */

   828 

   829 /*!

   830     \fn void Q3Process::wroteToStdin()

   831 

   832     This signal is emitted if the data sent to standard input (via

   833     writeToStdin()) was actually written to the process. This does not

   834     imply that the process really read the data, since this class only

   835     detects when it was able to write the data to the operating

   836     system. But it is now safe to close standard input without losing

   837     pending data.

   838 

   839     \sa writeToStdin() closeStdin()

   840 */

   841 

   842 

   843 /*!

   844     \overload

   845 

   846     The string \a buf is handled as text using the

   847     QString::local8Bit() representation.

   848 */

   849 void Q3Process::writeToStdin( const QString& buf )

   850 {

   851     QByteArray tmp = buf.local8Bit();

   852     tmp.resize( buf.length() );

   853     writeToStdin( tmp );

   854 }

   855 

   856 

   857 /*

   858  * Under Windows the implementation is not so nice: it is not that easy to

   859  * detect when one of the signals should be emitted; therefore there are some

   860  * timers that query the information.

   861  * To keep it a little efficient, use the timers only when they are needed.

   862  * They are needed, if you are interested in the signals. So use

   863  * connectNotify() and disconnectNotify() to keep track of your interest.

   864  */

   865 /*!  \reimp

   866 */

   867 void Q3Process::connectNotify( const char * signal )

   868 {

   869 #if defined(QT_Q3PROCESS_DEBUG)

   870     qDebug( "Q3Process::connectNotify(): signal %s has been connected", signal );

   871 #endif

   872     if ( !ioRedirection )

   873 	if ( qstrcmp( signal, SIGNAL(readyReadStdout()) )==0 ||

   874 		qstrcmp( signal, SIGNAL(readyReadStderr()) )==0

   875 	   ) {

   876 #if defined(QT_Q3PROCESS_DEBUG)

   877 	    qDebug( "Q3Process::connectNotify(): set ioRedirection to true" );

   878 #endif

   879 	    setIoRedirection( true );

   880 	    return;

   881 	}

   882     if ( !notifyOnExit && qstrcmp( signal, SIGNAL(processExited()) )==0 ) {

   883 #if defined(QT_Q3PROCESS_DEBUG)

   884 	qDebug( "Q3Process::connectNotify(): set notifyOnExit to true" );

   885 #endif

   886 	setNotifyOnExit( true );

   887 	return;

   888     }

   889     if ( !wroteToStdinConnected && qstrcmp( signal, SIGNAL(wroteToStdin()) )==0 ) {

   890 #if defined(QT_Q3PROCESS_DEBUG)

   891 	qDebug( "Q3Process::connectNotify(): set wroteToStdinConnected to true" );

   892 #endif

   893 	setWroteStdinConnected( true );

   894 	return;

   895     }

   896 }

   897 

   898 /*!  \reimp

   899 */

   900 void Q3Process::disconnectNotify( const char * )

   901 {

   902     if ( ioRedirection &&

   903 	    receivers( SIGNAL(readyReadStdout()) ) ==0 &&

   904 	    receivers( SIGNAL(readyReadStderr()) ) ==0

   905 	    ) {

   906 #if defined(QT_Q3PROCESS_DEBUG)

   907 	qDebug( "Q3Process::disconnectNotify(): set ioRedirection to false" );

   908 #endif

   909 	setIoRedirection( false );

   910     }

   911     if ( notifyOnExit && receivers( SIGNAL(processExited()) ) == 0 ) {

   912 #if defined(QT_Q3PROCESS_DEBUG)

   913 	qDebug( "Q3Process::disconnectNotify(): set notifyOnExit to false" );

   914 #endif

   915 	setNotifyOnExit( false );

   916     }

   917     if ( wroteToStdinConnected && receivers( SIGNAL(wroteToStdin()) ) == 0 ) {

   918 #if defined(QT_Q3PROCESS_DEBUG)

   919 	qDebug( "Q3Process::disconnectNotify(): set wroteToStdinConnected to false" );

   920 #endif

   921 	setWroteStdinConnected( false );

   922     }

   923 }

   924 

   925 QT_END_NAMESPACE

   926 

   927 #endif // QT_NO_PROCESS