FX::QChildProcess Class Reference
[Synchronous i/o devices]

#include <QChildProcess.h>

Inheritance diagram for FX::QChildProcess:

Detailed Description

A child process i/o device.

This handy class allows one process to portably communicate with a child process using the standard Unix stdin, stdout and stderr character streams. This can be useful for invoking compilers and other non-TnFOX command-line based programs.

QChildProcess is a synchronous i/o device like FX:QBlkSocket - in other words, reads from it block until data is available. To avoid this, check atEnd() before reading - however generally, you want it to block because you will have allocated a special thread whose sole purpose is to wait on incoming data and asynchronously do something useful with it. One action could be to post a message to some control in the GUI for example. You should note that if you don't empty the output stream from the child process regularly, most operating systems will suspend the child thread until you do.

The two readable streams, stdout and stderr, are read simultaneously and stored internally by QChildProcess. This allows you to read say only stdout and the stderr pipe won't get blocked up. On close() (or destruction), the calling thread blocks until the child process exits. The child process will be forcibly terminated if the parent process should die for any reason before close() - this ensures zombie child processes don't multiply. If you want to remove the child from management, call detach().

If a child process should hang, you can wait for a certain time period for it to produce output or to exit and if not then invoke terminate().

Usage:

To use is pretty easy - simply construct one and set the path to the command you desire. Calling open() invokes the process, and thereafter readBlock() and writeBlock() work as expected. Calling close() will wait for the process to terminate before returning. Should the process exit, readBlock() will start returning zero bytes instead of blocking for more data to arrive.

Unix programs output two streams: stdout and stderr. You can switch between which is active, or whether to merge them, as the read channel using setReadChannel().

Public Types

enum ReadChannel { StdOut, StdErr, Combined }

enum CRLFType { Default, Unix, MacOS, MSDOS }

enum UnicodeType {
NoTranslation, UTF8, UTF16, UTF16LE,
UTF32, UTF32LE
}

typedef FXfval Offset

Public Member Functions

QChildProcess (const FXString &command, const FXString &args=FXString::nullStr(), ReadChannel channel=Combined)

const FXString & command () const

void setCommand (const FXString &command)

FXString arguments () const

void setArguments (const FXString &args)

FXString workingDir () const

void setWorkingDir (const FXString &dir)

ReadChannel readChannel () const throw ()

void setReadChannel (ReadChannel channel)

FXlong returnCode () const throw ()

void detach ()

bool waitForExit (FXuint waitfor=FXINFINITE)

bool terminate ()

bool open (FXuint mode=IO_ReadWrite)

void close ()

void flush ()

FXfval size () const

FXuval readBlock (char *data, FXuval maxlen)

FXuval writeBlock (const char *data, FXuval maxlen)

int ungetch (int)

virtual bool isSynchronous () const

virtual void truncate (FXfval)

virtual FXfval at () const

virtual bool at (FXfval)

virtual bool atEnd () const

virtual FXuval readBlockFrom (char *data, FXuval maxlen, FXfval pos)

FXuval readBlockFrom (FXuchar *data, FXuval maxlen, FXfval pos)

virtual FXuval writeBlockTo (FXfval pos, const char *data, FXuval maxlen)

FXuval writeBlockTo (FXfval pos, const FXuchar *data, FXuval maxlen)

FXuint flags () const

FXuint mode () const

FXuint state () const

CRLFType crlfFormat () const

void setCRLFFormat (CRLFType type)

UnicodeType unicodeTranslation () const

void setUnicodeTranslation (UnicodeType type)

bool isBuffered () const

bool isRaw () const

bool isTranslated () const

bool isUTF16Translated () const

bool isUTF32Translated () const

bool isReadable () const

bool isWriteable () const

bool isWritable () const

bool isReadWrite () const

bool isClosed () const

bool isInactive () const

bool isOpen () const

virtual const FXACL & permissions () const

virtual void setPermissions (const FXACL &)

FXuval readBlock (FXuchar *data, FXuval maxlen)

FXuval writeBlock (const FXuchar *data, FXuval maxlen)

virtual FXuval readLine (char *data, FXuval maxlen)

virtual int getch ()

virtual int putch (int c)

FXfval shredData (FXfval offset, FXfval len=(FXfval)-1)

Static Public Member Functions

static bool waitForData (QIODeviceS **signalled, FXuint no, QIODeviceS **list, FXuint waitfor=FXINFINITE)

