-rw-r--r-- | libopie/oprocess.h | 2 |
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 | ||
41 | class QSocketNotifier; | 41 | class QSocketNotifier; |
42 | class OProcessPrivate; | 42 | class 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 | **/ |
147 | class OProcess : public QObject | 147 | class OProcess : public QObject |
148 | { | 148 | { |
149 | Q_OBJECT | 149 | Q_OBJECT |
150 | 150 | ||
151 | public: | 151 | public: |
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 | ||