Process Class Reference

Detailed Description

A class allowing running subprocesses and communicating with them through stdin/stdout/stderr.

The class allows keeping the subprocess running and writing to its input and reading from its output as that is produced. This example would run a subprocess, write one line to its input, and read its output line by line while it runs.

All output reading functions (readOutput(), readOutputLine(), ...) are blocking and will wait until there is something to read from the process.

Process proc;
proc.run("program.exe");
proc.writeInput("Hello\n");
while(true) {
    String line = proc.readOutputLine();
    if(line == "\n")
        break;
    printf("Subprocess wrote %s\n", *line);
}

A shorthand function allows executing a program and, after it finishes, getting its full output, errors and exitcode.

Process p = Process::execute("ipconfig");
if( p.success() )
    text = p.output();

In Windows you can append a '*' to program names (e.g. "notepad.exe*") or set showWindow in the process parameters to show their window if they are Win32 GUI apps. Or to show their console. Otherwise they run in the background with no window.

Warning: If a process is run with the run() method and we will not read its output, the process can hang if it writes a lot to its output stream (because it will fill a buffer that no one will free). To avoid that, call detach() before calling run().

You can set the environment variables to be used by the subprocess with setSubprocessEnvironment() before calling run(), and set the directory where the process will start with setStartDirectory().

#include <asl/Process.h>

Public Member Functions
int	pid ()
	Returns this process' ID (PID)
int	readOutput (void *p, int n)
	Reads n bytes of the process' stdout into a buffer pointed to by p
int	readErrors (void *p, int n)
	Reads n bytes of the process' stderr into a buffer pointed to by p
int	writeInput (const void *p, int n)
	Writes n bytes into the process' stdin from a buffer pointed to by p
void	writeInput (const String &s)
	Writes a string to the process' stdin
String	readOutputLine ()
	Reads one text line from the process' stdout or a "\n" if the process ended.
void	detach ()
	Indicates that we are not interested in the process' output (must be called this before run()), and the subprocess can continue running if the parent process ends.
void	setStartDirectory (const String &dir)
	Sets the starting directory of the new process.
int	outputAvailable ()
	Returns the number of bytes that can be read from the process' standard output.
int	errorsAvailable ()
	Returns the number of bytes that can be read from the process' standard errors.
const String &	output () const
	Returns the standard output of a subprocess as a string (if executed with Process::execute())
const String &	errors () const
	Returns the standard errors of a subprocess as a string (if executed with Process::execute())
void	run (const String &command, const Array< String > &args=Array< String >())
	Starts executing a program with optional command line arguments and environment variables.
bool	ready () const
	Tests if the process object and its pipes were created successfully.
bool	success ()
	Returns true if the process executed correctly (exited with zero status)
bool	started ()
	Tests if the subprocess has started successfully.
bool	finished ()
	Tests if the subprocess has finished.
bool	running ()
	Tests if the subprocess has not finished.
int	wait ()
	Waits for the subprocess to exit.
int	exitStatus ()
	Returns the exit code of the process, if finished.
void	use (const ProcParams &params)
	Sets the parameters to be used by the subprocess when run.
void	setSubprocessEnvironment (const ProcEnv &env)
	Sets the environment variables to be used by the subprocess when run.

Static Public Member Functions
static int	myPid ()
	Returns the current process identifier (PID)
static String	myPath ()
	Returns the full path of the executable file of the current process.
static String	myDir ()
	Returns the directory containing the executable file of the current process.
static String	loadedLibPath (const String &lib)
	Returns the full path of the shared library named lib (without extension) loaded in the current process.
static String	env (const String &var)
	Gets the value of an environment variable.
static void	setEnv (const String &var, const String &value)
	Sets the value of an environment variable.
static ProcEnv	environment ()
	Returns a dictionary of all environment variables of the current process.
static Process	execute (const String &command, const Array< String > &args=Array< String >(), const ProcParams &env=ProcParams())
	Executes command with optional arguments, environment vars and a start directory, and returns the process' data (including output (written to stdout and stderr);.
static Array< ProcessInfo >	list ()
	Returns a list of all running processes in the system, with their PID and executable path.
static bool	kill (int pid)
	Kills the process with the given PID.
static int	killAll (const String &name)
	Kills all processes with the given name.

Member Function Documentation

kill()

static bool kill ( int  pid )

static

Kills the process with the given PID.

Returns true if the process was killed successfully.

killAll()

static int killAll ( const String &  name )

static

Kills all processes with the given name.

Returns the number of processes killed.

use()

void use ( const ProcParams &  params )

inline

Sets the parameters to be used by the subprocess when run.

This includes environment variables, working directory, and other options.

---

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

• Process.h