static FXuint waitForDataMax () throw ()

static UnicodeType determineUnicodeType (FXuchar *data, FXuval len) throw ()

static FXuval applyCRLF (FXuchar *FXRESTRICT output, const FXuchar *FXRESTRICT input, FXuval outputlen, FXuval &inputlen, CRLFType crlftype=Default, UnicodeType utftype=NoTranslation)

static FXuval removeCRLF (FXuchar *FXRESTRICT output, const FXuchar *FXRESTRICT input, FXuval outputlen, FXuval &inputlen, UnicodeType utftype=NoTranslation)

Protected Member Functions

void setFlags (int f)

void setMode (int m)

void setState (int s)

Protected Attributes

FXfval ioIndex

Friends

FXAPI FXStream & operator<< (FXStream &s, QIODevice &i)

FXAPI FXStream & operator>> (FXStream &s, QIODevice &i)

Member Enumeration Documentation

enum FX::QChildProcess::ReadChannel

The types of read channel.

Enumerator:

StdOut	`stdout` is the read channel
StdErr	`stderr` is the read channel
Combined	`A` combination of `stdout` and `stderr` is the read channel

enum FX::QIODevice::CRLFType [inherited]

The type of CR/LF encoding you want.

Enumerator:

Default	Uses the host OS format.
Unix	Uses ASCII 10 to delimit lines.
MacOS	Uses ASCII 13 to delimit lines.
MSDOS	Uses ASCII 13,10 to delimit lines.

enum FX::QIODevice::UnicodeType [inherited]

The type of unicode translation you want.

Enumerator:

NoTranslation	Performs no translation.
UTF8	Outputs in native UTF-8.
UTF16	Converts between native (UTF-8) and UTF-16 big endian.
UTF16LE	Converts between native (UTF-8) and UTF-16 little endian.
UTF32	Converts between native (UTF-8) and UTF-32 big endian.
UTF32LE	Converts between native (UTF-8) and UTF-32 little endian.

Constructor & Destructor Documentation

FX::QChildProcess::QChildProcess	(	const FXString &	command,
		const FXString &	args = `FXString::nullStr()`,
		ReadChannel	channel = `Combined`
	)

Constructs an instance executing command.

Member Function Documentation

const FXString& FX::QChildProcess::command ( ) const

The command to be executed.

void FX::QChildProcess::setCommand ( const FXString & command )

Sets the command to be executed.

FXString FX::QChildProcess::arguments ( ) const

The arguments for the command to be executed.

void FX::QChildProcess::setArguments ( const FXString & args )

Sets the arguments for the command to be executed.

FXString FX::QChildProcess::workingDir ( ) const

The working directory for the command.

void FX::QChildProcess::setWorkingDir ( const FXString & dir )

Sets the working directory for the command to be executed.

ReadChannel FX::QChildProcess::readChannel ( ) const throw ()

Returns the channel to be used for reading.

void FX::QChildProcess::setReadChannel ( ReadChannel channel )

Sets the channel to be used for reading.

FXlong FX::QChildProcess::returnCode ( ) const throw ()

Returns the return code of the process (only valid after close()).

void FX::QChildProcess::detach ( )

Detaches the process.

bool FX::QChildProcess::waitForExit ( FXuint waitfor = FXINFINITE )

Waits for the process to end.

bool FX::QChildProcess::terminate ( )

Ensures the process is dead by exit, returning true if it was terminated (not exited naturally).

bool FX::QChildProcess::open ( FXuint mode = IO_ReadWrite ) [virtual]

Executes the command.

Implements FX::QIODeviceS.

void FX::QChildProcess::close ( ) [virtual]

Waits for the command to exit.

Implements FX::QIODevice.

void FX::QChildProcess::flush ( ) [virtual]

Flushes any data currently waiting to be transferred.

Implements FX::QIODevice.

FXfval FX::QChildProcess::size ( ) const [virtual]

Returns the amount of data waiting to be read. May return ((FXfval)-1) if there is data but it's unknown how much.

Implements FX::QIODevice.

FXuval FX::QChildProcess::readBlock	(	char *	data,
		FXuval	maxlen
	)			`[virtual]`

Returns:: The number of bytes read (which may be less than requested)

Parameters:

	data	Pointer to buffer to receive data
	maxlen	Maximum number of bytes to read

Reads a block of data from the command's output into the given buffer. Will wait forever until some data has been read if necessary. Is compatible with thread cancellation in FX::QThread on all platforms.

