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 | |
---|