Process Class Reference

A system process. More...

#include <Process.h++>

List of all members.

Public Member Functions
	Process (const String &path, const StringVec &args, const StringVec &env=StringVec::emptyVec, const String &workingDir=".")
	Construct a new Process.
	~Process () throw ()
	Destructor.
void	start () throw (SystemException)
	Start the process.
void	stop () throw ()
	Stop the process.
bool	kill () throw ()
	Forcibly kill the process.
void	setPriority (Priority priority) throw ()
	Set the process priority.
Priority	getPriority () const throw ()
	Get the process priority.
bool	waitFor (ExitStatus &status) throw ()
	Wait for the process to terminate.
bool	isStarted () const throw ()
	Determine if the process has been started.
Stream &	getInputStream () throw ()
	Get the input stream for the process.
Stream &	getOutputStream () throw ()
	Get the output stream for the process.
Stream &	getErrorStream () throw ()
	Get the error stream for the process.
time_ms_t	getStartTime () const throw ()
	Get the time at which the process was started.
Static Public Member Functions
static void	exit (int status) throw ()
	Terminate the calling process.
static const char *	getProgramName () throw ()
	Get the name of the calling program.
static String	getExecutablePath () throw (SystemException)
	Get the full path to the calling program's executable file.
static String	getExecutableDir () throw (SystemException)
	Get the full path to the directory containing the calling program's executable file.
static void	setProgramName (const char *name) throw ()
	Set the name of the calling program.
static String	getWorkingDir ()
	Get the calling process's working directory.
static bool	setWorkingDir (const String &path) throw ()
	Set the calling process's working directory.
static bool	hasConsole () throw ()
	Test for the presence of a console.
static bool	getConsoleSize (uint_t *columns, uint_t *rows) throw ()
	Get the console dimensions for the calling process, in characters.
static void	setConsoleTitle (const String &title) throw ()
	Set the console title for the calling process.
static ProcessID	currentProcessID () throw ()
	Get the calling process ID.

---

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	(	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

(

)

throw ()

Destructor.

The destructor does not terminate the process.

---

Member Function Documentation

ProcessID currentProcessID

(

)

throw () [static]

Get the calling process ID.

void exit

(

int

status

)

throw () [static]

Terminate the calling process.

Parameters:

status

The exit status to exit with.

bool getConsoleSize	(	uint_t *	columns,
		uint_t *	rows
	)			throw () [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.

Stream& getErrorStream

(

)

throw () [inline]

Get the error stream for the process.

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

String getExecutableDir

(

)

throw (SystemException) [static]

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

String getExecutablePath

(

)

throw (SystemException) [static]

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

Stream& getInputStream

(

)

throw () [inline]

Get the input stream for the process.

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

Stream& getOutputStream

(

)

throw () [inline]

Get the output stream for the process.

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

Priority getPriority

(

)

const throw ()

Get the process priority.

static const char* getProgramName

(

)

throw () [inline, static]

Get the name of the calling program.

time_ms_t getStartTime

(

)

const throw () [inline]

Get the time at which the process was started.

String getWorkingDir

(

)

[static]

Get the calling process's working directory.

bool hasConsole

(

)

throw () [static]

Test for the presence of a console.

Returns:

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

bool isStarted

(

)

const throw () [inline]

Determine if the process has been started.

bool kill

(

)

throw ()

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.

void setConsoleTitle

(

const String &

title

)

throw () [static]

Set the console title for the calling process.

Parameters:

title

The new title.

void setPriority

(

Priority

priority

)

throw ()

Set the process priority.

static void setProgramName

(

const char *

name

)

throw () [inline, static]

Set the name of the calling program.

bool setWorkingDir

(

const String &

path

)

throw () [static]

Set the calling process's working directory.

Parameters:

path

The new working directory.

Returns:

true on success, false otherwise.

void start

(

)

throw (SystemException)

Start the process.

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

Exceptions:

SystemException

If an error occurred.

void stop

(

)

throw ()

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.

bool waitFor

(

ExitStatus &

status

)

throw ()

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:

• Process.h++
• Process.c++