A system process. More...

#include <Process.h++>

Public Member Functions
	Process (const String &path, const StringVec &args, const StringVec &env=StringVec::emptyVec, const String &workingDir=".")
	Construct a new Process. More...

	~Process ()
	Destructor. More...

void	start ()
	Start the process. More...

void	stop ()
	Stop the process. More...

bool	kill ()
	Forcibly kill the process. More...

void	setPriority (Priority priority)
	Set the process priority. More...

Priority	getPriority () const
	Get the process priority. More...

bool	waitFor (ExitStatus &status)
	Wait for the process to terminate. More...

bool	isStarted () const
	Determine if the process has been started. More...

Stream &	getInputStream ()
	Get the input stream for the process. More...

Stream &	getOutputStream ()
	Get the output stream for the process. More...

Stream &	getErrorStream ()
	Get the error stream for the process. More...

time_ms_t	getStartTime () const
	Get the time at which the process was started. More...

Static Public Member Functions
static void	exit (int status)
	Terminate the calling process. More...

static String	getProgramName ()
	Get the name of the calling program. More...

static String	getExecutablePath ()
	Get the full path to the calling program's executable file. More...

static String	getExecutableDir ()
	Get the full path to the directory containing the calling program's executable file. More...

static void	setProgramName (const char *name)
	Set the name of the calling program. More...

static String	getWorkingDir ()
	Get the calling process's working directory. More...

static bool	setWorkingDir (const String &path)
	Set the calling process's working directory. More...

static bool	hasConsole ()
	Test for the presence of a console. More...

static bool	getConsoleSize (uint_t columns, uint_t rows)
	Get the console dimensions for the calling process, in characters. More...

static void	setConsoleTitle (const String &title)
	Set the console title for the calling process. More...

static ProcessID	currentProcessID ()
	Get the calling process ID. More...

Detailed Description

A system process.

This class may be used to execute a program, communicate with the program via its standard I/O streams, terminate the program, and collect its exit status. The class also includes a number of static utility functions that affect the current process.

When the Process is created, its standard input, output, and error streams are automatically connected to the parent process; these streams can be accessed using the getInputStream(), getOutputStream(), and getErrorStream() methods. Any output that the process produces on its standard output and error streams must be read in a timely manner by the calling process to avoid deadlock. Alternatively, if the calling process is not interested in the output, it can immediately close these streams.

Author: Mark Lindner

Constructor & Destructor Documentation

◆ Process()

Process	(	const String &	path,
		const StringVec &	args,
		const StringVec &	env = `StringVec::emptyVec`,
		const String &	workingDir = `"."`
	)

Construct a new Process.

Parameters

path	The path to the executable.
args	The command-line arguments for the executable.
env	Environment variable settings for the new process.
workingDir	The working directory for the new process.

◆ ~Process()

~Process ( )

Destructor.

The destructor does not terminate the process.

Member Function Documentation

◆ currentProcessID()

ProcessID currentProcessID ( )

static

Get the calling process ID.

◆ exit()

void exit ( int status )

static

Terminate the calling process.

Parameters

status The exit status to exit with.

◆ getConsoleSize()

bool getConsoleSize	(	uint_t *	columns,
		uint_t *	rows
	)

static

Get the console dimensions for the calling process, in characters.

On POSIX systems, this refers to the dimensions of the terminal window. On Windows, it refers to the "console buffer size."

Parameters

columns	A pointer to the value where the width of the console should be stored. May be NULL.
rows	A pointer to the value where the height of the console should be stored. May be NULL.

Returns: true if the size could be determined, false otherwise.

◆ getErrorStream()

Stream& getErrorStream ( )

inline

Get the error stream for the process.

This stream is connected to the standard error of the process.

◆ getExecutableDir()

String getExecutableDir ( )

static

Get the full path to the directory containing the calling program's executable file.

Exceptions

SystemException If an error occurs.

◆ getExecutablePath()

String getExecutablePath ( )

static

Get the full path to the calling program's executable file.

Exceptions

SystemException If an error occurs.

◆ getInputStream()

Stream& getInputStream ( )

inline

Get the input stream for the process.

This stream is connected to the standard input of the process.

◆ getOutputStream()

Stream& getOutputStream ( )

inline

Get the output stream for the process.

This stream is connected to the standard output of the process.

◆ getPriority()

Priority getPriority ( ) const

Get the process priority.

◆ getProgramName()

static String getProgramName ( )

inlinestatic

Get the name of the calling program.

◆ getStartTime()

time_ms_t getStartTime ( ) const

inline

Get the time at which the process was started.

◆ getWorkingDir()

String getWorkingDir ( )

static

Get the calling process's working directory.

◆ hasConsole()

bool hasConsole ( )

static

Test for the presence of a console.

Returns: true if the calling process is connected to a console, false otherwise.

◆ isStarted()

bool isStarted ( ) const

inline

Determine if the process has been started.

◆ kill()

bool kill ( )

Forcibly kill the process.

If the process has not been started, this method has no effect.

Returns: true if the process was successfully killed, false otherwise.

◆ setConsoleTitle()

void setConsoleTitle ( const String & title )

static

Set the console title for the calling process.

Parameters

title The new title.

◆ setPriority()

void setPriority ( Priority priority )

Set the process priority.

◆ setProgramName()

static void setProgramName ( const char * name )

inlinestatic

Set the name of the calling program.

◆ setWorkingDir()

bool setWorkingDir ( const String & path )

static

Set the calling process's working directory.

Parameters

path	The new working directory.

Returns: true on success, false otherwise.

◆ start()

void start ( )

Start the process.

If the process has already been started, this method has no effect.

Exceptions

SystemException If an error occurred.

◆ stop()

void stop ( )

Stop the process.

On Windows systems, this method has the same effect as kill(). On POSIX systems, this method sends a (catchable) SIGTERM signal to the process. If the process has not been started, this method has no effect.

◆ waitFor()

bool waitFor ( ExitStatus & status )

Wait for the process to terminate.

Once a process has exited (for whatever reason) and its exit status has been collected via a call to this method, it can be started again with start().

Parameters

status The object in which to store the exit status.

Returns: true if the process exited, false if the process was not running.

The documentation for this class was generated from the following files:

Public Member Functions

Static Public Member Functions

Detailed Description

Constructor & Destructor Documentation

◆ Process()

◆ ~Process()

Member Function Documentation

◆ currentProcessID()

◆ exit()

◆ getConsoleSize()

◆ getErrorStream()

◆ getExecutableDir()

◆ getExecutablePath()

◆ getInputStream()

◆ getOutputStream()

◆ getPriority()

◆ getProgramName()

◆ getStartTime()

◆ getWorkingDir()

◆ hasConsole()

◆ isStarted()

◆ kill()

◆ setConsoleTitle()

◆ setPriority()

◆ setProgramName()

◆ setWorkingDir()

◆ start()

◆ stop()

◆ waitFor()