Implements FX::QIODevice.

FXuval FX::QChildProcess::writeBlock	(	const char *	data,
		FXuval	maxlen
	)			`[virtual]`

Returns:: The number of bytes written.

Parameters:

	data	Pointer to buffer of data to send
	maxlen	Number of bytes to send

Writes a block of data from the given buffer to the command. If the command isn't reading in from its input quickly enough, this may block.

Implements FX::QIODevice.

int FX::QChildProcess::ungetch ( int ) [virtual]

Tries to unread a character. Unsupported.

Implements FX::QIODevice.

virtual bool FX::QIODeviceS::isSynchronous ( ) const [inline, virtual, inherited]

Returns true if this device is a synchronous device.

Reimplemented from FX::QIODevice.

Reimplemented in FX::QSSLDevice.

virtual void FX::QIODeviceS::truncate ( FXfval ) [inline, virtual, inherited]

Does nothing as synchronous devices can't be truncated.

Implements FX::QIODevice.

Reimplemented in FX::QLocalPipe, FX::QPipe, and FX::QSSLDevice.

virtual FXfval FX::QIODeviceS::at ( ) const [inline, virtual, inherited]

Returns 0 because synchronous devices don't have a current file pointer.

Reimplemented from FX::QIODevice.

Reimplemented in FX::QLocalPipe, FX::QPipe, and FX::QSSLDevice.

virtual bool FX::QIODeviceS::at ( FXfval ) [inline, virtual, inherited]

Returns false because you can't set the current file pointer on a synchronous device.

Reimplemented from FX::QIODevice.

Reimplemented in FX::QLocalPipe, FX::QPipe, and FX::QSSLDevice.

virtual bool FX::QIODeviceS::atEnd ( ) const [inline, virtual, inherited]

Default implementation returning true if size() is zero.

Reimplemented from FX::QIODevice.

Reimplemented in FX::QLocalPipe, FX::QPipe, and FX::QSSLDevice.

virtual FXuval FX::QIODeviceS::readBlockFrom	(	char *	data,
		FXuval	maxlen,
		FXfval	pos
	)			`[virtual, inherited]`

Default implementation throws an exception.

Implements FX::QIODevice.

Reimplemented in FX::QSSLDevice.

virtual FXuval FX::QIODeviceS::writeBlockTo	(	FXfval	pos,
		const char *	data,
		FXuval	maxlen
	)			`[virtual, inherited]`

Default implementation throws an exception.

Implements FX::QIODevice.

Reimplemented in FX::QSSLDevice.

static bool FX::QIODeviceS::waitForData	(	QIODeviceS **	signalled,
		FXuint	no,
		QIODeviceS **	list,
		FXuint	waitfor = `FXINFINITE`
	)			`[static, inherited]`

Waits for more data to become available for reading on any one or more of an array of QIODeviceS's specified by list. Precisely which are those left in the array signalled if it's not NULL with empty members being zero.

Warning:: Beware race conditions caused by waiting on i/o devices which can be read asynchronously by other threads

Note:: This is a thread cancellation point

static FXuint FX::QIODeviceS::waitForDataMax ( ) throw () [static, inherited]

Returns the maximum number of QIODeviceS's which can be waited for at once.

FXuint FX::QIODevice::flags ( ) const [inline, inherited]

Returns the flags of this device.

FXuint FX::QIODevice::mode ( ) const [inline, inherited]

Returns the mode of this device

See also:: QIODeviceOpenFlags

FXuint FX::QIODevice::state ( ) const [inline, inherited]

Returns the state of this device

See also:: QIODeviceStateFlags

CRLFType FX::QIODevice::crlfFormat ( ) const [inline, inherited]

Returns the CR/LF format of this device.

void FX::QIODevice::setCRLFFormat ( CRLFType type ) [inline, inherited]

Sets the CR/LF format for output of this device.

UnicodeType FX::QIODevice::unicodeTranslation ( ) const [inline, inherited]

Returns the unicode translation of this device.

void FX::QIODevice::setUnicodeTranslation ( UnicodeType type ) [inline, inherited]

Sets the unicode translation of this device.

bool FX::QIODevice::isBuffered ( ) const [inline, inherited]

Returns true if the device is buffered.

bool FX::QIODevice::isRaw ( ) const [inline, inherited]

Returns true if the device is unbuffered.

bool FX::QIODevice::isTranslated ( ) const [inline, inherited]

Returns true if the device is LR/CF translated.

