MauiKit Terminal

ProcessInfo.h
1/*
2 SPDX-FileCopyrightText: 2007-2008 Robert Knight <robertknight@gmail.com>
3
4 SPDX-License-Identifier: GPL-2.0-or-later
5
6 This program is distributed in the hope that it will be useful,
7 but WITHOUT ANY WARRANTY; without even the implied warranty of
8 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
9 GNU General Public License for more details.
10
11 You should have received a copy of the GNU General Public License
12 along with this program; if not, write to the Free Software
13 Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA
14 02110-1301 USA.
15*/
16
17#ifndef PROCESSINFO_H
18#define PROCESSINFO_H
19
20// Qt
21#include <QtCore/QFile>
22#include <QtCore/QMap>
23#include <QtCore/QString>
24#include <QtCore/QVector>
25
26// std
27#include <memory>
28
29namespace Konsole
30{
31/**
32 * Takes a snapshot of the state of a process and provides access to
33 * information such as the process name, parent process,
34 * the foreground process in the controlling terminal,
35 * the arguments with which the process was started and the
36 * environment.
37 *
38 * To create a new snapshot, construct a new ProcessInfo instance,
39 * using ProcessInfo::newInstance(),
40 * passing the process identifier of the process you are interested in.
41 *
42 * After creating a new instance, call the update() method to take a
43 * snapshot of the current state of the process.
44 *
45 * Before calling any additional methods, check that the process state
46 * was read successfully using the isValid() method.
47 *
48 * Each accessor method which provides information about the process state ( such as pid(),
49 * currentDir(), name() ) takes a pointer to a boolean as an argument. If the information
50 * requested was read successfully then the boolean is set to true, otherwise it is set
51 * to false, in which case the return value from the function should be ignored.
52 * If this boolean is set to false, it may indicate an error reading the process information,
53 * or it may indicate that the information is not available on the current platform.
54 *
55 * eg.
56 *
57 * @code
58 * ProcessInfo* info = ProcessInfo::newInstance(pid);
59 * info->update();
60 *
61 * if ( info->isValid() )
62 * {
63 * bool ok;
64 *
65 * QString name = info->name(&ok);
66 * if ( ok ) qDebug() << "process name - " << name;
67 * int parentPid = info->parentPid(&ok);
68 * if ( ok ) qDebug() << "parent process - " << parentPid;
69 * int foregroundPid = info->foregroundPid(&ok);
70 * if ( ok ) qDebug() << "foreground process - " << foregroundPid;
71 * }
72 * @endcode
73 */
75{
76public:
77 /**
78 * Constructs a new instance of a suitable ProcessInfo sub-class for
79 * the current platform which provides information about a given process.
80 *
81 * @param pid The pid of the process to examine
82 * @param readEnvironment Specifies whether environment bindings should
83 * be read. If this is false, then environment() calls will
84 * always fail. This is an optimization to avoid the overhead
85 * of reading the (potentially large) environment data when it
86 * is not required.
87 */
88 static std::unique_ptr<ProcessInfo> newInstance(int pid, bool readEnvironment = false);
89
90 virtual ~ProcessInfo()
91 {
92 }
93
94 /**
95 * Updates the information about the process. This must
96 * be called before attempting to use any of the accessor methods.
97 */
98 void update();
99
100 /** Returns true if the process state was read successfully. */
101 bool isValid() const;
102 /**
103 * Returns the process id.
104 *
105 * @param ok Set to true if the process id was read successfully or false otherwise
106 */
107 int pid(bool *ok) const;
108 /**
109 * Returns the id of the parent process id was read successfully or false otherwise
110 *
111 * @param ok Set to true if the parent process id
112 */
113 int parentPid(bool *ok) const;
114
115 /**
116 * Returns the id of the current foreground process
117 *
118 * NOTE: Using the foregroundProcessGroup() method of the Pty
119 * instance associated with the terminal of interest is preferred
120 * over using this method.
121 *
122 * @param ok Set to true if the foreground process id was read successfully or false otherwise
123 */
124 int foregroundPid(bool *ok) const;
125
126 /* Returns the user id of the process */
127 int userId(bool *ok) const;
128
129 /** Returns the user's name of the process */
130 QString userName() const;
131
132 /** Returns the user's home directory of the process */
133 QString userHomeDir() const;
134
135 /** Returns the local host */
136 static QString localHost();
137
138 /** Returns the name of the current process */
139 QString name(bool *ok) const;
140
141 /**
142 * Returns the command-line arguments which the process
143 * was started with.
144 *
145 * The first argument is the name used to launch the process.
146 *
147 * @param ok Set to true if the arguments were read successfully or false otherwise.
148 */
149 QVector<QString> arguments(bool *ok) const;
150 /**
151 * Returns the environment bindings which the process
152 * was started with.
153 * In the returned map, the key is the name of the environment variable,
154 * and the value is the corresponding value.
155 *
156 * @param ok Set to true if the environment bindings were read successfully or false otherwise
157 */
158 QMap<QString, QString> environment(bool *ok) const;
159
160 /**
161 * Returns the current working directory of the process
162 *
163 * @param ok Set to true if the current working directory was read successfully or false otherwise
164 */
165 QString currentDir(bool *ok) const;
166
167 /**
168 * Returns the current working directory of the process (or its parent)
169 */
170 QString validCurrentDir() const;
171
172 /** Forces the user home directory to be calculated */
173 void setUserHomeDir();
174
175 /**
176 * Parses an input string, looking for markers beginning with a '%'
177 * character and returns a string with the markers replaced
178 * with information from this process description.
179 * <br>
180 * The markers recognized are:
181 * <ul>
182 * <li> %u - Name of the user which owns the process. </li>
183 * <li> %n - Replaced with the name of the process. </li>
184 * <li> %d - Replaced with the last part of the path name of the
185 * process' current working directory.
186 *
187 * (eg. if the current directory is '/home/bob' then
188 * 'bob' would be returned)
189 * </li>
190 * <li> %D - Replaced with the current working directory of the process. </li>
191 * </ul>
192 */
193 QString format(const QString &text) const;
194
195 /**
196 * This enum describes the errors which can occur when trying to read
197 * a process's information.
198 */
199 enum Error {
200 /** No error occurred. */
202 /** The nature of the error is unknown. */
204 /** Konsole does not have permission to obtain the process information. */
206 };
207
208 /**
209 * Returns the last error which occurred.
210 */
211 Error error() const;
212
213 enum Field { PROCESS_ID = 1, PARENT_PID = 2, FOREGROUND_PID = 4, ARGUMENTS = 8, ENVIRONMENT = 16, NAME = 32, CURRENT_DIR = 64, UID = 128 };
214 Q_DECLARE_FLAGS(Fields, Field)
215
216protected:
217 /**
218 * Constructs a new process instance. You should not call the constructor
219 * of ProcessInfo or its subclasses directly. Instead use the
220 * static ProcessInfo::newInstance() method which will return
221 * a suitable ProcessInfo instance for the current platform.
222 */
223 explicit ProcessInfo(int pid, bool readEnvironment = false);
224
225 /**
226 * This is called on construction to read the process state
227 * Subclasses should reimplement this function to provide
228 * platform-specific process state reading functionality.
229 *
230 * When called, readProcessInfo() should attempt to read all
231 * of the necessary state information. If the attempt is successful,
232 * it should set the process id using setPid(), and update
233 * the other relevant information using setParentPid(), setName(),
234 * setArguments() etc.
235 *
236 * Calls to isValid() will return true only if the process id
237 * has been set using setPid()
238 *
239 * @param pid The process id of the process to read
240 * @param readEnvironment Specifies whether the environment bindings
241 * for the process should be read
242 */
243 virtual bool readProcessInfo(int pid, bool readEnvironment) = 0;
244
245 /* Read the user name */
246 virtual void readUserName(void) = 0;
247
248 /** Sets the process id associated with this ProcessInfo instance */
249 void setPid(int pid);
250 /** Sets the parent process id as returned by parentPid() */
251 void setParentPid(int pid);
252 /** Sets the foreground process id as returned by foregroundPid() */
253 void setForegroundPid(int pid);
254 /** Sets the user id associated with this ProcessInfo instance */
255 void setUserId(int uid);
256 /** Sets the user name of the process as set by readUserName() */
257 void setUserName(const QString &name);
258 /** Sets the name of the process as returned by name() */
259 void setName(const QString &name);
260 /** Sets the current working directory for the process */
261 void setCurrentDir(const QString &dir);
262
263 /** Sets the error */
264 void setError(Error error);
265
266 /** Convenience method. Sets the error based on a QFile error code. */
268
269 /**
270 * Adds a commandline argument for the process, as returned
271 * by arguments()
272 */
273 void addArgument(const QString &argument);
274
275 /**
276 * clear the commandline arguments for the process, as returned
277 * by arguments()
278 */
279 void clearArguments();
280
281 /**
282 * Adds an environment binding for the process, as returned by
283 * environment()
284 *
285 * @param name The name of the environment variable, eg. "PATH"
286 * @param value The value of the environment variable, eg. "/bin"
287 */
288 void addEnvironmentBinding(const QString &name, const QString &value);
289
290private:
291 // takes a full directory path and returns a
292 // shortened version suitable for display in
293 // space-constrained UI elements (eg. tabs)
294 QString formatShortDir(const QString &dirPath) const;
295
296 Fields _fields;
297
298 bool _enableEnvironmentRead; // specifies whether to read the environment
299 // bindings when update() is called
300 int _pid;
301 int _parentPid;
302 int _foregroundPid;
303 int _userId;
304
305 Error _lastError;
306
307 QString _name;
308 QString _userName;
309 QString _userHomeDir;
310 QString _currentDir;
311
312 QVector<QString> _arguments;
313 QMap<QString, QString> _environment;
314
315 static QSet<QString> commonDirNames();
316 static QSet<QString> _commonDirNames;
317};
318Q_DECLARE_OPERATORS_FOR_FLAGS(ProcessInfo::Fields)
319
320/**
321 * Implementation of ProcessInfo which does nothing.
322 * Used on platforms where a suitable ProcessInfo subclass is not
323 * available.
324 *
325 * isValid() will always return false for instances of NullProcessInfo
326 */
328{
329public:
330 /**
331 * Constructs a new NullProcessInfo instance.
332 * See ProcessInfo::newInstance()
333 */
334 explicit NullProcessInfo(int pid, bool readEnvironment = false);
335
336protected:
337 bool readProcessInfo(int pid, bool readEnvironment) override;
338 void readUserName(void) override;
339};
340
341#if !defined(Q_OS_WIN)
342/**
343 * Implementation of ProcessInfo for Unix platforms which uses
344 * the /proc filesystem
345 */
347{
348public:
349 /**
350 * Constructs a new instance of UnixProcessInfo.
351 * See ProcessInfo::newInstance()
352 */
353 explicit UnixProcessInfo(int pid, bool readEnvironment = false);
354
355protected:
356 /**
357 * Implementation of ProcessInfo::readProcessInfo(); calls the
358 * four private methods below in turn.
359 */
360 bool readProcessInfo(int pid, bool readEnvironment) override;
361
362 void readUserName(void) override;
363
364private:
365 /**
366 * Read the standard process information -- PID, parent PID, foreground PID.
367 * @param pid process ID to use
368 * @return true on success
369 */
370 virtual bool readProcInfo(int pid) = 0;
371
372 /**
373 * Read the environment of the process. Sets _environment.
374 * @param pid process ID to use
375 * @return true on success
376 */
377 virtual bool readEnvironment(int pid) = 0;
378
379 /**
380 * Determine what arguments were passed to the process. Sets _arguments.
381 * @param pid process ID to use
382 * @return true on success
383 */
384 virtual bool readArguments(int pid) = 0;
385
386 /**
387 * Determine the current directory of the process.
388 * @param pid process ID to use
389 * @return true on success
390 */
391 virtual bool readCurrentDir(int pid) = 0;
392};
393#endif
394
395/**
396 * Lightweight class which provides additional information about SSH processes.
397 */
399{
400public:
401 /**
402 * Constructs a new SSHProcessInfo instance which provides additional
403 * information about the specified SSH process.
404 *
405 * @param process A ProcessInfo instance for a SSH process.
406 */
407 explicit SSHProcessInfo(const ProcessInfo &process);
408
409 /**
410 * Returns the user name which the user initially logged into on
411 * the remote computer.
412 */
413 QString userName() const;
414
415 /**
416 * Returns the host which the user has connected to.
417 */
418 QString host() const;
419
420 /**
421 * Returns the port on host which the user has connected to.
422 */
423 QString port() const;
424
425 /**
426 * Returns the command which the user specified to execute on the
427 * remote computer when starting the SSH process.
428 */
429 QString command() const;
430
431 /**
432 * Operates in the same way as ProcessInfo::format(), except
433 * that the set of markers understood is different:
434 *
435 * %u - Replaced with user name which the user initially logged
436 * into on the remote computer.
437 * %h - Replaced with the first part of the host name which
438 * is connected to.
439 * %H - Replaced with the full host name of the computer which
440 * is connected to.
441 * %c - Replaced with the command which the user specified
442 * to execute when starting the SSH process.
443 */
444 QString format(const QString &input) const;
445
446private:
447 const ProcessInfo &_process;
448 QString _user;
449 QString _host;
450 QString _port;
451 QString _command;
452};
453}
454#endif // PROCESSINFO_H
Implementation of ProcessInfo which does nothing.
Takes a snapshot of the state of a process and provides access to information such as the process nam...
Definition ProcessInfo.h:75
int parentPid(bool *ok) const
Returns the id of the parent process id was read successfully or false otherwise.
void setUserName(const QString &name)
Sets the user name of the process as set by readUserName()
void clearArguments()
clear the commandline arguments for the process, as returned by arguments()
void setUserHomeDir()
Forces the user home directory to be calculated.
ProcessInfo(int pid, bool readEnvironment=false)
Constructs a new process instance.
static QString localHost()
Returns the local host.
void addEnvironmentBinding(const QString &name, const QString &value)
Adds an environment binding for the process, as returned by environment()
void setName(const QString &name)
Sets the name of the process as returned by name()
Error
This enum describes the errors which can occur when trying to read a process's information.
@ PermissionsError
Konsole does not have permission to obtain the process information.
@ UnknownError
The nature of the error is unknown.
@ NoError
No error occurred.
QString currentDir(bool *ok) const
Returns the current working directory of the process.
void setFileError(QFile::FileError error)
Convenience method.
void setParentPid(int pid)
Sets the parent process id as returned by parentPid()
void setPid(int pid)
Sets the process id associated with this ProcessInfo instance.
int pid(bool *ok) const
Returns the process id.
int foregroundPid(bool *ok) const
Returns the id of the current foreground process.
void setError(Error error)
Sets the error.
void setCurrentDir(const QString &dir)
Sets the current working directory for the process.
QMap< QString, QString > environment(bool *ok) const
Returns the environment bindings which the process was started with.
bool isValid() const
Returns true if the process state was read successfully.
QString userHomeDir() const
Returns the user's home directory of the process.
QString format(const QString &text) const
Parses an input string, looking for markers beginning with a '' character and returns a string with t...
void update()
Updates the information about the process.
Error error() const
Returns the last error which occurred.
QString name(bool *ok) const
Returns the name of the current process.
void setUserId(int uid)
Sets the user id associated with this ProcessInfo instance.
QString validCurrentDir() const
Returns the current working directory of the process (or its parent)
void setForegroundPid(int pid)
Sets the foreground process id as returned by foregroundPid()
QVector< QString > arguments(bool *ok) const
Returns the command-line arguments which the process was started with.
QString userName() const
Returns the user's name of the process.
static std::unique_ptr< ProcessInfo > newInstance(int pid, bool readEnvironment=false)
Constructs a new instance of a suitable ProcessInfo sub-class for the current platform which provides...
void addArgument(const QString &argument)
Adds a commandline argument for the process, as returned by arguments()
virtual bool readProcessInfo(int pid, bool readEnvironment)=0
This is called on construction to read the process state Subclasses should reimplement this function ...
Lightweight class which provides additional information about SSH processes.
QString format(const QString &input) const
Operates in the same way as ProcessInfo::format(), except that the set of markers understood is diffe...
QString userName() const
Returns the user name which the user initially logged into on the remote computer.
QString host() const
Returns the host which the user has connected to.
QString command() const
Returns the command which the user specified to execute on the remote computer when starting the SSH ...
QString port() const
Returns the port on host which the user has connected to.
SSHProcessInfo(const ProcessInfo &process)
Constructs a new SSHProcessInfo instance which provides additional information about the specified SS...
Implementation of ProcessInfo for Unix platforms which uses the /proc filesystem.
UnixProcessInfo(int pid, bool readEnvironment=false)
Constructs a new instance of UnixProcessInfo.
bool readProcessInfo(int pid, bool readEnvironment) override
Implementation of ProcessInfo::readProcessInfo(); calls the four private methods below in turn.
This file is part of the KDE documentation.
Documentation copyright © 1996-2024 The KDE developers.
Generated on Fri Nov 29 2024 11:55:13 by doxygen 1.12.0 written by Dimitri van Heesch, © 1997-2006

KDE's Doxygen guidelines are available online.