Mercurial > hg > octave-thorsten

comparison gui/qtermwidget/lib/k3process.h @ 14240:a9992bc3c3f7 gui

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
GUI: Added qtermwidget snapshot as a subproject to build as a library that links with Octave GUI.
author Jacob Dawid <jacob.dawid@googlemail.com>
date Sat, 21 Jan 2012 11:26:36 +0100
parents fd14634f9c1e
children
comparison
equal deleted inserted replaced
14239:7ecaa8a66d5a 14240:a9992bc3c3f7
1 /* This file is part of the KDE libraries
2 Copyright (C) 1997 Christian Czezakte (e9025461@student.tuwien.ac.at)
3
4 Rewritten for QT4 by e_k <e_k at users.sourceforge.net>, Copyright (C)2008
5
6 This library is free software; you can redistribute it and/or
7 modify it under the terms of the GNU Library General Public
8 License as published by the Free Software Foundation; either
9 version 2 of the License, or (at your option) any later version.
10
11 This library is distributed in the hope that it will be useful,
12 but WITHOUT ANY WARRANTY; without even the implied warranty of
13 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
14 Library General Public License for more details.
15
16 You should have received a copy of the GNU Library General Public License
17 along with this library; see the file COPYING.LIB. If not, write to
18 the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor,
19 Boston, MA 02110-1301, USA.
20 */
21
22 #ifndef K3PROCESS_H
23 #define K3PROCESS_H
24
25 #include <QtCore/QObject>
26
27 #include <sys/types.h> // for pid_t
28 #include <sys/wait.h>
29 #include <signal.h>
30 #include <unistd.h>
31
32 class QSocketNotifier;
33 class K3ProcessPrivate;
34 class KPty;
35
36 /**
37 * @obsolete Use KProcess and KPtyProcess instead.
38 *
39 * Child process invocation, monitoring and control.
40 * This class works only in the application's main thread.
41 *
42 * <b>General usage and features:</b>\n
43 *
44 * This class allows a KDE application to start child processes without having
45 * to worry about UN*X signal handling issues and zombie process reaping.
46 *
47 * @see K3ProcIO
48 *
49 * Basically, this class distinguishes three different ways of running
50 * child processes:
51 *
52 * @li DontCare -- The child process is invoked and both the child
53 * process and the parent process continue concurrently.
54 *
55 * The process is started in an own session (see setsid(2)).
56 *
57 * @li NotifyOnExit -- The child process is invoked and both the
58 * child and the parent process run concurrently.
59 *
60 * When the child process exits, the K3Process instance
61 * corresponding to it emits the Qt signal processExited().
62 * Since this signal is @em not emitted from within a UN*X
63 * signal handler, arbitrary function calls can be made.
64 *
65 * Be aware: When the K3Process object gets destructed, the child
66 * process will be killed if it is still running!
67 * This means in particular, that it usually makes no sense to use
68 * a K3Process on the stack with NotifyOnExit.
69 *
70 * @li OwnGroup -- like NotifyOnExit, but the child process is started
71 * in an own process group (and an own session, FWIW). The behavior of
72 * kill() changes to killing the whole process group - this makes
73 * this mode useful for implementing primitive job management. It can be
74 * used to work around broken wrapper scripts that don't propagate signals
75 * to the "real" program. However, use this with care, as you disturb the
76 * shell's job management if your program is started from the command line.
77 *
78 * @li 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 * In this mode the parent can read the child's output, but can't send it any
82 * input.
83 *
84 * K3Process also provides several functions for determining the exit status
85 * and the pid of the child process it represents.
86 *
87 * Furthermore it is possible to supply command-line arguments to the process
88 * in a clean fashion (no null-terminated stringlists and such...)
89 *
90 * A small usage example:
91 * \code
92 * K3Process *proc = new K3Process;
93 *
94 * *proc << "my_executable";
95 * *proc << "These" << "are" << "the" << "command" << "line" << "args";
96 * QApplication::connect(proc, SIGNAL(processExited(K3Process *)),
97 * pointer_to_my_object, SLOT(my_objects_slot(K3Process *)));
98 * proc->start();
99 * \endcode
100 *
101 * This will start "my_executable" with the commandline arguments "These"...
102 *
103 * When the child process exits, the slot will be invoked.
104 *
105 * <b>Communication with the child process:</b>\n
106 *
107 * K3Process supports communication with the child process through
108 * stdin/stdout/stderr.
109 *
110 * The following functions are provided for getting data from the child
111 * process or sending data to the child's stdin (For more information,
112 * have a look at the documentation of each function):
113 *
114 * @li writeStdin()
115 * -- Transmit data to the child process' stdin. When all data was sent, the
116 * signal wroteStdin() is emitted.
117 *
118 * @li When data arrives at stdout or stderr, the signal receivedStdout()
119 * resp. receivedStderr() is emitted.
120 *
121 * @li You can shut down individual communication channels with
122 * closeStdin(), closeStdout(), and closeStderr(), resp.
123 *
124 * @author Christian Czezatke e9025461@student.tuwien.ac.at
125 *
126 **/
127 class K3Process : public QObject
128 {
129 Q_OBJECT
130
131 public:
132
133 /**
134 * Modes in which the communication channels can be opened.
135 *
136 * If communication for more than one channel is required,
137 * the values should be or'ed together, for example to get
138 * communication with stdout as well as with stdin, you would
139 * specify @p Stdin | @p Stdout
140 *
141 */
142 enum CommunicationFlag {
143 NoCommunication = 0, /**< No communication with the process. */
144 Stdin = 1, /**< Connect to write to the process with writeStdin(). */
145 Stdout = 2, /**< Connect to read from the process' output. */
146 Stderr = 4, /**< Connect to read from the process' stderr. */
147 AllOutput = 6, /**< Connects to all output channels. */
148 All = 7, /**< Connects to all channels. */
149 NoRead = 8, /**< If specified with Stdout, no data is actually read from stdout,
150 * only the signal receivedStdout(int fd, int &len) is emitted. */
151 CTtyOnly = NoRead, /**< Tells setUsePty() to create a PTY for the process
152 * and make it the process' controlling TTY, but does not
153 * redirect any I/O channel to the PTY. */
154 MergedStderr = 16 /**< If specified with Stdout, the process' stderr will be
155 * redirected onto the same file handle as its stdout, i.e.,
156 * all error output will be signalled with receivedStdout().
157 * Don't specify Stderr if you specify MergedStderr. */
158 };
159
160 Q_DECLARE_FLAGS(Communication, CommunicationFlag)
161
162 /**
163 * Run-modes for a child process.
164 */
165 enum RunMode {
166 /**
167 * The application does not receive notifications from the subprocess when
168 * it is finished or aborted.
169 */
170 DontCare,
171 /**
172 * The application is notified when the subprocess dies.
173 */
174 NotifyOnExit,
175 /**
176 * The application is suspended until the started process is finished.
177 */
178 Block,
179 /**
180 * Same as NotifyOnExit, but the process is run in an own session,
181 * just like with DontCare.
182 */
183 OwnGroup
184 };
185
186 /**
187 * Constructor
188 */
189 explicit K3Process( QObject* parent=0L );
190
191 /**
192 *Destructor:
193 *
194 * If the process is running when the destructor for this class
195 * is called, the child process is killed with a SIGKILL, but
196 * only if the run mode is not of type @p DontCare.
197 * Processes started as @p DontCare keep running anyway.
198 */
199 virtual ~K3Process();
200
201 /**
202 * Sets the executable and the command line argument list for this process.
203 *
204 * For example, doing an "ls -l /usr/local/bin" can be achieved by:
205 * \code
206 * K3Process p;
207 * ...
208 * p << "ls" << "-l" << "/usr/local/bin"
209 * \endcode
210 *
211 * @param arg the argument to add
212 * @return a reference to this K3Process
213 **/
214 K3Process &operator<<(const QString& arg);
215 /**
216 * Similar to previous method, takes a char *, supposed to be in locale 8 bit already.
217 */
218 K3Process &operator<<(const char * arg);
219 /**
220 * Similar to previous method, takes a QByteArray, supposed to be in locale 8 bit already.
221 * @param arg the argument to add
222 * @return a reference to this K3Process
223 */
224 K3Process &operator<<(const QByteArray & arg);
225
226 /**
227 * Sets the executable and the command line argument list for this process,
228 * in a single method call, or add a list of arguments.
229 * @param args the arguments to add
230 * @return a reference to this K3Process
231 **/
232 K3Process &operator<<(const QStringList& args);
233
234 /**
235 * Clear a command line argument list that has been set by using
236 * operator<<.
237 */
238 void clearArguments();
239
240 /**
241 * Starts the process.
242 * For a detailed description of the
243 * various run modes and communication semantics, have a look at the
244 * general description of the K3Process class. Note that if you use
245 * setUsePty( Stdout | Stderr, \<bool\> ), you cannot use Stdout | Stderr
246 * here - instead, use Stdout only to receive the mixed output.
247 *
248 * The following problems could cause this function to
249 * return false:
250 *
251 * @li The process is already running.
252 * @li The command line argument list is empty.
253 * @li The the @p comm parameter is incompatible with the selected pty usage.
254 * @li The starting of the process failed (could not fork).
255 * @li The executable was not found.
256 *
257 * @param runmode The Run-mode for the process.
258 * @param comm Specifies which communication channels should be
259 * established to the child process (stdin/stdout/stderr). By default,
260 * no communication takes place and the respective communication
261 * signals will never get emitted.
262 *
263 * @return true on success, false on error
264 * (see above for error conditions)
265 **/
266 virtual bool start(RunMode runmode = NotifyOnExit,
267 Communication comm = NoCommunication);
268
269 /**
270 * Stop the process (by sending it a signal).
271 *
272 * @param signo The signal to send. The default is SIGTERM.
273 * @return true if the signal was delivered successfully.
274 */
275 virtual bool kill(int signo = SIGTERM);
276
277 /**
278 * Checks whether the process is running.
279 * @return true if the process is (still) considered to be running
280 */
281 bool isRunning() const;
282
283 /** Returns the process id of the process.
284 *
285 * If it is called after
286 * the process has exited, it returns the process id of the last
287 * child process that was created by this instance of K3Process.
288 *
289 * Calling it before any child process has been started by this
290 * K3Process instance causes pid() to return 0.
291 * @return the pid of the process or 0 if no process has been started yet.
292 **/
293 pid_t pid() const;
294
295 /**
296 * Suspend processing of data from stdout of the child process.
297 */
298 void suspend();
299
300 /**
301 * Resume processing of data from stdout of the child process.
302 */
303 void resume();
304
305 /**
306 * Suspend execution of the current thread until the child process dies
307 * or the timeout hits. This function is not recommended for programs
308 * with a GUI.
309 * @param timeout timeout in seconds. -1 means wait indefinitely.
310 * @return true if the process exited, false if the timeout hit.
311 */
312 bool wait(int timeout = -1);
313
314 /**
315 * Checks whether the process exited cleanly.
316 *
317 * @return true if the process has already finished and has exited
318 * "voluntarily", ie: it has not been killed by a signal.
319 */
320 bool normalExit() const;
321
322 /**
323 * Checks whether the process was killed by a signal.
324 *
325 * @return true if the process has already finished and has not exited
326 * "voluntarily", ie: it has been killed by a signal.
327 */
328 bool signalled() const;
329
330 /**
331 * Checks whether a killed process dumped core.
332 *
333 * @return true if signalled() returns true and the process
334 * dumped core. Note that on systems that don't define the
335 * WCOREDUMP macro, the return value is always false.
336 */
337 bool coreDumped() const;
338
339 /**
340 * Returns the exit status of the process.
341 *
342 * @return the exit status of the process. Note that this value
343 * is not valid if normalExit() returns false.
344 */
345 int exitStatus() const;
346
347 /**
348 * Returns the signal the process was killed by.
349 *
350 * @return the signal number that caused the process to exit.
351 * Note that this value is not valid if signalled() returns false.
352 */
353 int exitSignal() const;
354
355 /**
356 * Transmit data to the child process' stdin.
357 *
358 * This function may return false in the following cases:
359 *
360 * @li The process is not currently running.
361 * This implies that you cannot use this function in Block mode.
362 *
363 * @li Communication to stdin has not been requested in the start() call.
364 *
365 * @li Transmission of data to the child process by a previous call to
366 * writeStdin() is still in progress.
367 *
368 * Please note that the data is sent to the client asynchronously,
369 * so when this function returns, the data might not have been
370 * processed by the child process.
371 * That means that you must not free @p buffer or call writeStdin()
372 * again until either a wroteStdin() signal indicates that the
373 * data has been sent or a processExited() signal shows that
374 * the child process is no longer alive.
375 *
376 * If all the data has been sent to the client, the signal
377 * wroteStdin() will be emitted.
378 *
379 * This function does not work when the process is start()ed in Block mode.
380 *
381 * @param buffer the buffer to write
382 * @param buflen the length of the buffer
383 * @return false if an error has occurred
384 **/
385 bool writeStdin(const char *buffer, int buflen);
386
387 /**
388 * Shuts down the Stdin communication link. If no pty is used, this
389 * causes "EOF" to be indicated on the child's stdin file descriptor.
390 *
391 * @return false if no Stdin communication link exists (any more).
392 */
393 bool closeStdin();
394
395 /**
396 * Shuts down the Stdout communication link. If no pty is used, any further
397 * attempts by the child to write to its stdout file descriptor will cause
398 * it to receive a SIGPIPE.
399 *
400 * @return false if no Stdout communication link exists (any more).
401 */
402 bool closeStdout();
403
404 /**
405 * Shuts down the Stderr communication link. If no pty is used, any further
406 * attempts by the child to write to its stderr file descriptor will cause
407 * it to receive a SIGPIPE.
408 *
409 * @return false if no Stderr communication link exists (any more).
410 */
411 bool closeStderr();
412
413 /**
414 * Deletes the optional utmp entry and closes the pty.
415 *
416 * Make sure to shut down any communication links that are using the pty
417 * before calling this function.
418 *
419 * @return false if the pty is not open (any more).
420 */
421 bool closePty();
422
423 /**
424 * @brief Close stdin, stdout, stderr and the pty
425 *
426 * This is the same that calling all close* functions in a row:
427 * @see closeStdin, @see closeStdout, @see closeStderr and @see closePty
428 */
429 void closeAll();
430
431 /**
432 * Lets you see what your arguments are for debugging.
433 * @return the list of arguments
434 */
435 const QList<QByteArray> &args() /* const */ { return arguments; }
436
437 /**
438 * Controls whether the started process should drop any
439 * setuid/setgid privileges or whether it should keep them.
440 * Note that this function is mostly a dummy, as the KDE libraries
441 * currently refuse to run with setuid/setgid privileges.
442 *
443 * The default is false: drop privileges
444 * @param keepPrivileges true to keep the privileges
445 */
446 void setRunPrivileged(bool keepPrivileges);
447
448 /**
449 * Returns whether the started process will drop any
450 * setuid/setgid privileges or whether it will keep them.
451 * @return true if the process runs privileged
452 */
453 bool runPrivileged() const;
454
455 /**
456 * Adds the variable @p name to the process' environment.
457 * This function must be called before starting the process.
458 * @param name the name of the environment variable
459 * @param value the new value for the environment variable
460 */
461 void setEnvironment(const QString &name, const QString &value);
462
463 /**
464 * Changes the current working directory (CWD) of the process
465 * to be started.
466 * This function must be called before starting the process.
467 * @param dir the new directory
468 */
469 void setWorkingDirectory(const QString &dir);
470
471 /**
472 * Specify whether to start the command via a shell or directly.
473 * The default is to start the command directly.
474 * If @p useShell is true @p shell will be used as shell, or
475 * if shell is empty, /bin/sh will be used.
476 *
477 * When using a shell, the caller should make sure that all filenames etc.
478 * are properly quoted when passed as argument.
479 * @see quote()
480 * @param useShell true if the command should be started via a shell
481 * @param shell the path to the shell that will execute the process, or
482 * 0 to use /bin/sh. Use getenv("SHELL") to use the user's
483 * default shell, but note that doing so is usually a bad idea
484 * for shell compatibility reasons.
485 */
486 void setUseShell(bool useShell, const char *shell = 0);
487
488 /**
489 * This function can be used to quote an argument string such that
490 * the shell processes it properly. This is e. g. necessary for
491 * user-provided file names which may contain spaces or quotes.
492 * It also prevents expansion of wild cards and environment variables.
493 * @param arg the argument to quote
494 * @return the quoted argument
495 */
496 static QString quote(const QString &arg);
497
498 /**
499 * Detaches K3Process from child process. All communication is closed.
500 * No exit notification is emitted any more for the child process.
501 * Deleting the K3Process will no longer kill the child process.
502 * Note that the current process remains the parent process of the
503 * child process.
504 */
505 void detach();
506
507 /**
508 * Specify whether to create a pty (pseudo-terminal) for running the
509 * command.
510 * This function should be called before starting the process.
511 *
512 * @param comm for which stdio handles to use a pty. Note that it is not
513 * allowed to specify Stdout and Stderr at the same time both here and to
514 * start (there is only one pty, so they cannot be distinguished).
515 * @param addUtmp true if a utmp entry should be created for the pty
516 */
517 void setUsePty(Communication comm, bool addUtmp);
518
519 /**
520 * Obtains the pty object used by this process. The return value is
521 * valid only after setUsePty() was used with a non-zero argument.
522 * The pty is open only while the process is running.
523 * @return a pointer to the pty object
524 */
525 KPty *pty() const;
526
527 /**
528 * More or less intuitive constants for use with setPriority().
529 */
530 enum { PrioLowest = 20, PrioLow = 10, PrioLower = 5, PrioNormal = 0,
531 PrioHigher = -5, PrioHigh = -10, PrioHighest = -19 };
532
533 /**
534 * Sets the scheduling priority of the process.
535 * @param prio the new priority in the range -20 (high) to 19 (low).
536 * @return false on error; see setpriority(2) for possible reasons.
537 */
538 bool setPriority(int prio);
539
540 Q_SIGNALS:
541 /**
542 * Emitted after the process has terminated when
543 * the process was run in the @p NotifyOnExit (==default option to
544 * start() ) or the Block mode.
545 * @param proc a pointer to the process that has exited
546 **/
547 void processExited(K3Process *proc);
548
549
550 /**
551 * Emitted, when output from the child process has
552 * been received on stdout.
553 *
554 * To actually get this signal, the Stdout communication link
555 * has to be turned on in start().
556 *
557 * @param proc a pointer to the process that has received the output
558 * @param buffer The data received.
559 * @param buflen The number of bytes that are available.
560 *
561 * You should copy the information contained in @p buffer to your private
562 * data structures before returning from the slot.
563 * Example:
564 * \code
565 * QString myBuf = QLatin1String(buffer, buflen);
566 * \endcode
567 **/
568 void receivedStdout(K3Process *proc, char *buffer, int buflen);
569
570 /**
571 * Emitted when output from the child process has
572 * been received on stdout.
573 *
574 * To actually get this signal, the Stdout communication link
575 * has to be turned on in start() and the
576 * NoRead flag must have been passed.
577 *
578 * You will need to explicitly call resume() after your call to start()
579 * to begin processing data from the child process' stdout. This is
580 * to ensure that this signal is not emitted when no one is connected
581 * to it, otherwise this signal will not be emitted.
582 *
583 * The data still has to be read from file descriptor @p fd.
584 * @param fd the file descriptor that provides the data
585 * @param len the number of bytes that have been read from @p fd must
586 * be written here
587 **/
588 void receivedStdout(int fd, int &len); // KDE4: change, broken API
589
590
591 /**
592 * Emitted, when output from the child process has
593 * been received on stderr.
594 *
595 * To actually get this signal, the Stderr communication link
596 * has to be turned on in start().
597 *
598 * You should copy the information contained in @p buffer to your private
599 * data structures before returning from the slot.
600 *
601 * @param proc a pointer to the process that has received the data
602 * @param buffer The data received.
603 * @param buflen The number of bytes that are available.
604 **/
605 void receivedStderr(K3Process *proc, char *buffer, int buflen);
606
607 /**
608 * Emitted after all the data that has been
609 * specified by a prior call to writeStdin() has actually been
610 * written to the child process.
611 * @param proc a pointer to the process
612 **/
613 void wroteStdin(K3Process *proc);
614
615
616 protected Q_SLOTS:
617
618 /**
619 * This slot gets activated when data from the child's stdout arrives.
620 * It usually calls childOutput().
621 * @param fdno the file descriptor for the output
622 */
623 void slotChildOutput(int fdno);
624
625 /**
626 * This slot gets activated when data from the child's stderr arrives.
627 * It usually calls childError().
628 * @param fdno the file descriptor for the output
629 */
630 void slotChildError(int fdno);
631
632 /**
633 * Called when another bulk of data can be sent to the child's
634 * stdin. If there is no more data to be sent to stdin currently
635 * available, this function must disable the QSocketNotifier innot.
636 * @param dummy ignore this argument
637 */
638 void slotSendData(int dummy); // KDE 4: remove dummy
639
640 protected:
641
642 /**
643 * Sets up the environment according to the data passed via
644 * setEnvironment()
645 */
646 void setupEnvironment();
647
648 /**
649 * The list of the process' command line arguments. The first entry
650 * in this list is the executable itself.
651 */
652 QList<QByteArray> arguments;
653 /**
654 * How to run the process (Block, NotifyOnExit, DontCare). You should
655 * not modify this data member directly from derived classes.
656 */
657 RunMode run_mode;
658 /**
659 * true if the process is currently running. You should not
660 * modify this data member directly from derived classes. Please use
661 * isRunning() for reading the value of this data member since it
662 * will probably be made private in later versions of K3Process.
663 */
664 bool runs;
665
666 /**
667 * The PID of the currently running process.
668 * You should not modify this data member in derived classes.
669 * Please use pid() instead of directly accessing this
670 * member since it will probably be made private in
671 * later versions of K3Process.
672 */
673 pid_t pid_;
674
675 /**
676 * The process' exit status as returned by waitpid(). You should not
677 * modify the value of this data member from derived classes. You should
678 * rather use exitStatus() than accessing this data member directly
679 * since it will probably be made private in further versions of
680 * K3Process.
681 */
682 int status;
683
684
685 /**
686 * If false, the child process' effective uid & gid will be reset to the
687 * real values.
688 * @see setRunPrivileged()
689 */
690 bool keepPrivs;
691
692 /**
693 * This function is called from start() right before a fork() takes
694 * place. According to the @p comm parameter this function has to initialize
695 * the in, out and err data members of K3Process.
696 *
697 * This function should return 1 if setting the needed communication channels
698 * was successful.
699 *
700 * The default implementation is to create UNIX STREAM sockets for the
701 * communication, but you could reimplement this function to establish a
702 * TCP/IP communication for network communication, for example.
703 */
704 virtual int setupCommunication(Communication comm);
705
706 /**
707 * Called right after a (successful) fork() on the parent side. This function
708 * will usually do some communications cleanup, like closing in[0],
709 * out[1] and out[1].
710 *
711 * Furthermore, it must also create the QSocketNotifiers innot,
712 * outnot and errnot and connect their Qt signals to the respective
713 * K3Process slots.
714 *
715 * For a more detailed explanation, it is best to have a look at the default
716 * implementation in kprocess.cpp.
717 */
718 virtual int commSetupDoneP();
719
720 /**
721 * Called right after a (successful) fork(), but before an exec() on the child
722 * process' side. It usually duplicates the in[0], out[1] and
723 * err[1] file handles to the respective standard I/O handles.
724 */
725 virtual int commSetupDoneC();
726
727
728 /**
729 * Immediately called after a successfully started process in NotifyOnExit
730 * mode has exited. This function normally calls commClose()
731 * and emits the processExited() signal.
732 * @param state the exit code of the process as returned by waitpid()
733 */
734 virtual void processHasExited(int state);
735
736 /**
737 * Cleans up the communication links to the child after it has exited.
738 * This function should act upon the values of pid() and runs.
739 * See the kprocess.cpp source for details.
740 * @li If pid() returns zero, the communication links should be closed
741 * only.
742 * @li if pid() returns non-zero and runs is false, all data
743 * immediately available from the communication links should be processed
744 * before closing them.
745 * @li if pid() returns non-zero and runs is true, the communication
746 * links should be monitored for data until the file handle returned by
747 * K3ProcessController::theKProcessController->notifierFd() becomes ready
748 * for reading - when it triggers, runs should be reset to false, and
749 * the function should be immediately left without closing anything.
750 *
751 * The previous semantics of this function are forward-compatible, but should
752 * be avoided, as they are prone to race conditions and can cause K3Process
753 * (and thus the whole program) to lock up under certain circumstances. At the
754 * end the function closes the communication links in any case. Additionally
755 * @li if runs is true, the communication links are monitored for data
756 * until all of them have returned EOF. Note that if any system function is
757 * interrupted (errno == EINTR) the polling loop should be aborted.
758 * @li if runs is false, all data immediately available from the
759 * communication links is processed.
760 */
761 virtual void commClose();
762
763 /* KDE 4 - commClose will be changed to perform cleanup only in all cases *
764 * If @p notfd is -1, all data immediately available from the
765 * communication links should be processed.
766 * If @p notfd is not -1, the communication links should be monitored
767 * for data until the file handle @p notfd becomes ready for reading.
768 */
769 // virtual void commDrain(int notfd);
770
771 /**
772 * Specify the actual executable that should be started (first argument to execve)
773 * Normally the the first argument is the executable but you can
774 * override that with this function.
775 */
776 void setBinaryExecutable(const char *filename);
777
778 /**
779 * The socket descriptors for stdout.
780 */
781 int out[2];
782 /**
783 * The socket descriptors for stdin.
784 */
785 int in[2];
786 /**
787 * The socket descriptors for stderr.
788 */
789 int err[2];
790
791 /**
792 * The socket notifier for in[1].
793 */
794 QSocketNotifier *innot;
795 /**
796 * The socket notifier for out[0].
797 */
798 QSocketNotifier *outnot;
799 /**
800 * The socket notifier for err[0].
801 */
802 QSocketNotifier *errnot;
803
804 /**
805 * Lists the communication links that are activated for the child
806 * process. Should not be modified from derived classes.
807 */
808 Communication communication;
809
810 /**
811 * Called by slotChildOutput() this function copies data arriving from
812 * the child process' stdout to the respective buffer and emits the signal
813 * receivedStdout().
814 */
815 int childOutput(int fdno);
816
817 /**
818 * Called by slotChildError() this function copies data arriving from
819 * the child process' stderr to the respective buffer and emits the signal
820 * receivedStderr().
821 */
822 int childError(int fdno);
823
824 /**
825 * The buffer holding the data that has to be sent to the child
826 */
827 const char *input_data;
828 /**
829 * The number of bytes already transmitted
830 */
831 int input_sent;
832 /**
833 * The total length of input_data
834 */
835 int input_total;
836
837 /**
838 * K3ProcessController is a friend of K3Process because it has to have
839 * access to various data members.
840 */
841 friend class K3ProcessController;
842
843 private:
844 K3ProcessPrivate* const d;
845 };
846
847 Q_DECLARE_OPERATORS_FOR_FLAGS(K3Process::Communication)
848
849 class K3ShellProcessPrivate;
850
851 /**
852 * @obsolete
853 *
854 * Use K3Process and K3Process::setUseShell(true) instead.
855 *
856 * @short A class derived from K3Process to start child
857 * processes through a shell.
858 * @author Christian Czezatke <e9025461@student.tuwien.ac.at>
859 */
860 class K3ShellProcess : public K3Process
861 {
862 Q_OBJECT
863
864 public:
865
866 /**
867 * Constructor
868 *
869 * If no shellname is specified, the user's default shell is used.
870 */
871 explicit K3ShellProcess(const char *shellname=0);
872
873 /**
874 * Destructor.
875 */
876 ~K3ShellProcess();
877
878 virtual bool start(RunMode runmode = NotifyOnExit,
879 Communication comm = NoCommunication);
880
881 static QString quote(const QString &arg);
882
883 private:
884 K3ShellProcessPrivate* const d;
885 };
886
887
888
889 #endif
890