summaryrefslogtreecommitdiff
path: root/libopie/oprocess.h
Unidiff
Diffstat (limited to 'libopie/oprocess.h') (more/less context) (ignore whitespace changes)
-rw-r--r--libopie/oprocess.h2
1 files changed, 1 insertions, 1 deletions
diff --git a/libopie/oprocess.h b/libopie/oprocess.h
index ce3c87d..fd726b4 100644
--- a/libopie/oprocess.h
+++ b/libopie/oprocess.h
@@ -1,283 +1,283 @@
1/* This file is part of the KDE libraries 1/* This file is part of the KDE libraries
2 Copyright (C) 1997 Christian Czezakte (e9025461@student.tuwien.ac.at) 2 Copyright (C) 1997 Christian Czezakte (e9025461@student.tuwien.ac.at)
3 3
4 This library is free software; you can redistribute it and/or 4 This library is free software; you can redistribute it and/or
5 modify it under the terms of the GNU Library General Public 5 modify it under the terms of the GNU Library General Public
6 License as published by the Free Software Foundation; either 6 License as published by the Free Software Foundation; either
7 version 2 of the License, or (at your option) any later version. 7 version 2 of the License, or (at your option) any later version.
8 8
9 This library is distributed in the hope that it will be useful, 9 This library is distributed in the hope that it will be useful,
10 but WITHOUT ANY WARRANTY; without even the implied warranty of 10 but WITHOUT ANY WARRANTY; without even the implied warranty of
11 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU 11 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
12 Library General Public License for more details. 12 Library General Public License for more details.
13 13
14 You should have received a copy of the GNU Library General Public License 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 15 along with this library; see the file COPYING.LIB. If not, write to
16 the Free Software Foundation, Inc., 59 Temple Place - Suite 330, 16 the Free Software Foundation, Inc., 59 Temple Place - Suite 330,
17 Boston, MA 02111-1307, USA. 17 Boston, MA 02111-1307, USA.
18*/ 18*/
19// 19//
20// KPROCESS -- A class for handling child processes in KDE without 20// KPROCESS -- A class for handling child processes in KDE without
21// having to take care of Un*x specific implementation details 21// having to take care of Un*x specific implementation details
22// 22//
23// version 0.3.1, Jan 8th 1998 23// version 0.3.1, Jan 8th 1998
24// 24//
25// (C) Christian Czezatke 25// (C) Christian Czezatke
26// e9025461@student.tuwien.ac.at 26// e9025461@student.tuwien.ac.at
27// Ported by Holger Freyther 27// Ported by Holger Freyther to the Open Palmtop Integrated Environment
28// 28//
29 29
30#ifndef __kprocess_h__ 30#ifndef __kprocess_h__
31#define __kprocess_h__ 31#define __kprocess_h__
32 32
33#include <sys/types.h> // for pid_t 33#include <sys/types.h> // for pid_t
34#include <sys/wait.h> 34#include <sys/wait.h>
35#include <signal.h> 35#include <signal.h>
36#include <unistd.h> 36#include <unistd.h>
37#include <qvaluelist.h> 37#include <qvaluelist.h>
38#include <qcstring.h> 38#include <qcstring.h>
39#include <qobject.h> 39#include <qobject.h>
40 40
41class QSocketNotifier; 41class QSocketNotifier;
42class OProcessPrivate; 42class OProcessPrivate;
43 43
44/** 44/**
45 * Child process invocation, monitoring and control. 45 * Child process invocation, monitoring and control.
46 * 46 *
47 * @sect General usage and features 47 * @sect General usage and features
48 * 48 *
49 *This class allows a KDE application to start child processes without having 49 *This class allows a KDE application to start child processes without having
50 *to worry about UN*X signal handling issues and zombie process reaping. 50 *to worry about UN*X signal handling issues and zombie process reaping.
51 * 51 *
52 *@see KProcIO 52 *@see KProcIO
53 * 53 *
54 *Basically, this class distinguishes three different ways of running 54 *Basically, this class distinguishes three different ways of running
55 *child processes: 55 *child processes:
56 * 56 *
57 *@li OProcess::DontCare -- The child process is invoked and both the child 57 *@li OProcess::DontCare -- The child process is invoked and both the child
58 *process and the parent process continue concurrently. 58 *process and the parent process continue concurrently.
59 * 59 *
60 *Starting a DontCare child process means that the application is 60 *Starting a DontCare child process means that the application is
61 *not interested in any notification to determine whether the 61 *not interested in any notification to determine whether the
62 *child process has already exited or not. 62 *child process has already exited or not.
63 * 63 *
64 *@li OProcess::NotifyOnExit -- The child process is invoked and both the 64 *@li OProcess::NotifyOnExit -- The child process is invoked and both the
65 *child and the parent process run concurrently. 65 *child and the parent process run concurrently.
66 * 66 *
67 *When the child process exits, the OProcess instance 67 *When the child process exits, the OProcess instance
68 *corresponding to it emits the Qt signal @ref processExited(). 68 *corresponding to it emits the Qt signal @ref processExited().
69 * 69 *
70 *Since this signal is @em not emitted from within a UN*X 70 *Since this signal is @em not emitted from within a UN*X
71 *signal handler, arbitrary function calls can be made. 71 *signal handler, arbitrary function calls can be made.
72 * 72 *
73 *Be aware: When the OProcess objects gets destructed, the child 73 *Be aware: When the OProcess objects gets destructed, the child
74 *process will be killed if it is still running! 74 *process will be killed if it is still running!
75 *This means in particular, that you cannot use a OProcess on the stack 75 *This means in particular, that you cannot use a OProcess on the stack
76 *with OProcess::NotifyOnExit. 76 *with OProcess::NotifyOnExit.
77 * 77 *
78 *@li OProcess::Block -- The child process starts and the parent process 78 *@li OProcess::Block -- The child process starts and the parent process
79 *is suspended until the child process exits. (@em Really not recommended 79 *is suspended until the child process exits. (@em Really not recommended
80 *for programs with a GUI.) 80 *for programs with a GUI.)
81 * 81 *
82 *OProcess also provides several functions for determining the exit status 82 *OProcess also provides several functions for determining the exit status
83 *and the pid of the child process it represents. 83 *and the pid of the child process it represents.
84 * 84 *
85 *Furthermore it is possible to supply command-line arguments to the process 85 *Furthermore it is possible to supply command-line arguments to the process
86 *in a clean fashion (no null -- terminated stringlists and such...) 86 *in a clean fashion (no null -- terminated stringlists and such...)
87 * 87 *
88 *A small usage example: 88 *A small usage example:
89 *<pre> 89 *<pre>
90 *OProcess *proc = new OProcess; 90 *OProcess *proc = new OProcess;
91 * 91 *
92 **proc << "my_executable"; 92 **proc << "my_executable";
93 **proc << "These" << "are" << "the" << "command" << "line" << "args"; 93 **proc << "These" << "are" << "the" << "command" << "line" << "args";
94 *QApplication::connect(proc, SIGNAL(processExited(OProcess *)), 94 *QApplication::connect(proc, SIGNAL(processExited(OProcess *)),
95 * pointer_to_my_object, SLOT(my_objects_slot(OProcess *))); 95 * pointer_to_my_object, SLOT(my_objects_slot(OProcess *)));
96 *proc->start(); 96 *proc->start();
97 *</pre> 97 *</pre>
98 * 98 *
99 *This will start "my_executable" with the commandline arguments "These"... 99 *This will start "my_executable" with the commandline arguments "These"...
100 * 100 *
101 *When the child process exits, the respective Qt signal will be emitted. 101 *When the child process exits, the respective Qt signal will be emitted.
102 * 102 *
103 *@sect Communication with the child process 103 *@sect Communication with the child process
104 * 104 *
105 *OProcess supports communication with the child process through 105 *OProcess supports communication with the child process through
106 *stdin/stdout/stderr. 106 *stdin/stdout/stderr.
107 * 107 *
108 *The following functions are provided for getting data from the child 108 *The following functions are provided for getting data from the child
109 *process or sending data to the child's stdin (For more information, 109 *process or sending data to the child's stdin (For more information,
110 *have a look at the documentation of each function): 110 *have a look at the documentation of each function):
111 * 111 *
112 *@li bool @ref writeStdin(char *buffer, int buflen); 112 *@li bool @ref writeStdin(char *buffer, int buflen);
113 *@li -- Transmit data to the child process's stdin. 113 *@li -- Transmit data to the child process's stdin.
114 * 114 *
115 *@li bool @ref closeStdin(); 115 *@li bool @ref closeStdin();
116 *@li -- Closes the child process's stdin (which causes it to see an feof(stdin)). 116 *@li -- Closes the child process's stdin (which causes it to see an feof(stdin)).
117 *Returns false if you try to close stdin for a process that has been started 117 *Returns false if you try to close stdin for a process that has been started
118 *without a communication channel to stdin. 118 *without a communication channel to stdin.
119 * 119 *
120 *@li bool @ref closeStdout(); 120 *@li bool @ref closeStdout();
121 *@li -- Closes the child process's stdout. 121 *@li -- Closes the child process's stdout.
122 *Returns false if you try to close stdout for a process that has been started 122 *Returns false if you try to close stdout for a process that has been started
123 *without a communication channel to stdout. 123 *without a communication channel to stdout.
124 * 124 *
125 *@li bool @ref closeStderr(); 125 *@li bool @ref closeStderr();
126 *@li -- Closes the child process's stderr. 126 *@li -- Closes the child process's stderr.
127 *Returns false if you try to close stderr for a process that has been started 127 *Returns false if you try to close stderr for a process that has been started
128 *without a communication channel to stderr. 128 *without a communication channel to stderr.
129 * 129 *
130 * 130 *
131 *@sect QT signals: 131 *@sect QT signals:
132 * 132 *
133 *@li void @ref receivedStdout(OProcess *proc, char *buffer, int buflen); 133 *@li void @ref receivedStdout(OProcess *proc, char *buffer, int buflen);
134 *@li void @ref receivedStderr(OProcess *proc, char *buffer, int buflen); 134 *@li void @ref receivedStderr(OProcess *proc, char *buffer, int buflen);
135 *@li -- Indicates that new data has arrived from either the 135 *@li -- Indicates that new data has arrived from either the
136 *child process's stdout or stderr. 136 *child process's stdout or stderr.
137 * 137 *
138 *@li void @ref wroteStdin(OProcess *proc); 138 *@li void @ref wroteStdin(OProcess *proc);
139 *@li -- Indicates that all data that has been sent to the child process 139 *@li -- Indicates that all data that has been sent to the child process
140 *by a prior call to @ref writeStdin() has actually been transmitted to the 140 *by a prior call to @ref writeStdin() has actually been transmitted to the
141 *client . 141 *client .
142 * 142 *
143 *@author Christian Czezakte e9025461@student.tuwien.ac.at 143 *@author Christian Czezakte e9025461@student.tuwien.ac.at
144 * 144 *
145 * 145 *
146 **/ 146 **/
147class OProcess : public QObject 147class OProcess : public QObject
148{ 148{
149 Q_OBJECT 149 Q_OBJECT
150 150
151public: 151public:
152 152
153 /** 153 /**
154 * Modes in which the communication channel can be opened. 154 * Modes in which the communication channel can be opened.
155 * 155 *
156 * If communication for more than one channel is required, 156 * If communication for more than one channel is required,
157 * the values have to be or'ed together, for example to get 157 * the values have to be or'ed together, for example to get
158 * communication with stdout as well as with stdin, you would 158 * communication with stdout as well as with stdin, you would
159 * specify @p Stdin @p | @p Stdout 159 * specify @p Stdin @p | @p Stdout
160 * 160 *
161 * If @p NoRead is specified in conjunction with @p Stdout, 161 * If @p NoRead is specified in conjunction with @p Stdout,
162 * no data is actually read from @p Stdout but only 162 * no data is actually read from @p Stdout but only
163 * the signal @ref childOutput(int fd) is emitted. 163 * the signal @ref childOutput(int fd) is emitted.
164 */ 164 */
165 enum Communication { NoCommunication = 0, Stdin = 1, Stdout = 2, Stderr = 4, 165 enum Communication { NoCommunication = 0, Stdin = 1, Stdout = 2, Stderr = 4,
166 AllOutput = 6, All = 7, 166 AllOutput = 6, All = 7,
167 NoRead }; 167 NoRead };
168 168
169 /** 169 /**
170 * Run-modes for a child process. 170 * Run-modes for a child process.
171 */ 171 */
172 enum RunMode { 172 enum RunMode {
173 /** 173 /**
174 * The application does not receive notifications from the subprocess when 174 * The application does not receive notifications from the subprocess when
175 * it is finished or aborted. 175 * it is finished or aborted.
176 */ 176 */
177 DontCare, 177 DontCare,
178 /** 178 /**
179 * The application is notified when the subprocess dies. 179 * The application is notified when the subprocess dies.
180 */ 180 */
181 NotifyOnExit, 181 NotifyOnExit,
182 /** 182 /**
183 * The application is suspended until the started process is finished. 183 * The application is suspended until the started process is finished.
184 */ 184 */
185 Block }; 185 Block };
186 186
187 /** 187 /**
188 * Constructor 188 * Constructor
189 */ 189 */
190 OProcess(); 190 OProcess();
191 191
192 /** 192 /**
193 *Destructor: 193 *Destructor:
194 * 194 *
195 * If the process is running when the destructor for this class 195 * If the process is running when the destructor for this class
196 * is called, the child process is killed with a SIGKILL, but 196 * is called, the child process is killed with a SIGKILL, but
197 * only if the run mode is not of type @p DontCare. 197 * only if the run mode is not of type @p DontCare.
198 * Processes started as @p DontCare keep running anyway. 198 * Processes started as @p DontCare keep running anyway.
199 */ 199 */
200 virtual ~OProcess(); 200 virtual ~OProcess();
201 201
202 /** 202 /**
203 @deprecated 203 @deprecated
204 204
205 The use of this function is now deprecated. -- Please use the 205 The use of this function is now deprecated. -- Please use the
206 "operator<<" instead of "setExecutable". 206 "operator<<" instead of "setExecutable".
207 207
208 Sets the executable to be started with this OProcess object. 208 Sets the executable to be started with this OProcess object.
209 Returns false if the process is currently running (in that 209 Returns false if the process is currently running (in that
210 case the executable remains unchanged.) 210 case the executable remains unchanged.)
211 211
212 @see operator<< 212 @see operator<<
213 213
214 */ 214 */
215 bool setExecutable(const QString& proc); 215 bool setExecutable(const QString& proc);
216 216
217 217
218 /** 218 /**
219 * Sets the executable and the command line argument list for this process. 219 * Sets the executable and the command line argument list for this process.
220 * 220 *
221 * For example, doing an "ls -l /usr/local/bin" can be achieved by: 221 * For example, doing an "ls -l /usr/local/bin" can be achieved by:
222 * <pre> 222 * <pre>
223 * OProcess p; 223 * OProcess p;
224 * ... 224 * ...
225 * p << "ls" << "-l" << "/usr/local/bin" 225 * p << "ls" << "-l" << "/usr/local/bin"
226 * </pre> 226 * </pre>
227 * 227 *
228 **/ 228 **/
229 OProcess &operator<<(const QString& arg); 229 OProcess &operator<<(const QString& arg);
230 /** 230 /**
231 * Similar to previous method, takes a char *, supposed to be in locale 8 bit already. 231 * Similar to previous method, takes a char *, supposed to be in locale 8 bit already.
232 */ 232 */
233 OProcess &operator<<(const char * arg); 233 OProcess &operator<<(const char * arg);
234 /** 234 /**
235 * Similar to previous method, takes a QCString, supposed to be in locale 8 bit already. 235 * Similar to previous method, takes a QCString, supposed to be in locale 8 bit already.
236 */ 236 */
237 OProcess &operator<<(const QCString & arg); 237 OProcess &operator<<(const QCString & arg);
238 238
239 /** 239 /**
240 * Sets the executable and the command line argument list for this process, 240 * Sets the executable and the command line argument list for this process,
241 * in a single method call, or add a list of arguments. 241 * in a single method call, or add a list of arguments.
242 **/ 242 **/
243 OProcess &operator<<(const QStringList& args); 243 OProcess &operator<<(const QStringList& args);
244 244
245 /** 245 /**
246 * Clear a command line argument list that has been set by using 246 * Clear a command line argument list that has been set by using
247 * the "operator<<". 247 * the "operator<<".
248 */ 248 */
249 void clearArguments(); 249 void clearArguments();
250 250
251 /** 251 /**
252 * Starts the process. 252 * Starts the process.
253 * For a detailed description of the 253 * For a detailed description of the
254 * various run modes and communication semantics, have a look at the 254 * various run modes and communication semantics, have a look at the
255 * general description of the OProcess class. 255 * general description of the OProcess class.
256 * 256 *
257 * The following problems could cause this function to 257 * The following problems could cause this function to
258 * return false: 258 * return false:
259 * 259 *
260 * @li The process is already running. 260 * @li The process is already running.
261 * @li The command line argument list is empty. 261 * @li The command line argument list is empty.
262 * @li The starting of the process failed (could not fork). 262 * @li The starting of the process failed (could not fork).
263 * @li The executable was not found. 263 * @li The executable was not found.
264 * 264 *
265 * @param comm Specifies which communication links should be 265 * @param comm Specifies which communication links should be
266 * established to the child process (stdin/stdout/stderr). By default, 266 * established to the child process (stdin/stdout/stderr). By default,
267 * no communication takes place and the respective communication 267 * no communication takes place and the respective communication
268 * signals will never get emitted. 268 * signals will never get emitted.
269 * 269 *
270 * @return true on success, false on error 270 * @return true on success, false on error
271 * (see above for error conditions) 271 * (see above for error conditions)
272 **/ 272 **/
273 virtual bool start(RunMode runmode = NotifyOnExit, 273 virtual bool start(RunMode runmode = NotifyOnExit,
274 Communication comm = NoCommunication); 274 Communication comm = NoCommunication);
275 275
276 /** 276 /**
277 * Stop the process (by sending it a signal). 277 * Stop the process (by sending it a signal).
278 * 278 *
279 * @param signoThe signal to send. The default is SIGTERM. 279 * @param signoThe signal to send. The default is SIGTERM.
280 * @return @p true if the signal was delivered successfully. 280 * @return @p true if the signal was delivered successfully.
281 */ 281 */
282 virtual bool kill(int signo = SIGTERM); 282 virtual bool kill(int signo = SIGTERM);
283 283