bool FX::QIODevice::isUTF16Translated ( ) const [inline, inherited]

Returns true if the device is UTF-16 translated.

bool FX::QIODevice::isUTF32Translated ( ) const [inline, inherited]

Returns true if the device is UTF-32 translated.

bool FX::QIODevice::isReadable ( ) const [inline, inherited]

Returns true if the device is readable.

bool FX::QIODevice::isWriteable ( ) const [inline, inherited]

Returns true if the device is writeable.

bool FX::QIODevice::isReadWrite ( ) const [inline, inherited]

Returns true if the device is readable & writeable.

bool FX::QIODevice::isClosed ( ) const [inline, inherited]

Returns true if the device is closed.

bool FX::QIODevice::isOpen ( ) const [inline, inherited]

Returns true if the device is opened.

virtual const FXACL& FX::QIODevice::permissions ( ) const [virtual, inherited]

Returns the ACL for this device.

Reimplemented in FX::QBlkSocket, FX::QFile, FX::QMemMap, FX::QPipe, and FX::QSSLDevice.

virtual void FX::QIODevice::setPermissions ( const FXACL & ) [virtual, inherited]

Sets the ACL for this device.

Reimplemented in FX::QFile, FX::QMemMap, FX::QPipe, and FX::QSSLDevice.

virtual FXuval FX::QIODevice::readLine	(	char *	data,
		FXuval	maxlen
	)			`[virtual, inherited]`

Reads data until an end-of-line or maxlen is exceeded.

virtual int FX::QIODevice::getch ( ) [virtual, inherited]

Reads a single byte. Returns -1 for no data found.

Reimplemented in FX::QBuffer, FX::QBZip2Device, FX::QGZipDevice, and FX::QMemMap.

virtual int FX::QIODevice::putch ( int c ) [virtual, inherited]

Writes a single byte.

Reimplemented in FX::QBuffer, FX::QBZip2Device, FX::QGZipDevice, and FX::QMemMap.

static UnicodeType FX::QIODevice::determineUnicodeType	(	FXuchar *	data,
		FXuval	len
	)			throw () `[static, inherited]`

Looks at a sample of data and determines what kind of Unicode text it is, returning UnicodeType::NoTranslation if it isn't text. This routine isn't foolproof, but it's a good guess

static FXuval FX::QIODevice::applyCRLF	(	FXuchar *FXRESTRICT	output,
		const FXuchar *FXRESTRICT	input,
		FXuval	outputlen,
		FXuval &	inputlen,
		CRLFType	crlftype = `Default`,
		UnicodeType	utftype = `NoTranslation`
	)			`[static, inherited]`

Applies CR/LF and optional UTF-x translation returning bytes output. If outputlen would run out before inputlen can be exhausted it will return early (eg; if mid newline, or mid UTF-x sequence). You should rewind processing to the difference between entrant inputlen and returned inputlen.

static FXuval FX::QIODevice::removeCRLF	(	FXuchar *FXRESTRICT	output,
		const FXuchar *FXRESTRICT	input,
		FXuval	outputlen,
		FXuval &	inputlen,
		UnicodeType	utftype = `NoTranslation`
	)			`[static, inherited]`

Removes CR/LF translation intelligently (ie; self-adjusts to MS-DOS, Unix and MacOS formats or any mixture of these) and can perform optional UTF-x translation, returning bytes output. If outputlen would run out before inputlen can be exhausted it will return early (eg; if mid newline, or mid UTF-x sequence). You should rewind processing to the difference between entrant inputlen and returned inputlen.

FXfval FX::QIODevice::shredData	(	FXfval	offset,
		FXfval	len = `(FXfval)-1`
	)			`[inherited]`

Destroys the len bytes of data from offset offset into the file. Restores the file pointer afterwards and returns how much data was shredded before end of file if encountered. You must have the device open for both reading and writing for this call to succeed.

void FX::QIODevice::setFlags ( int f ) [inline, protected, inherited]

Sets the flags.

void FX::QIODevice::setMode ( int m ) [inline, protected, inherited]

Sets the mode.

void FX::QIODevice::setState ( int s ) [inline, protected, inherited]

Sets the state.

Friends And Related Function Documentation

FXAPI FXStream& operator<<	(	FXStream &	s,
		QIODevice &	i
	)			`[friend, inherited]`

Appends the contents of an i/o device to stream s

Warning:: This operation is not thread-safe

