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