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
39namespace Poco {
40
41
42class Pipe;
43
44
45class 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{
52public:
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
71protected:
72 ProcessHandle(ProcessHandleImpl* pImpl);
73
74private:
75 ProcessHandle();
76
77 ProcessHandleImpl* _pImpl;
78
79 friend class Process;
80};
81
82
83class Foundation_API Process: public ProcessImpl
84 /// This class provides methods for working with processes.
85{
86public:
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//
251inline Process::PID Process::id()
252{
253 return ProcessImpl::idImpl();
254}
255
256
257inline 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