summaryrefslogtreecommitdiffabout
path: root/microkde/oprocess.h
Unidiff
Diffstat (limited to 'microkde/oprocess.h') (more/less context) (ignore whitespace changes)
-rw-r--r--microkde/oprocess.h761
1 files changed, 761 insertions, 0 deletions
diff --git a/microkde/oprocess.h b/microkde/oprocess.h
new file mode 100644
index 0000000..be1436c
--- a/dev/null
+++ b/microkde/oprocess.h
@@ -0,0 +1,761 @@
1/*
2                This file is part of the Opie Project
3             Copyright (C) 2003-2004 Holger Freyther <zecke@handhelds.org>
4 Copyright (C) The Opie Team <opie-devel@handhelds.org>
5 =. Based on KProcess (C) 1997 Christian Czezatke (e9025461@student.tuwien.ac.at)
6 .=l.
7          .>+-=
8_;:,     .>    :=|. This program is free software; you can
9.> <`_,   >  .   <= redistribute it and/or modify it under
10:`=1 )Y*s>-.--   : the terms of the GNU Library General Public
11.="- .-=="i,     .._ License as published by the Free Software
12- .   .-<_>     .<> Foundation; either version 2 of the License,
13    ._= =}       : or (at your option) any later version.
14   .%`+i>       _;_.
15   .i_,=:_.      -<s. This program is distributed in the hope that
16    +  .  -:.       = it will be useful, but WITHOUT ANY WARRANTY;
17   : ..    .:,     . . . without even the implied warranty of
18   =_        +     =;=|` MERCHANTABILITY or FITNESS FOR A
19 _.=:.       :    :=>`: PARTICULAR PURPOSE. See the GNU
20..}^=.=       =       ; Library General Public License for more
21++=   -.     .`     .: details.
22:     =  ...= . :.=-
23-.   .:....=;==+<; You should have received a copy of the GNU
24 -_. . .   )=.  = Library General Public License along with
25   --        :-=` this library; see the file COPYING.LIB.
26 If not, write to the Free Software Foundation,
27 Inc., 59 Temple Place - Suite 330,
28 Boston, MA 02111-1307, USA.
29*/
30
31#ifndef OPROCESS_H
32#define OPROCESS_H
33
34/* QT */
35#include <qcstring.h>
36#include <qobject.h>
37#include <qvaluelist.h>
38
39/* STD */
40#include <sys/types.h> // for pid_t
41#include <sys/wait.h>
42#include <signal.h>
43#include <unistd.h>
44
45class QSocketNotifier;
46
47namespace Opie {
48namespace Core {
49namespace Internal {
50class OProcessController;
51class OProcessPrivate;
52}
53
54/**
55 * Child process invocation, monitoring and control.
56 *
57 * @sect General usage and features
58 *
59 *This class allows a KDE and OPIE application to start child processes without having
60 *to worry about UN*X signal handling issues and zombie process reaping.
61 *
62 *@see KProcIO
63 *
64 *Basically, this class distinguishes three different ways of running
65 *child processes:
66 *
67 *@li OProcess::DontCare -- The child process is invoked and both the child
68 *process and the parent process continue concurrently.
69 *
70 *Starting a DontCare child process means that the application is
71 *not interested in any notification to determine whether the
72 *child process has already exited or not.
73 *
74 *@li OProcess::NotifyOnExit -- The child process is invoked and both the
75 *child and the parent process run concurrently.
76 *
77 *When the child process exits, the OProcess instance
78 *corresponding to it emits the Qt signal @ref processExited().
79 *
80 *Since this signal is @em not emitted from within a UN*X
81 *signal handler, arbitrary function calls can be made.
82 *
83 *Be aware: When the OProcess objects gets destructed, the child
84 *process will be killed if it is still running!
85 *This means in particular, that you cannot use a OProcess on the stack
86 *with OProcess::NotifyOnExit.
87 *
88 *@li OProcess::Block -- The child process starts and the parent process
89 *is suspended until the child process exits. (@em Really not recommended
90 *for programs with a GUI.)
91 *
92 *OProcess also provides several functions for determining the exit status
93 *and the pid of the child process it represents.
94 *
95 *Furthermore it is possible to supply command-line arguments to the process
96 *in a clean fashion (no null -- terminated stringlists and such...)
97 *
98 *A small usage example:
99 *<pre>
100 *OProcess *proc = new OProcess;
101 *
102 **proc << "my_executable";
103 **proc << "These" << "are" << "the" << "command" << "line" << "args";
104 *QApplication::connect(proc, SIGNAL(processExited(Opie::Core::OProcess *)),
105 * pointer_to_my_object, SLOT(my_objects_slot(Opie::Core::OProcess *)));
106 *proc->start();
107 *</pre>
108 *
109 *This will start "my_executable" with the commandline arguments "These"...
110 *
111 *When the child process exits, the respective Qt signal will be emitted.
112 *
113 *@sect Communication with the child process
114 *
115 *OProcess supports communication with the child process through
116 *stdin/stdout/stderr.
117 *
118 *The following functions are provided for getting data from the child
119 *process or sending data to the child's stdin (For more information,
120 *have a look at the documentation of each function):
121 *
122 *@li bool @ref writeStdin(char *buffer, int buflen);
123 *@li -- Transmit data to the child process's stdin.
124 *
125 *@li bool @ref closeStdin();
126 *@li -- Closes the child process's stdin (which causes it to see an feof(stdin)).
127 *Returns false if you try to close stdin for a process that has been started
128 *without a communication channel to stdin.
129 *
130 *@li bool @ref closeStdout();
131 *@li -- Closes the child process's stdout.
132 *Returns false if you try to close stdout for a process that has been started
133 *without a communication channel to stdout.
134 *
135 *@li bool @ref closeStderr();
136 *@li -- Closes the child process's stderr.
137 *Returns false if you try to close stderr for a process that has been started
138 *without a communication channel to stderr.
139 *
140 *
141 *@sect QT signals:
142 *
143 *@li void @ref receivedStdout(OProcess *proc, char *buffer, int buflen);
144 *@li void @ref receivedStderr(OProcess *proc, char *buffer, int buflen);
145 *@li -- Indicates that new data has arrived from either the
146 *child process's stdout or stderr.
147 *
148 *@li void @ref wroteStdin(OProcess *proc);
149 *@li -- Indicates that all data that has been sent to the child process
150 *by a prior call to @ref writeStdin() has actually been transmitted to the
151 *client .
152 *
153 *@author Christian Czezakte e9025461@student.tuwien.ac.at
154 *@author Holger Freyther (Opie Port)
155 *
156 **/
157class OProcess : public QObject
158{
159 Q_OBJECT
160
161public:
162
163 /**
164 * Modes in which the communication channel can be opened.
165 *
166 * If communication for more than one channel is required,
167 * the values have to be or'ed together, for example to get
168 * communication with stdout as well as with stdin, you would
169 * specify @p Stdin @p | @p Stdout
170 *
171 * If @p NoRead is specified in conjunction with @p Stdout,
172 * no data is actually read from @p Stdout but only
173 * the signal @ref childOutput(int fd) is emitted.
174 */
175 enum Communication { NoCommunication = 0, Stdin = 1, Stdout = 2, Stderr = 4,
176 AllOutput = 6, All = 7,
177 NoRead };
178
179 /**
180 * Run-modes for a child process.
181 */
182 enum RunMode {
183 /**
184 * The application does not receive notifications from the subprocess when
185 * it is finished or aborted.
186 */
187 DontCare,
188 /**
189 * The application is notified when the subprocess dies.
190 */
191 NotifyOnExit,
192 /**
193 * The application is suspended until the started process is finished.
194 */
195 Block };
196
197 /**
198 * Constructor
199 */
200 OProcess( QObject *parent = 0, const char *name = 0 );
201 /**
202 * Constructor
203 */
204 OProcess( const QString &arg0, QObject *parent = 0, const char *name = 0 );
205 /**
206 * Constructor
207 */
208 OProcess( const QStringList &args, QObject *parent = 0, const char *name = 0 );
209
210 /**
211 *Destructor:
212 *
213 * If the process is running when the destructor for this class
214 * is called, the child process is killed with a SIGKILL, but
215 * only if the run mode is not of type @p DontCare.
216 * Processes started as @p DontCare keep running anyway.
217 */
218 virtual ~OProcess();
219
220 /**
221 @deprecated
222
223 The use of this function is now deprecated. -- Please use the
224 "operator<<" instead of "setExecutable".
225
226 Sets the executable to be started with this OProcess object.
227 Returns false if the process is currently running (in that
228 case the executable remains unchanged.)
229
230 @see operator<<
231
232 */
233 bool setExecutable( const QString& proc );
234
235
236 /**
237 * Sets the executable and the command line argument list for this process.
238 *
239 * For example, doing an "ls -l /usr/local/bin" can be achieved by:
240 * <pre>
241 * OProcess p;
242 * ...
243 * p << "ls" << "-l" << "/usr/local/bin"
244 * </pre>
245 *
246 **/
247 OProcess &operator<<( const QString& arg );
248 /**
249 * Similar to previous method, takes a char *, supposed to be in locale 8 bit already.
250 */
251 OProcess &operator<<( const char * arg );
252 /**
253 * Similar to previous method, takes a QCString, supposed to be in locale 8 bit already.
254 */
255 OProcess &operator<<( const QCString & arg );
256
257 /**
258 * Sets the executable and the command line argument list for this process,
259 * in a single method call, or add a list of arguments.
260 **/
261 OProcess &operator<<( const QStringList& args );
262
263 /**
264 * Clear a command line argument list that has been set by using
265 * the "operator<<".
266 */
267 void clearArguments();
268
269 /**
270 * Starts the process.
271 * For a detailed description of the
272 * various run modes and communication semantics, have a look at the
273 * general description of the OProcess class.
274 *
275 * The following problems could cause this function to
276 * return false:
277 *
278 * @li The process is already running.
279 * @li The command line argument list is empty.
280 * @li The starting of the process failed (could not fork).
281 * @li The executable was not found.
282 *
283 * @param comm Specifies which communication links should be
284 * established to the child process (stdin/stdout/stderr). By default,
285 * no communication takes place and the respective communication
286 * signals will never get emitted.
287 *
288 * @return true on success, false on error
289 * (see above for error conditions)
290 **/
291 virtual bool start( RunMode runmode = NotifyOnExit,
292 Communication comm = NoCommunication );
293
294 /**
295 * Stop the process (by sending it a signal).
296 *
297 * @param signoThe signal to send. The default is SIGTERM.
298 * @return @p true if the signal was delivered successfully.
299 */
300 virtual bool kill( int signo = SIGTERM );
301
302 /**
303 @return @p true if the process is (still) considered to be running
304 */
305 bool isRunning() const;
306
307 /** Returns the process id of the process.
308 *
309 * If it is called after
310 * the process has exited, it returns the process id of the last
311 * child process that was created by this instance of OProcess.
312 *
313 * Calling it before any child process has been started by this
314 * OProcess instance causes pid() to return 0.
315 **/
316 pid_t pid() const;
317
318 /**
319 * Suspend processing of data from stdout of the child process.
320 */
321 void suspend();
322
323 /**
324 * Resume processing of data from stdout of the child process.
325 */
326 void resume();
327
328 /**
329 * @return @p true if the process has already finished and has exited
330 * "voluntarily", ie: it has not been killed by a signal.
331 *
332 * Note that you should check @ref OProcess::exitStatus() to determine
333 * whether the process completed its task successful or not.
334 */
335 bool normalExit() const;
336
337 /**
338 * Returns the exit status of the process.
339 *
340 * Please use
341 * @ref OProcess::normalExit() to check whether the process has exited
342 * cleanly (i.e., @ref OProcess::normalExit() returns @p true) before calling
343 * this function because if the process did not exit normally,
344 * it does not have a valid exit status.
345 */
346 int exitStatus() const;
347
348
349 /**
350 * Transmit data to the child process's stdin.
351 *
352 * OProcess::writeStdin may return false in the following cases:
353 *
354 * @li The process is not currently running.
355 *
356 * @li Communication to stdin has not been requested in the @ref start() call.
357 *
358 * @li Transmission of data to the child process by a previous call to
359 * @ref writeStdin() is still in progress.
360 *
361 * Please note that the data is sent to the client asynchronously,
362 * so when this function returns, the data might not have been
363 * processed by the child process.
364 *
365 * If all the data has been sent to the client, the signal
366 * @ref wroteStdin() will be emitted.
367 *
368 * Please note that you must not free "buffer" or call @ref writeStdin()
369 * again until either a @ref wroteStdin() signal indicates that the
370 * data has been sent or a @ref processHasExited() signal shows that
371 * the child process is no longer alive...
372 **/
373 bool writeStdin( const char *buffer, int buflen );
374
375 void flushStdin();
376
377 /**
378 * This causes the stdin file descriptor of the child process to be
379 * closed indicating an "EOF" to the child.
380 *
381 * @return @p false if no communication to the process's stdin
382 * had been specified in the call to @ref start().
383 */
384 bool closeStdin();
385
386 /**
387 * This causes the stdout file descriptor of the child process to be
388 * closed.
389 *
390 * @return @p false if no communication to the process's stdout
391 * had been specified in the call to @ref start().
392 */
393 bool closeStdout();
394
395 /**
396 * This causes the stderr file descriptor of the child process to be
397 * closed.
398 *
399 * @return @p false if no communication to the process's stderr
400 * had been specified in the call to @ref start().
401 */
402 bool closeStderr();
403
404 /**
405 * Lets you see what your arguments are for debugging.
406 * \todo make const
407 */
408
409 const QValueList<QCString> &args()
410 {
411 return arguments;
412 }
413
414 /**
415 * Controls whether the started process should drop any
416 * setuid/segid privileges or whether it should keep them
417 *
418 * The default is @p false : drop privileges
419 */
420 void setRunPrivileged( bool keepPrivileges );
421
422 /**
423 * Returns whether the started process will drop any
424 * setuid/segid privileges or whether it will keep them
425 */
426 bool runPrivileged() const;
427
428 /**
429 * Modifies the environment of the process to be started.
430 * This function must be called before starting the process.
431 */
432 void setEnvironment( const QString &name, const QString &value );
433
434 /**
435 * Changes the current working directory (CWD) of the process
436 * to be started.
437 * This function must be called before starting the process.
438 */
439 void setWorkingDirectory( const QString &dir );
440
441 /**
442 * Specify whether to start the command via a shell or directly.
443 * The default is to start the command directly.
444 * If @p useShell is true @p shell will be used as shell, or
445 * if shell is empty, the standard shell is used.
446 * @p quote A flag indicating whether to quote the arguments.
447 *
448 * When using a shell, the caller should make sure that all filenames etc.
449 * are properly quoted when passed as argument.
450 * @see quote()
451 */
452 void setUseShell( bool useShell, const char *shell = 0 );
453
454 /**
455 * This function can be used to quote an argument string such that
456 * the shell processes it properly. This is e. g. necessary for
457 * user-provided file names which may contain spaces or quotes.
458 * It also prevents expansion of wild cards and environment variables.
459 */
460 static QString quote( const QString &arg );
461
462 /**
463 * Detaches OProcess from child process. All communication is closed.
464 * No exit notification is emitted any more for the child process.
465 * Deleting the OProcess will no longer kill the child process.
466 * Note that the current process remains the parent process of the
467 * child process.
468 */
469 void detach();
470
471 /**
472 * @return the PID of @a process, or -1 if the process is not running
473 */
474 static int processPID( const QString& process );
475
476signals:
477
478 /**
479 * Emitted after the process has terminated when
480 * the process was run in the @p NotifyOnExit (==default option to
481 * @ref start()) or the @ref Block mode.
482 **/
483 void processExited( Opie::Core::OProcess *proc );
484
485
486 /**
487 * Emitted, when output from the child process has
488 * been received on stdout.
489 *
490 * To actually get
491 * these signals, the respective communication link (stdout/stderr)
492 * has to be turned on in @ref start().
493 *
494 * @param buffer The data received.
495 * @param buflen The number of bytes that are available.
496 *
497 * You should copy the information contained in @p buffer to your private
498 * data structures before returning from this slot.
499 **/
500 void receivedStdout( Opie::Core::OProcess *proc, char *buffer, int buflen );
501
502 /**
503 * Emitted when output from the child process has
504 * been received on stdout.
505 *
506 * To actually get these signals, the respective communications link
507 * (stdout/stderr) has to be turned on in @ref start() and the
508 * @p NoRead flag should have been passed.
509 *
510 * You will need to explicitly call resume() after your call to start()
511 * to begin processing data from the child process's stdout. This is
512 * to ensure that this signal is not emitted when no one is connected
513 * to it, otherwise this signal will not be emitted.
514 *
515 * The data still has to be read from file descriptor @p fd.
516 **/
517 void receivedStdout( int fd, int &len );
518
519
520 /**
521 * Emitted, when output from the child process has
522 * been received on stderr.
523 * To actually get
524 * these signals, the respective communication link (stdout/stderr)
525 * has to be turned on in @ref start().
526 *
527 * @param buffer The data received.
528 * @param buflen The number of bytes that are available.
529 *
530 * You should copy the information contained in @p buffer to your private
531 * data structures before returning from this slot.
532 */
533 void receivedStderr( Opie::Core::OProcess *proc, char *buffer, int buflen );
534
535 /**
536 * Emitted after all the data that has been
537 * specified by a prior call to @ref writeStdin() has actually been
538 * written to the child process.
539 **/
540 void wroteStdin( Opie::Core::OProcess *proc );
541
542protected slots:
543
544 /**
545 * This slot gets activated when data from the child's stdout arrives.
546 * It usually calls "childOutput"
547 */
548 void slotChildOutput( int fdno );
549
550 /**
551 * This slot gets activated when data from the child's stderr arrives.
552 * It usually calls "childError"
553 */
554 void slotChildError( int fdno );
555 /*
556 Slot functions for capturing stdout and stderr of the child
557 */
558
559 /**
560 * Called when another bulk of data can be sent to the child's
561 * stdin. If there is no more data to be sent to stdin currently
562 * available, this function must disable the QSocketNotifier "innot".
563 */
564 void slotSendData( int dummy );
565
566protected:
567
568 /**
569 * Sets up the environment according to the data passed via
570 * setEnvironment(...)
571 */
572 void setupEnvironment();
573
574 /**
575 * The list of the process' command line arguments. The first entry
576 * in this list is the executable itself.
577 */
578 QValueList<QCString> arguments;
579 /**
580 * How to run the process (Block, NotifyOnExit, DontCare). You should
581 * not modify this data member directly from derived classes.
582 */
583 RunMode run_mode;
584 /**
585 * true if the process is currently running. You should not
586 * modify this data member directly from derived classes. For
587 * reading the value of this data member, please use "isRunning()"
588 * since "runs" will probably be made private in later versions
589 * of OProcess.
590 */
591 bool runs;
592
593 /**
594 * The PID of the currently running process (see "getPid()").
595 * You should not modify this data member in derived classes.
596 * Please use "getPid()" instead of directly accessing this
597 * member function since it will probably be made private in
598 * later versions of OProcess.
599 */
600 pid_t pid_;
601
602 /**
603 * The process' exit status as returned by "waitpid". You should not
604 * modify the value of this data member from derived classes. You should
605 * rather use @ref exitStatus than accessing this data member directly
606 * since it will probably be made private in further versions of
607 * OProcess.
608 */
609 int status;
610
611
612 /**
613 * See setRunPrivileged()
614 */
615 bool keepPrivs;
616
617 /*
618 Functions for setting up the sockets for communication.
619 setupCommunication
620 -- is called from "start" before "fork"ing.
621 commSetupDoneP
622 -- completes communication socket setup in the parent
623 commSetupDoneC
624 -- completes communication setup in the child process
625 commClose
626 -- frees all allocated communication resources in the parent
627 after the process has exited
628 */
629
630 /**
631 * This function is called from "OProcess::start" right before a "fork" takes
632 * place. According to
633 * the "comm" parameter this function has to initialize the "in", "out" and
634 * "err" data member of OProcess.
635 *
636 * This function should return 0 if setting the needed communication channels
637 * was successful.
638 *
639 * The default implementation is to create UNIX STREAM sockets for the communication,
640 * but you could overload this function and establish a TCP/IP communication for
641 * network communication, for example.
642 */
643 virtual int setupCommunication( Communication comm );
644
645 /**
646 * Called right after a (successful) fork on the parent side. This function
647 * will usually do some communications cleanup, like closing the reading end
648 * of the "stdin" communication channel.
649 *
650 * Furthermore, it must also create the QSocketNotifiers "innot", "outnot" and
651 * "errnot" and connect their Qt slots to the respective OProcess member functions.
652 *
653 * For a more detailed explanation, it is best to have a look at the default
654 * implementation of "setupCommunication" in kprocess.cpp.
655 */
656 virtual int commSetupDoneP();
657
658 /**
659 * Called right after a (successful) fork, but before an "exec" on the child
660 * process' side. It usually just closes the unused communication ends of
661 * "in", "out" and "err" (like the writing end of the "in" communication
662 * channel.
663 */
664 virtual int commSetupDoneC();
665
666
667 /**
668 * Immediately called after a process has exited. This function normally
669 * calls commClose to close all open communication channels to this
670 * process and emits the "processExited" signal (if the process was
671 * not running in the "DontCare" mode).
672 */
673 virtual void processHasExited( int state );
674
675 /**
676 * Should clean up the communication links to the child after it has
677 * exited. Should be called from "processHasExited".
678 */
679 virtual void commClose();
680
681
682 /**
683 * the socket descriptors for stdin/stdout/stderr.
684 */
685 int out[ 2 ];
686 int in[ 2 ];
687 int err[ 2 ];
688
689 /**
690 * The socket notifiers for the above socket descriptors.
691 */
692 QSocketNotifier *innot;
693 QSocketNotifier *outnot;
694 QSocketNotifier *errnot;
695
696 /**
697 * Lists the communication links that are activated for the child
698 * process. Should not be modified from derived classes.
699 */
700 Communication communication;
701
702 /**
703 * Called by "slotChildOutput" this function copies data arriving from the
704 * child process's stdout to the respective buffer and emits the signal
705 * "@ref receivedStderr".
706 */
707 int childOutput( int fdno );
708
709 /**
710 * Called by "slotChildOutput" this function copies data arriving from the
711 * child process's stdout to the respective buffer and emits the signal
712 * "@ref receivedStderr"
713 */
714 int childError( int fdno );
715
716 // information about the data that has to be sent to the child:
717
718 const char *input_data; // the buffer holding the data
719 int input_sent; // # of bytes already transmitted
720 int input_total; // total length of input_data
721
722 /**
723 * @ref OProcessController is a friend of OProcess because it has to have
724 * access to various data members.
725 */
726 friend class Internal::OProcessController;
727
728private:
729 /**
730 * Searches for a valid shell.
731 * Here is the algorithm used for finding an executable shell:
732 *
733 * @li Try the executable pointed to by the "SHELL" environment
734 * variable with white spaces stripped off
735 *
736 * @li If your process runs with uid != euid or gid != egid, a shell
737 * not listed in /etc/shells will not used.
738 *
739 * @li If no valid shell could be found, "/bin/sh" is used as a last resort.
740 */
741 QCString searchShell();
742
743 /**
744 * Used by @ref searchShell in order to find out whether the shell found
745 * is actually executable at all.
746 */
747 bool isExecutable( const QCString &filename );
748
749 // Disallow assignment and copy-construction
750 OProcess( const OProcess& );
751 OProcess& operator= ( const OProcess& );
752
753private:
754 void init ( );
755 Internal::OProcessPrivate *d;
756};
757}
758}
759
760#endif
761