1 | // |
2 | // Process.h |
3 | // |
4 | // Library: Foundation |
5 | // Package: Processes |
6 | // Module: Process |
7 | // |
8 | // Definition of the Process class. |
9 | // |
10 | // Copyright (c) 2004-2006, Applied Informatics Software Engineering GmbH. |
11 | // and Contributors. |
12 | // |
13 | // SPDX-License-Identifier: BSL-1.0 |
14 | // |
15 | |
16 | |
17 | #ifndef Foundation_Process_INCLUDED |
18 | #define Foundation_Process_INCLUDED |
19 | |
20 | |
21 | #include "Poco/Foundation.h" |
22 | |
23 | |
24 | #if defined(POCO_OS_FAMILY_WINDOWS) |
25 | #if defined(_WIN32_WCE) |
26 | #include "Process_WINCE.h" |
27 | #else |
28 | #include "Poco/Process_WIN32.h" |
29 | #endif |
30 | #elif defined(POCO_VXWORKS) |
31 | #include "Poco/Process_VX.h" |
32 | #elif defined(POCO_OS_FAMILY_UNIX) |
33 | #include "Poco/Process_UNIX.h" |
34 | #else |
35 | #include "Poco/Process_VMS.h" |
36 | #endif |
37 | |
38 | |
39 | namespace Poco { |
40 | |
41 | |
42 | class Pipe; |
43 | |
44 | |
45 | class Foundation_API ProcessHandle |
46 | /// A handle for a process created with Process::launch(). |
47 | /// |
48 | /// This handle can be used to determine the process ID of |
49 | /// the newly created process and it can be used to wait for |
50 | /// the completion of a process. |
51 | { |
52 | public: |
53 | typedef ProcessImpl::PIDImpl PID; |
54 | |
55 | ProcessHandle(const ProcessHandle& handle); |
56 | /// Creates a ProcessHandle by copying another one. |
57 | |
58 | ~ProcessHandle(); |
59 | /// Destroys the ProcessHandle. |
60 | |
61 | ProcessHandle& operator = (const ProcessHandle& handle); |
62 | /// Assigns another handle. |
63 | |
64 | PID id() const; |
65 | /// Returns the process ID. |
66 | |
67 | int wait() const; |
68 | /// Waits for the process to terminate |
69 | /// and returns the exit code of the process. |
70 | |
71 | protected: |
72 | ProcessHandle(ProcessHandleImpl* pImpl); |
73 | |
74 | private: |
75 | ProcessHandle(); |
76 | |
77 | ProcessHandleImpl* _pImpl; |
78 | |
79 | friend class Process; |
80 | }; |
81 | |
82 | |
83 | class Foundation_API Process: public ProcessImpl |
84 | /// This class provides methods for working with processes. |
85 | { |
86 | public: |
87 | typedef PIDImpl PID; |
88 | typedef ArgsImpl Args; |
89 | typedef EnvImpl Env; |
90 | |
91 | static PID id(); |
92 | /// Returns the process ID of the current process. |
93 | |
94 | static void times(long& userTime, long& kernelTime); |
95 | /// Returns the number of seconds spent by the |
96 | /// current process in user and kernel mode. |
97 | |
98 | static ProcessHandle launch(const std::string& command, const Args& args); |
99 | /// Creates a new process for the given command and returns |
100 | /// a ProcessHandle of the new process. The given arguments are |
101 | /// passed to the command on the command line. |
102 | |
103 | static ProcessHandle launch( |
104 | const std::string& command, |
105 | const Args& args, |
106 | const std::string& initialDirectory); |
107 | /// Creates a new process for the given command and returns |
108 | /// a ProcessHandle of the new process. The given arguments are |
109 | /// passed to the command on the command line. |
110 | /// The process starts executing in the specified initial directory. |
111 | |
112 | static ProcessHandle launch( |
113 | const std::string& command, |
114 | const Args& args, |
115 | Pipe* inPipe, |
116 | Pipe* outPipe, |
117 | Pipe* errPipe); |
118 | /// Creates a new process for the given command and returns |
119 | /// a ProcessHandle of the new process. The given arguments are |
120 | /// passed to the command on the command line. |
121 | /// |
122 | /// If inPipe, outPipe or errPipe is non-null, the corresponding |
123 | /// standard input, standard output or standard error stream |
124 | /// of the launched process is redirected to the Pipe. |
125 | /// PipeInputStream or PipeOutputStream can be used to |
126 | /// send receive data from, or send data to the process. |
127 | /// |
128 | /// Note: the same Pipe can be used for both outPipe and errPipe. |
129 | /// |
130 | /// After a Pipe has been passed as inPipe, only write operations |
131 | /// are valid. After a Pipe has been passed as outPipe or errPipe, |
132 | /// only read operations are valid. |
133 | /// |
134 | /// It is forbidden to pass the same pipe as inPipe and outPipe or errPipe. |
135 | /// |
136 | /// Usage example: |
137 | /// Pipe outPipe; |
138 | /// Process::Args args; |
139 | /// ProcessHandle ph(launch("/bin/ps", args, 0, &outPipe, 0)); |
140 | /// PipeInputStream istr(outPipe); |
141 | /// ... // read output of ps from istr |
142 | /// int rc = ph.wait(); |
143 | |
144 | static ProcessHandle launch( |
145 | const std::string& command, |
146 | const Args& args, |
147 | const std::string& initialDirectory, |
148 | Pipe* inPipe, |
149 | Pipe* outPipe, |
150 | Pipe* errPipe); |
151 | /// Creates a new process for the given command and returns |
152 | /// a ProcessHandle of the new process. The given arguments are |
153 | /// passed to the command on the command line. |
154 | /// The process starts executing in the specified initial directory. |
155 | /// |
156 | /// If inPipe, outPipe or errPipe is non-null, the corresponding |
157 | /// standard input, standard output or standard error stream |
158 | /// of the launched process is redirected to the Pipe. |
159 | /// PipeInputStream or PipeOutputStream can be used to |
160 | /// send receive data from, or send data to the process. |
161 | /// |
162 | /// Note: the same Pipe can be used for both outPipe and errPipe. |
163 | /// |
164 | /// After a Pipe has been passed as inPipe, only write operations |
165 | /// are valid. After a Pipe has been passed as outPipe or errPipe, |
166 | /// only read operations are valid. |
167 | /// |
168 | /// It is forbidden to pass the same pipe as inPipe and outPipe or errPipe. |
169 | /// |
170 | /// Usage example: |
171 | /// Pipe outPipe; |
172 | /// Process::Args args; |
173 | /// ProcessHandle ph(launch("/bin/ps", args, 0, &outPipe, 0)); |
174 | /// PipeInputStream istr(outPipe); |
175 | /// ... // read output of ps from istr |
176 | /// int rc = ph.wait(); |
177 | |
178 | static ProcessHandle launch( |
179 | const std::string& command, |
180 | const Args& args, |
181 | Pipe* inPipe, |
182 | Pipe* outPipe, |
183 | Pipe* errPipe, |
184 | const Env& env); |
185 | /// Creates a new process for the given command and returns |
186 | /// a ProcessHandle of the new process. The given arguments are |
187 | /// passed to the command on the command line. |
188 | /// |
189 | /// If inPipe, outPipe or errPipe is non-null, the corresponding |
190 | /// standard input, standard output or standard error stream |
191 | /// of the launched process is redirected to the Pipe. |
192 | /// |
193 | /// The launched process is given the specified environment variables. |
194 | |
195 | static ProcessHandle launch( |
196 | const std::string& command, |
197 | const Args& args, |
198 | const std::string& initialDirectory, |
199 | Pipe* inPipe, |
200 | Pipe* outPipe, |
201 | Pipe* errPipe, |
202 | const Env& env); |
203 | /// Creates a new process for the given command and returns |
204 | /// a ProcessHandle of the new process. The given arguments are |
205 | /// passed to the command on the command line. |
206 | /// The process starts executing in the specified initial directory. |
207 | /// If inPipe, outPipe or errPipe is non-null, the corresponding |
208 | /// standard input, standard output or standard error stream |
209 | /// of the launched process is redirected to the Pipe. |
210 | /// The launched process is given the specified environment variables. |
211 | |
212 | static int wait(const ProcessHandle& handle); |
213 | /// Waits for the process specified by handle to terminate |
214 | /// and returns the exit code of the process. |
215 | |
216 | static bool isRunning(const ProcessHandle& handle); |
217 | /// check if the process specified by handle is running or not |
218 | /// |
219 | /// This is preferable on Windows where process IDs |
220 | /// may be reused. |
221 | |
222 | static bool isRunning(PID pid); |
223 | /// Check if the process specified by given pid is running or not. |
224 | |
225 | static void kill(ProcessHandle& handle); |
226 | /// Kills the process specified by handle. |
227 | /// |
228 | /// This is preferable on Windows where process IDs |
229 | /// may be reused. |
230 | |
231 | static void kill(PID pid); |
232 | /// Kills the process with the given pid. |
233 | |
234 | static void requestTermination(PID pid); |
235 | /// Requests termination of the process with the give PID. |
236 | /// |
237 | /// On Unix platforms, this will send a SIGINT to the |
238 | /// process and thus work with arbitrary processes. |
239 | /// |
240 | /// On other platforms, a global event flag |
241 | /// will be set. Setting the flag will cause |
242 | /// Util::ServerApplication::waitForTerminationRequest() to |
243 | /// return. Therefore this will only work with applications |
244 | /// based on Util::ServerApplication. |
245 | }; |
246 | |
247 | |
248 | // |
249 | // inlines |
250 | // |
251 | inline Process::PID Process::id() |
252 | { |
253 | return ProcessImpl::idImpl(); |
254 | } |
255 | |
256 | |
257 | inline void Process::times(long& userTime, long& kernelTime) |
258 | { |
259 | ProcessImpl::timesImpl(userTime, kernelTime); |
260 | } |
261 | |
262 | |
263 | } // namespace Poco |
264 | |
265 | |
266 | #endif // Foundation_Process_INCLUDED |
267 | |