Warning: That file was not part of the compilation database. It may have many parsing errors.
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., 51 Franklin Street, Fifth Floor, |
17 | Boston, MA 02110-1301, USA. |
18 | */ |
19 | |
20 | #ifndef K3PROCESS_H |
21 | #define K3PROCESS_H |
22 | |
23 | #include <kde3support_export.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 KDE3SUPPORT_EXPORT_DEPRECATED 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 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 KDE3SUPPORT_EXPORT_DEPRECATED 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 | |
891 |
Warning: That file was not part of the compilation database. It may have many parsing errors.