-rw-r--r-- | libopie/oprocess.h | 24 |
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 | ||
41 | class QSocketNotifier; | 41 | class QSocketNotifier; |
42 | class OProcessPrivate; | 42 | class 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 | ||
459 | signals: | 465 | signals: |
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 | ||
550 | protected: | 556 | protected: |
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 | ||
713 | private: | 719 | private: |
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 | */ |