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