FXAPI FXStream& operator>>	(	FXStream &	s,
		QIODevice &	i
	)			`[friend, inherited]`

Reads all available contents of the stream s to an i/o device, replacing its current contents and resetting the file pointer to the start

Warning:: This operation is not thread-safe

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

QChildProcess.h


Public Types
enum	ReadChannel { StdOut, StdErr, Combined }
enum	CRLFType { Default, Unix, MacOS, MSDOS }
enum	UnicodeType { NoTranslation, UTF8, UTF16, UTF16LE, UTF32, UTF32LE }
typedef FXfval	Offset
Public Member Functions
	QChildProcess (const FXString &command, const FXString &args=FXString::nullStr(), ReadChannel channel=Combined)
const FXString &	command () const
void	setCommand (const FXString &command)
FXString	arguments () const
void	setArguments (const FXString &args)
FXString	workingDir () const
void	setWorkingDir (const FXString &dir)
ReadChannel	readChannel () const throw ()
void	setReadChannel (ReadChannel channel)
FXlong	returnCode () const throw ()
void	detach ()
bool	waitForExit (FXuint waitfor=FXINFINITE)
bool	terminate ()
bool	open (FXuint mode=IO_ReadWrite)
void	close ()
void	flush ()
FXfval	size () const
FXuval	readBlock (char *data, FXuval maxlen)
FXuval	writeBlock (const char *data, FXuval maxlen)
int	ungetch (int)
virtual bool	isSynchronous () const
virtual void	truncate (FXfval)
virtual FXfval	at () const
virtual bool	at (FXfval)
virtual bool	atEnd () const
virtual FXuval	readBlockFrom (char *data, FXuval maxlen, FXfval pos)
FXuval	readBlockFrom (FXuchar *data, FXuval maxlen, FXfval pos)
virtual FXuval	writeBlockTo (FXfval pos, const char *data, FXuval maxlen)
FXuval	writeBlockTo (FXfval pos, const FXuchar *data, FXuval maxlen)
FXuint	flags () const
FXuint	mode () const
FXuint	state () const
CRLFType	crlfFormat () const
void	setCRLFFormat (CRLFType type)
UnicodeType	unicodeTranslation () const
void	setUnicodeTranslation (UnicodeType type)
bool	isBuffered () const
bool	isRaw () const
bool	isTranslated () const
bool	isUTF16Translated () const
bool	isUTF32Translated () const
bool	isReadable () const
bool	isWriteable () const
bool	isWritable () const
bool	isReadWrite () const
bool	isClosed () const
bool	isInactive () const
bool	isOpen () const
virtual const FXACL &	permissions () const
virtual void	setPermissions (const FXACL &)
FXuval	readBlock (FXuchar *data, FXuval maxlen)
FXuval	writeBlock (const FXuchar *data, FXuval maxlen)
virtual FXuval	readLine (char *data, FXuval maxlen)
virtual int	getch ()
virtual int	putch (int c)
FXfval	shredData (FXfval offset, FXfval len=(FXfval)-1)
Static Public Member Functions
static bool	waitForData (QIODeviceS signalled, FXuint no, QIODeviceS list, FXuint waitfor=FXINFINITE)
static FXuint	waitForDataMax () throw ()
static UnicodeType	determineUnicodeType (FXuchar *data, FXuval len) throw ()
static FXuval	applyCRLF (FXuchar FXRESTRICT output, const FXuchar FXRESTRICT input, FXuval outputlen, FXuval &inputlen, CRLFType crlftype=Default, UnicodeType utftype=NoTranslation)
static FXuval	removeCRLF (FXuchar FXRESTRICT output, const FXuchar FXRESTRICT input, FXuval outputlen, FXuval &inputlen, UnicodeType utftype=NoTranslation)
Protected Member Functions
void	setFlags (int f)
void	setMode (int m)
void	setState (int s)
Protected Attributes
FXfval	ioIndex
Friends
FXAPI FXStream &	operator<< (FXStream &s, QIODevice &i)
FXAPI FXStream &	operator>> (FXStream &s, QIODevice &i)

FX::QChildProcess Class Reference [Synchronous i/o devices]

Detailed Description

Usage:

Public Types

Public Member Functions

Static Public Member Functions

Protected Member Functions

Protected Attributes

Friends

Member Enumeration Documentation

Constructor & Destructor Documentation

Member Function Documentation

Friends And Related Function Documentation

FX::QChildProcess Class Reference
[Synchronous i/o devices]