summaryrefslogtreecommitdiff
path: root/libopie/oprocess.h
Unidiff
Diffstat (limited to 'libopie/oprocess.h') (more/less context) (ignore whitespace changes)
-rw-r--r--libopie/oprocess.h747
1 files changed, 0 insertions, 747 deletions
diff --git a/libopie/oprocess.h b/libopie/oprocess.h
deleted file mode 100644
index af7cddb..0000000
--- a/libopie/oprocess.h
+++ b/dev/null
@@ -1,747 +0,0 @@
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 to the Open Palmtop Integrated Environment
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 and OPIE 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(QObject *parent = 0, const char *name = 0);
191 /**
192 * Constructor
193 */
194 OProcess(const QString &arg0, QObject *parent = 0, const char *name = 0);
195 /**
196 * Constructor
197 */
198 OProcess(const QStringList &args, QObject *parent = 0, const char *name = 0);
199
200 /**
201 *Destructor:
202 *
203 * If the process is running when the destructor for this class
204 * is called, the child process is killed with a SIGKILL, but
205 * only if the run mode is not of type @p DontCare.
206 * Processes started as @p DontCare keep running anyway.
207 */
208 virtual ~OProcess();
209
210 /**
211 @deprecated
212
213 The use of this function is now deprecated. -- Please use the
214 "operator<<" instead of "setExecutable".
215
216 Sets the executable to be started with this OProcess object.
217 Returns false if the process is currently running (in that
218 case the executable remains unchanged.)
219
220 @see operator<<
221
222 */
223 bool setExecutable(const QString& proc);
224
225
226 /**
227 * Sets the executable and the command line argument list for this process.
228 *
229 * For example, doing an "ls -l /usr/local/bin" can be achieved by:
230 * <pre>
231 * OProcess p;
232 * ...
233 * p << "ls" << "-l" << "/usr/local/bin"
234 * </pre>
235 *
236 **/
237 OProcess &operator<<(const QString& arg);
238 /**
239 * Similar to previous method, takes a char *, supposed to be in locale 8 bit already.
240 */
241 OProcess &operator<<(const char * arg);
242 /**
243 * Similar to previous method, takes a QCString, supposed to be in locale 8 bit already.
244 */
245 OProcess &operator<<(const QCString & arg);
246
247 /**
248 * Sets the executable and the command line argument list for this process,
249 * in a single method call, or add a list of arguments.
250 **/
251 OProcess &operator<<(const QStringList& args);
252
253 /**
254 * Clear a command line argument list that has been set by using
255 * the "operator<<".
256 */
257 void clearArguments();
258
259 /**
260 * Starts the process.
261 * For a detailed description of the
262 * various run modes and communication semantics, have a look at the
263 * general description of the OProcess class.
264 *
265 * The following problems could cause this function to
266 * return false:
267 *
268 * @li The process is already running.
269 * @li The command line argument list is empty.
270 * @li The starting of the process failed (could not fork).
271 * @li The executable was not found.
272 *
273 * @param comm Specifies which communication links should be
274 * established to the child process (stdin/stdout/stderr). By default,
275 * no communication takes place and the respective communication
276 * signals will never get emitted.
277 *
278 * @return true on success, false on error
279 * (see above for error conditions)
280 **/
281 virtual bool start(RunMode runmode = NotifyOnExit,
282 Communication comm = NoCommunication);
283
284 /**
285 * Stop the process (by sending it a signal).
286 *
287 * @param signoThe signal to send. The default is SIGTERM.
288 * @return @p true if the signal was delivered successfully.
289 */
290 virtual bool kill(int signo = SIGTERM);
291
292 /**
293 @return @p true if the process is (still) considered to be running
294 */
295 bool isRunning() const;
296
297 /** Returns the process id of the process.
298 *
299 * If it is called after
300 * the process has exited, it returns the process id of the last
301 * child process that was created by this instance of OProcess.
302 *
303 * Calling it before any child process has been started by this
304 * OProcess instance causes pid() to return 0.
305 **/
306 pid_t pid() const;
307
308 /**
309 * Suspend processing of data from stdout of the child process.
310 */
311 void suspend();
312
313 /**
314 * Resume processing of data from stdout of the child process.
315 */
316 void resume();
317
318 /**
319 * @return @p true if the process has already finished and has exited
320 * "voluntarily", ie: it has not been killed by a signal.
321 *
322 * Note that you should check @ref OProcess::exitStatus() to determine
323 * whether the process completed its task successful or not.
324 */
325 bool normalExit() const;
326
327 /**
328 * Returns the exit status of the process.
329 *
330 * Please use
331 * @ref OProcess::normalExit() to check whether the process has exited
332 * cleanly (i.e., @ref OProcess::normalExit() returns @p true) before calling
333 * this function because if the process did not exit normally,
334 * it does not have a valid exit status.
335 */
336 int exitStatus() const;
337
338
339 /**
340 * Transmit data to the child process's stdin.
341 *
342 * OProcess::writeStdin may return false in the following cases:
343 *
344 * @li The process is not currently running.
345 *
346 * @li Communication to stdin has not been requested in the @ref start() call.
347 *
348 * @li Transmission of data to the child process by a previous call to
349 * @ref writeStdin() is still in progress.
350 *
351 * Please note that the data is sent to the client asynchronously,
352 * so when this function returns, the data might not have been
353 * processed by the child process.
354 *
355 * If all the data has been sent to the client, the signal
356 * @ref wroteStdin() will be emitted.
357 *
358 * Please note that you must not free "buffer" or call @ref writeStdin()
359 * again until either a @ref wroteStdin() signal indicates that the
360 * data has been sent or a @ref processHasExited() signal shows that
361 * the child process is no longer alive...
362 **/
363 bool writeStdin(const char *buffer, int buflen);
364
365 void flushStdin();
366
367 /**
368 * This causes the stdin file descriptor of the child process to be
369 * closed indicating an "EOF" to the child.
370 *
371 * @return @p false if no communication to the process's stdin
372 * had been specified in the call to @ref start().
373 */
374 bool closeStdin();
375
376 /**
377 * This causes the stdout file descriptor of the child process to be
378 * closed.
379 *
380 * @return @p false if no communication to the process's stdout
381 * had been specified in the call to @ref start().
382 */
383 bool closeStdout();
384
385 /**
386 * This causes the stderr file descriptor of the child process to be
387 * closed.
388 *
389 * @return @p false if no communication to the process's stderr
390 * had been specified in the call to @ref start().
391 */
392 bool closeStderr();
393
394 /**
395 * Lets you see what your arguments are for debugging.
396 */
397
398 const QValueList<QCString> &args() { return arguments; }
399
400 /**
401 * Controls whether the started process should drop any
402 * setuid/segid privileges or whether it should keep them
403 *
404 * The default is @p false : drop privileges
405 */
406 void setRunPrivileged(bool keepPrivileges);
407
408 /**
409 * Returns whether the started process will drop any
410 * setuid/segid privileges or whether it will keep them
411 */
412 bool runPrivileged() const;
413
414 /**
415 * Modifies the environment of the process to be started.
416 * This function must be called before starting the process.
417 */
418 void setEnvironment(const QString &name, const QString &value);
419
420 /**
421 * Changes the current working directory (CWD) of the process
422 * to be started.
423 * This function must be called before starting the process.
424 */
425 void setWorkingDirectory(const QString &dir);
426
427 /**
428 * Specify whether to start the command via a shell or directly.
429 * The default is to start the command directly.
430 * If @p useShell is true @p shell will be used as shell, or
431 * if shell is empty, the standard shell is used.
432 * @p quote A flag indicating whether to quote the arguments.
433 *
434 * When using a shell, the caller should make sure that all filenames etc.
435 * are properly quoted when passed as argument.
436 * @see quote()
437 */
438 void setUseShell(bool useShell, const char *shell = 0);
439
440 /**
441 * This function can be used to quote an argument string such that
442 * the shell processes it properly. This is e. g. necessary for
443 * user-provided file names which may contain spaces or quotes.
444 * It also prevents expansion of wild cards and environment variables.
445 */
446 static QString quote(const QString &arg);
447
448 /**
449 * Detaches OProcess from child process. All communication is closed.
450 * No exit notification is emitted any more for the child process.
451 * Deleting the OProcess will no longer kill the child process.
452 * Note that the current process remains the parent process of the
453 * child process.
454 */
455 void detach();
456
457
458
459signals:
460
461 /**
462 * Emitted after the process has terminated when
463 * the process was run in the @p NotifyOnExit (==default option to
464 * @ref start()) or the @ref Block mode.
465 **/
466 void processExited(OProcess *proc);
467
468
469 /**
470 * Emitted, when output from the child process has
471 * been received on stdout.
472 *
473 * To actually get
474 * these signals, the respective communication link (stdout/stderr)
475 * has to be turned on in @ref start().
476 *
477 * @param buffer The data received.
478 * @param buflen The number of bytes that are available.
479 *
480 * You should copy the information contained in @p buffer to your private
481 * data structures before returning from this slot.
482 **/
483 void receivedStdout(OProcess *proc, char *buffer, int buflen);
484
485 /**
486 * Emitted when output from the child process has
487 * been received on stdout.
488 *
489 * To actually get these signals, the respective communications link
490 * (stdout/stderr) has to be turned on in @ref start() and the
491 * @p NoRead flag should have been passed.
492 *
493 * 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
495 * to ensure that this signal is not emitted when no one is connected
496 * to it, otherwise this signal will not be emitted.
497 *
498 * The data still has to be read from file descriptor @p fd.
499 **/
500 void receivedStdout(int fd, int &len);
501
502
503 /**
504 * Emitted, when output from the child process has
505 * been received on stderr.
506 * To actually get
507 * these signals, the respective communication link (stdout/stderr)
508 * has to be turned on in @ref start().
509 *
510 * @param buffer The data received.
511 * @param buflen The number of bytes that are available.
512 *
513 * You should copy the information contained in @p buffer to your private
514 * data structures before returning from this slot.
515 */
516 void receivedStderr(OProcess *proc, char *buffer, int buflen);
517
518 /**
519 * Emitted after all the data that has been
520 * specified by a prior call to @ref writeStdin() has actually been
521 * written to the child process.
522 **/
523 void wroteStdin(OProcess *proc);
524
525
526protected slots:
527
528 /**
529 * This slot gets activated when data from the child's stdout arrives.
530 * It usually calls "childOutput"
531 */
532 void slotChildOutput(int fdno);
533
534 /**
535 * This slot gets activated when data from the child's stderr arrives.
536 * It usually calls "childError"
537 */
538 void slotChildError(int fdno);
539 /*
540 Slot functions for capturing stdout and stderr of the child
541 */
542
543 /**
544 * 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
546 * available, this function must disable the QSocketNotifier "innot".
547 */
548 void slotSendData(int dummy);
549
550protected:
551
552 /**
553 * Sets up the environment according to the data passed via
554 * setEnvironment(...)
555 */
556 void setupEnvironment();
557
558 /**
559 * The list of the process' command line arguments. The first entry
560 * in this list is the executable itself.
561 */
562 QValueList<QCString> arguments;
563 /**
564 * How to run the process (Block, NotifyOnExit, DontCare). You should
565 * not modify this data member directly from derived classes.
566 */
567 RunMode run_mode;
568 /**
569 * true if the process is currently running. You should not
570 * modify this data member directly from derived classes. For
571 * reading the value of this data member, please use "isRunning()"
572 * since "runs" will probably be made private in later versions
573 * of OProcess.
574 */
575 bool runs;
576
577 /**
578 * The PID of the currently running process (see "getPid()").
579 * You should not modify this data member in derived classes.
580 * Please use "getPid()" instead of directly accessing this
581 * member function since it will probably be made private in
582 * later versions of OProcess.
583 */
584 pid_t pid_;
585
586 /**
587 * The process' exit status as returned by "waitpid". You should not
588 * modify the value of this data member from derived classes. You should
589 * rather use @ref exitStatus than accessing this data member directly
590 * since it will probably be made private in further versions of
591 * OProcess.
592 */
593 int status;
594
595
596 /**
597 * See setRunPrivileged()
598 */
599 bool keepPrivs;
600
601 /*
602 Functions for setting up the sockets for communication.
603 setupCommunication
604 -- is called from "start" before "fork"ing.
605 commSetupDoneP
606 -- completes communication socket setup in the parent
607 commSetupDoneC
608 -- completes communication setup in the child process
609 commClose
610 -- frees all allocated communication resources in the parent
611 after the process has exited
612 */
613
614 /**
615 * This function is called from "OProcess::start" right before a "fork" takes
616 * place. According to
617 * the "comm" parameter this function has to initialize the "in", "out" and
618 * "err" data member of OProcess.
619 *
620 * This function should return 0 if setting the needed communication channels
621 * was successful.
622 *
623 * The default implementation is to create UNIX STREAM sockets for the communication,
624 * but you could overload this function and establish a TCP/IP communication for
625 * network communication, for example.
626 */
627 virtual int setupCommunication(Communication comm);
628
629 /**
630 * Called right after a (successful) fork on the parent side. This function
631 * will usually do some communications cleanup, like closing the reading end
632 * of the "stdin" communication channel.
633 *
634 * Furthermore, it must also create the QSocketNotifiers "innot", "outnot" and
635 * "errnot" and connect their Qt slots to the respective OProcess member functions.
636 *
637 * For a more detailed explanation, it is best to have a look at the default
638 * implementation of "setupCommunication" in kprocess.cpp.
639 */
640 virtual int commSetupDoneP();
641
642 /**
643 * Called right after a (successful) fork, but before an "exec" on the child
644 * process' side. It usually just closes the unused communication ends of
645 * "in", "out" and "err" (like the writing end of the "in" communication
646 * channel.
647 */
648 virtual int commSetupDoneC();
649
650
651 /**
652 * Immediately called after a process has exited. This function normally
653 * calls commClose to close all open communication channels to this
654 * process and emits the "processExited" signal (if the process was
655 * not running in the "DontCare" mode).
656 */
657 virtual void processHasExited(int state);
658
659 /**
660 * Should clean up the communication links to the child after it has
661 * exited. Should be called from "processHasExited".
662 */
663 virtual void commClose();
664
665
666 /**
667 * the socket descriptors for stdin/stdout/stderr.
668 */
669 int out[2];
670 int in[2];
671 int err[2];
672
673 /**
674 * The socket notifiers for the above socket descriptors.
675 */
676 QSocketNotifier *innot;
677 QSocketNotifier *outnot;
678 QSocketNotifier *errnot;
679
680 /**
681 * Lists the communication links that are activated for the child
682 * process. Should not be modified from derived classes.
683 */
684 Communication communication;
685
686 /**
687 * Called by "slotChildOutput" this function copies data arriving from the
688 * child process's stdout to the respective buffer and emits the signal
689 * "@ref receivedStderr".
690 */
691 int childOutput(int fdno);
692
693 /**
694 * Called by "slotChildOutput" this function copies data arriving from the
695 * child process's stdout to the respective buffer and emits the signal
696 * "@ref receivedStderr"
697 */
698 int childError(int fdno);
699
700 // information about the data that has to be sent to the child:
701
702 const char *input_data; // the buffer holding the data
703 int input_sent; // # of bytes already transmitted
704 int input_total; // total length of input_data
705
706 /**
707 * @ref OProcessController is a friend of OProcess because it has to have
708 * access to various data members.
709 */
710 friend class OProcessController;
711
712
713private:
714 /**
715 * Searches for a valid shell.
716 * Here is the algorithm used for finding an executable shell:
717 *
718 * @li Try the executable pointed to by the "SHELL" environment
719 * variable with white spaces stripped off
720 *
721 * @li If your process runs with uid != euid or gid != egid, a shell
722 * not listed in /etc/shells will not used.
723 *
724 * @li If no valid shell could be found, "/bin/sh" is used as a last resort.
725 */
726 QCString searchShell();
727
728 /**
729 * Used by @ref searchShell in order to find out whether the shell found
730 * is actually executable at all.
731 */
732 bool isExecutable(const QCString &filename);
733
734 // Disallow assignment and copy-construction
735 OProcess( const OProcess& );
736 OProcess& operator= ( const OProcess& );
737
738private:
739 void init ( );
740
741 OProcessPrivate *d;
742};
743
744
745
746#endif
747