summaryrefslogtreecommitdiff
path: root/libopie/oprocess.h
Unidiff
Diffstat (limited to 'libopie/oprocess.h') (more/less context) (ignore whitespace changes)
-rw-r--r--libopie/oprocess.h24
1 files changed, 15 insertions, 9 deletions
diff --git a/libopie/oprocess.h b/libopie/oprocess.h
index bf5fe0e..f2853b0 100644
--- a/libopie/oprocess.h
+++ b/libopie/oprocess.h
@@ -33,33 +33,33 @@
33#include <sys/types.h> // for pid_t 33#include <sys/types.h> // for pid_t
34#include <sys/wait.h> 34#include <sys/wait.h>
35#include <signal.h> 35#include <signal.h>
36#include <unistd.h> 36#include <unistd.h>
37#include <qvaluelist.h> 37#include <qvaluelist.h>
38#include <qcstring.h> 38#include <qcstring.h>
39#include <qobject.h> 39#include <qobject.h>
40 40
41class QSocketNotifier; 41class QSocketNotifier;
42class OProcessPrivate; 42class OProcessPrivate;
43 43
44/** 44/**
45 * Child process invocation, monitoring and control. 45 * Child process invocation, monitoring and control.
46 * 46 *
47 * @sect General usage and features 47 * @sect General usage and features
48 * 48 *
49 *This class allows a KDE application to start child processes without having 49 *This class allows a KDE and OPIE application to start child processes without having
50 *to worry about UN*X signal handling issues and zombie process reaping. 50 *to worry about UN*X signal handling issues and zombie process reaping.
51 * 51 *
52 *@see KProcIO 52 *@see KProcIO
53 * 53 *
54 *Basically, this class distinguishes three different ways of running 54 *Basically, this class distinguishes three different ways of running
55 *child processes: 55 *child processes:
56 * 56 *
57 *@li OProcess::DontCare -- The child process is invoked and both the child 57 *@li OProcess::DontCare -- The child process is invoked and both the child
58 *process and the parent process continue concurrently. 58 *process and the parent process continue concurrently.
59 * 59 *
60 *Starting a DontCare child process means that the application is 60 *Starting a DontCare child process means that the application is
61 *not interested in any notification to determine whether the 61 *not interested in any notification to determine whether the
62 *child process has already exited or not. 62 *child process has already exited or not.
63 * 63 *
64 *@li OProcess::NotifyOnExit -- The child process is invoked and both the 64 *@li OProcess::NotifyOnExit -- The child process is invoked and both the
65 *child and the parent process run concurrently. 65 *child and the parent process run concurrently.
@@ -175,33 +175,39 @@ public:
175 * it is finished or aborted. 175 * it is finished or aborted.
176 */ 176 */
177 DontCare, 177 DontCare,
178 /** 178 /**
179 * The application is notified when the subprocess dies. 179 * The application is notified when the subprocess dies.
180 */ 180 */
181 NotifyOnExit, 181 NotifyOnExit,
182 /** 182 /**
183 * The application is suspended until the started process is finished. 183 * The application is suspended until the started process is finished.
184 */ 184 */
185 Block }; 185 Block };
186 186
187 /** 187 /**
188 * Constructor 188 * Constructor
189 */ 189 */
190 OProcess(QObject *parent = 0, const char *name = 0); 190 OProcess(QObject *parent = 0, const char *name = 0);
191 /**
192 * Constructor
193 */
191 OProcess(const QString &arg0, QObject *parent = 0, const char *name = 0); 194 OProcess(const QString &arg0, QObject *parent = 0, const char *name = 0);
195 /**
196 * Constructor
197 */
192 OProcess(const QStringList &args, QObject *parent = 0, const char *name = 0); 198 OProcess(const QStringList &args, QObject *parent = 0, const char *name = 0);
193 199
194 /** 200 /**
195 *Destructor: 201 *Destructor:
196 * 202 *
197 * If the process is running when the destructor for this class 203 * If the process is running when the destructor for this class
198 * is called, the child process is killed with a SIGKILL, but 204 * is called, the child process is killed with a SIGKILL, but
199 * only if the run mode is not of type @p DontCare. 205 * only if the run mode is not of type @p DontCare.
200 * Processes started as @p DontCare keep running anyway. 206 * Processes started as @p DontCare keep running anyway.
201 */ 207 */
202 virtual ~OProcess(); 208 virtual ~OProcess();
203 209
204 /** 210 /**
205 @deprecated 211 @deprecated
206 212
207 The use of this function is now deprecated. -- Please use the 213 The use of this function is now deprecated. -- Please use the
@@ -397,41 +403,41 @@ public:
397 403
398 const QValueList<QCString> &args() { return arguments; } 404 const QValueList<QCString> &args() { return arguments; }
399 405
400 /** 406 /**
401 * Controls whether the started process should drop any 407 * Controls whether the started process should drop any
402 * setuid/segid privileges or whether it should keep them 408 * setuid/segid privileges or whether it should keep them
403 * 409 *
404 * The default is @p false : drop privileges 410 * The default is @p false : drop privileges
405 */ 411 */
406 void setRunPrivileged(bool keepPrivileges); 412 void setRunPrivileged(bool keepPrivileges);
407 413
408 /** 414 /**
409 * Returns whether the started process will drop any 415 * Returns whether the started process will drop any
410 * setuid/segid privileges or whether it will keep them 416 * setuid/segid privileges or whether it will keep them
411 */ 417 */
412 bool runPrivileged() const; 418 bool runPrivileged() const;
413 419
414 /** 420 /**
415 * Modifies the environment of the process to be started. 421 * Modifies the environment of the process to be started.
416 * This function must be called before starting the process. 422 * This function must be called before starting the process.
417 */ 423 */
418 void setEnvironment(const QString &name, const QString &value); 424 void setEnvironment(const QString &name, const QString &value);
419 425
420 /** 426 /**
421 * Changes the current working directory (CWD) of the process 427 * Changes the current working directory (CWD) of the process
422 * to be started. 428 * to be started.
423 * This function must be called before starting the process. 429 * This function must be called before starting the process.
424 */ 430 */
425 void setWorkingDirectory(const QString &dir); 431 void setWorkingDirectory(const QString &dir);
426 432
427 /** 433 /**
428 * Specify whether to start the command via a shell or directly. 434 * Specify whether to start the command via a shell or directly.
429 * The default is to start the command directly. 435 * The default is to start the command directly.
430 * If @p useShell is true @p shell will be used as shell, or 436 * If @p useShell is true @p shell will be used as shell, or
431 * if shell is empty, the standard shell is used. 437 * if shell is empty, the standard shell is used.
432 * @p quote A flag indicating whether to quote the arguments. 438 * @p quote A flag indicating whether to quote the arguments.
433 * 439 *
434 * When using a shell, the caller should make sure that all filenames etc. 440 * When using a shell, the caller should make sure that all filenames etc.
435 * are properly quoted when passed as argument. 441 * are properly quoted when passed as argument.
436 * @see quote() 442 * @see quote()
437 */ 443 */
@@ -439,33 +445,33 @@ public:
439 445
440 /** 446 /**
441 * This function can be used to quote an argument string such that 447 * This function can be used to quote an argument string such that
442 * the shell processes it properly. This is e. g. necessary for 448 * the shell processes it properly. This is e. g. necessary for
443 * user-provided file names which may contain spaces or quotes. 449 * user-provided file names which may contain spaces or quotes.
444 * It also prevents expansion of wild cards and environment variables. 450 * It also prevents expansion of wild cards and environment variables.
445 */ 451 */
446 static QString quote(const QString &arg); 452 static QString quote(const QString &arg);
447 453
448 /** 454 /**
449 * Detaches OProcess from child process. All communication is closed. 455 * Detaches OProcess from child process. All communication is closed.
450 * No exit notification is emitted any more for the child process. 456 * No exit notification is emitted any more for the child process.
451 * Deleting the OProcess will no longer kill the child process. 457 * Deleting the OProcess will no longer kill the child process.
452 * Note that the current process remains the parent process of the 458 * Note that the current process remains the parent process of the
453 * child process. 459 * child process.
454 */ 460 */
455 void detach(); 461 void detach();
456 462
457 463
458 464
459signals: 465signals:
460 466
461 /** 467 /**
462 * Emitted after the process has terminated when 468 * Emitted after the process has terminated when
463 * the process was run in the @p NotifyOnExit (==default option to 469 * the process was run in the @p NotifyOnExit (==default option to
464 * @ref start()) or the @ref Block mode. 470 * @ref start()) or the @ref Block mode.
465 **/ 471 **/
466 void processExited(OProcess *proc); 472 void processExited(OProcess *proc);
467 473
468 474
469 /** 475 /**
470 * Emitted, when output from the child process has 476 * Emitted, when output from the child process has
471 * been received on stdout. 477 * been received on stdout.
@@ -473,41 +479,41 @@ signals:
473 * To actually get 479 * To actually get
474 * these signals, the respective communication link (stdout/stderr) 480 * these signals, the respective communication link (stdout/stderr)
475 * has to be turned on in @ref start(). 481 * has to be turned on in @ref start().
476 * 482 *
477 * @param buffer The data received. 483 * @param buffer The data received.
478 * @param buflen The number of bytes that are available. 484 * @param buflen The number of bytes that are available.
479 * 485 *
480 * You should copy the information contained in @p buffer to your private 486 * You should copy the information contained in @p buffer to your private
481 * data structures before returning from this slot. 487 * data structures before returning from this slot.
482 **/ 488 **/
483 void receivedStdout(OProcess *proc, char *buffer, int buflen); 489 void receivedStdout(OProcess *proc, char *buffer, int buflen);
484 490
485 /** 491 /**
486 * Emitted when output from the child process has 492 * Emitted when output from the child process has
487 * been received on stdout. 493 * been received on stdout.
488 * 494 *
489 * To actually get these signals, the respective communications link 495 * To actually get these signals, the respective communications link
490 * (stdout/stderr) has to be turned on in @ref start() and the 496 * (stdout/stderr) has to be turned on in @ref start() and the
491 * @p NoRead flag should have been passed. 497 * @p NoRead flag should have been passed.
492 * 498 *
493 * You will need to explicitly call resume() after your call to start() 499 * You will need to explicitly call resume() after your call to start()
494 * to begin processing data from the child process's stdout. This is 500 * to begin processing data from the child process's stdout. This is
495 * to ensure that this signal is not emitted when no one is connected 501 * to ensure that this signal is not emitted when no one is connected
496 * to it, otherwise this signal will not be emitted. 502 * to it, otherwise this signal will not be emitted.
497 * 503 *
498 * The data still has to be read from file descriptor @p fd. 504 * The data still has to be read from file descriptor @p fd.
499 **/ 505 **/
500 void receivedStdout(int fd, int &len); 506 void receivedStdout(int fd, int &len);
501 507
502 508
503 /** 509 /**
504 * Emitted, when output from the child process has 510 * Emitted, when output from the child process has
505 * been received on stderr. 511 * been received on stderr.
506 * To actually get 512 * To actually get
507 * these signals, the respective communication link (stdout/stderr) 513 * these signals, the respective communication link (stdout/stderr)
508 * has to be turned on in @ref start(). 514 * has to be turned on in @ref start().
509 * 515 *
510 * @param buffer The data received. 516 * @param buffer The data received.
511 * @param buflen The number of bytes that are available. 517 * @param buflen The number of bytes that are available.
512 * 518 *
513 * You should copy the information contained in @p buffer to your private 519 * You should copy the information contained in @p buffer to your private
@@ -537,33 +543,33 @@ protected slots:
537 */ 543 */
538 void slotChildError(int fdno); 544 void slotChildError(int fdno);
539 /* 545 /*
540 Slot functions for capturing stdout and stderr of the child 546 Slot functions for capturing stdout and stderr of the child
541 */ 547 */
542 548
543 /** 549 /**
544 * Called when another bulk of data can be sent to the child's 550 * Called when another bulk of data can be sent to the child's
545 * stdin. If there is no more data to be sent to stdin currently 551 * stdin. If there is no more data to be sent to stdin currently
546 * available, this function must disable the QSocketNotifier "innot". 552 * available, this function must disable the QSocketNotifier "innot".
547 */ 553 */
548 void slotSendData(int dummy); 554 void slotSendData(int dummy);
549 555
550protected: 556protected:
551 557
552 /** 558 /**
553 * Sets up the environment according to the data passed via 559 * Sets up the environment according to the data passed via
554 * setEnvironment(...) 560 * setEnvironment(...)
555 */ 561 */
556 void setupEnvironment(); 562 void setupEnvironment();
557 563
558 /** 564 /**
559 * The list of the process' command line arguments. The first entry 565 * The list of the process' command line arguments. The first entry
560 * in this list is the executable itself. 566 * in this list is the executable itself.
561 */ 567 */
562 QValueList<QCString> arguments; 568 QValueList<QCString> arguments;
563 /** 569 /**
564 * How to run the process (Block, NotifyOnExit, DontCare). You should 570 * How to run the process (Block, NotifyOnExit, DontCare). You should
565 * not modify this data member directly from derived classes. 571 * not modify this data member directly from derived classes.
566 */ 572 */
567 RunMode run_mode; 573 RunMode run_mode;
568 /** 574 /**
569 * true if the process is currently running. You should not 575 * true if the process is currently running. You should not
@@ -699,33 +705,33 @@ protected:
699 705
700 // information about the data that has to be sent to the child: 706 // information about the data that has to be sent to the child:
701 707
702 const char *input_data; // the buffer holding the data 708 const char *input_data; // the buffer holding the data
703 int input_sent; // # of bytes already transmitted 709 int input_sent; // # of bytes already transmitted
704 int input_total; // total length of input_data 710 int input_total; // total length of input_data
705 711
706 /** 712 /**
707 * @ref OProcessController is a friend of OProcess because it has to have 713 * @ref OProcessController is a friend of OProcess because it has to have
708 * access to various data members. 714 * access to various data members.
709 */ 715 */
710 friend class OProcessController; 716 friend class OProcessController;
711 717
712 718
713private: 719private:
714 /** 720 /**
715 * Searches for a valid shell. 721 * Searches for a valid shell.
716 * Here is the algorithm used for finding an executable shell: 722 * Here is the algorithm used for finding an executable shell:
717 * 723 *
718 * @li Try the executable pointed to by the "SHELL" environment 724 * @li Try the executable pointed to by the "SHELL" environment
719 * variable with white spaces stripped off 725 * variable with white spaces stripped off
720 * 726 *
721 * @li If your process runs with uid != euid or gid != egid, a shell 727 * @li If your process runs with uid != euid or gid != egid, a shell
722 * not listed in /etc/shells will not used. 728 * not listed in /etc/shells will not used.
723 * 729 *
724 * @li If no valid shell could be found, "/bin/sh" is used as a last resort. 730 * @li If no valid shell could be found, "/bin/sh" is used as a last resort.
725 */ 731 */
726 QCString searchShell(); 732 QCString searchShell();
727 733
728 /** 734 /**
729 * Used by @ref searchShell in order to find out whether the shell found 735 * Used by @ref searchShell in order to find out whether the shell found
730 * is actually executable at all. 736 * is actually executable at all.
731 */ 737 */