MCProcess Class Reference

Representation of a process. More...

#include <mcllib/MCProcess.h>

Inheritance diagram for MCProcess:

List of all members.

Public Member Functions
void	detach ()
	Detach the process.
const MCString &	getDirectory ()
	Get working directory for a process.
MCString	getExecutableName ()
	Get base name of executable file name of the process.
const MCString &	getFileName ()
	Get executable file name of the process.
bool	isDetached ()
	Test to see if the detached state for a process is true.
bool	isRunning ()
	Test to see if a process is running.
void	kill ()
	Kill the process.
	MCProcess (const MCString &name)
	Create a process object with the specified name.
	MCProcess ()
	Create a process object that represents the current process.
void	run (char *const *argv, char *const *envp=0)
	Run the process.
void	setDetached (bool detached)
	Set detached state.
void	setDirectory (const MCString &dir)
	Set working directory for process.
void	setStdHandle (MCFile::EStdHandle hdl, const MCFile &file)
	Set (redirect) the standard file handle for a process.
mcint32	wait ()
	Wait for the process to exit.

---

Detailed Description

Representation of a process.

A process object either refers to the currently running process or can be used to allow a new process to be started. Process objects which refer to the currently running process are called "current process" objects. All other process objects are simply "process" objects or sometimes "named process" objects because a name is specified at construction time.

---

Constructor & Destructor Documentation

MCProcess (   )

Create a process object that represents the current process. Several methods will generate exceptions if called against a current process object.

MCProcess (  const MCString &  name  )

Create a process object with the specified name. The name is used entirely for diagnostic purposes and is not used to specify which executable image to create a process from. A new process is not created until the run() method is called. Parameters: name  a name used to identify the process for diagnostic purposes.

---

Member Function Documentation

void detach (   )

Detach the process. This frees system resources consumed by the process. An exception is thrown is the process has not been started with run() or if the process was run in a detached state. An exception is thrown if the process is a current process object. Reimplemented from MCBase.

const MCString& getDirectory (   )

Get working directory for a process. If called on a current process object then the working directory of the current process is obtained. This is done using MCDir::getCurrent() and so should reflect changes made to the current directory using MCDir::setCurrent(). Returns: the working directory for the process

MCString getExecutableName (   )

Get base name of executable file name of the process. Effectively calls getFileName() and then obtains the basename from that using the MCDirEntry::tail() method. Returns: the base name of the executable image of the process.

const MCString& getFileName (   )

Get executable file name of the process. If called on a current process object the path name of the executable used to create the current process will be returned (if it can be determined). If called on a named process object, the path (argv[0]) passed to the run() method is returned. If run() has not been called an empty string is returned. Returns: the file name of the executable image of the process.

bool isDetached (   )

Test to see if the detached state for a process is true. Returns: the detached state of the process.

bool isRunning (   )

Test to see if a process is running. For a current process object this is always true. A side effect of run()ing a detached process is that isRunning() will always return false. This is because specifying detached indicates to the system that you are no longer interested in the process. This includes knowing whether it is running or not. Returns: true if the process is running.

void kill (   )

Kill the process. An exception is thrown is the process has not been started with run() or if the process was run in a detached state. An exception is thrown if the process is a current process object.

void run (  char *const *  argv, char *const *  envp = 0 )

Run the process. argv[0] specifies the executable file to run. The other arguments form the command line arguments to the process. If envp is not provided the environment of the current process will be passed to the new process. Otherwise whatever environment is specified will for the environment for the new process. An exception will be thrown is run() is called on a current process object. Parameters: argv  the arguments to the process envp  the environment for the process

void setDetached (  bool  detached  )

Set detached state. When a detached process is run() it is immediately "forgotten about" and resources relating to it are returned to the system. A detached process cannot be wait()ed on. When a process object is constructed, the detached state is initially false which means that when the process is run(), it can be wait()ed on. Parameters: detached  whether the process should be detached when run.

void setDirectory (  const MCString &  dir  )

Set working directory for process. This method must be called before run(). Calling setDirectory() after run() has been called will have no effect. If setDirectory() is called on a current process object an exception is thrown. Parameters: dir  the new current directory for the process

void setStdHandle (  MCFile::EStdHandle  hdl, const MCFile &  file )

Set (redirect) the standard file handle for a process. An exception is thrown is setStdHandle() is called on a current process object. When the process is run() the specified standard handle is redirected to file. Todo: redirection does not work on all platforms Parameters: hdl  the handle to redirect file  the file to redirect to

mcint32 wait (   )

Wait for the process to exit. The exit status of the process is returned. An exception is thrown is the process has not been started with run() or if the process was run in a detached state. An exception is thrown if the process is a current process object. Returns: the exit status of the process

---