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*") 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().

#include <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.
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 by a command line.
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.

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 Process	execute (const String &command, const Array< String > &args=Array< String >())
	Executes command and returns the process' output (written to stdout) as a String.

Member Function Documentation

execute()

static Process execute ( const String &  command, const Array< String > &  args = Array< String >()  )

static

Executes command and returns the process' output (written to stdout) as a String.

Add a '*' at the end of the command name to show the program's window in case of Win32 apps.

---

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

• Process.h