IXE::io::basic_pstreambuf< CharT, Traits > Class Template Reference

Class template for stream buffer. More...

#include <pstream.h>

Inheritance diagram for IXE::io::basic_pstreambuf< CharT, Traits >:

Collaboration diagram for IXE::io::basic_pstreambuf< CharT, Traits >:

List of all members.

Public Types

typedef CharT char_type

typedef Traits traits_type

typedef traits_type::int_type int_type

typedef traits_type::off_type off_type

typedef traits_type::pos_type pos_type

typedef int fd_type

Type used for file descriptors.

typedef fd_type fd_t

Public Member Functions

basic_pstreambuf ()

Default constructor.

basic_pstreambuf (const std::string &command, pmode mode)

Constructor that initialises the buffer with command.

basic_pstreambuf (const std::string &file, const argv_type &argv, pmode mode)

Constructor that initialises the buffer with file and argv.

~basic_pstreambuf ()

Destructor.

basic_pstreambuf * open (const std::string &command, pmode mode)

Initialise the stream buffer with command.

basic_pstreambuf * open (const std::string &file, const argv_type &argv, pmode mode)

Initialise the stream buffer with file and argv.

basic_pstreambuf * close ()

Close the stream buffer and wait for the process to exit.

basic_pstreambuf * kill (int signal=SIGTERM)

Send a signal to the process.

void peof ()

Close the pipe connected to the process' stdin.

bool read_err (bool readerr=true)

Change active input source.

bool is_open () const

Report whether the stream buffer has been initialised.

bool exited ()

Report whether the process has exited.

int status () const

Return the exit status of the process.

int error () const

Return the error number for the most recent failed operation.

Protected Types

enum buf_read_src { rsrc_out = 0, rsrc_err = 1 }

Enumerated type to indicate whether stdout or stderr is to be read.

Protected Member Functions

int_type overflow (int_type c)

Transfer characters to the pipe when character buffer overflows.

int_type underflow ()

Transfer characters from the pipe when the character buffer is empty.

int_type pbackfail (int_type c=traits_type::eof())

Make a character available to be returned by the next extraction.

int sync ()

Write any buffered characters to the stream.

std::streamsize xsputn (const char_type *s, std::streamsize n)

Insert multiple characters into the pipe.

std::streamsize write (char_type *s, std::streamsize n)

Insert a sequence of characters into the pipe.

std::streamsize read (char_type *s, std::streamsize n)

Extract a sequence of characters from the pipe.

pid_t fork (pmode mode)

Initialise pipes and fork process.

int wait (bool nohang=false)

Wait for the child process to exit.

fd_type & wpipe ()

Return the file descriptor for the output pipe.

fd_type & rpipe ()

Return the file descriptor for the active input pipe.

fd_type & rpipe (buf_read_src which)

Return the file descriptor for the specified input pipe.

void create_buffers (pmode mode)

void destroy_buffers (pmode mode)

bool empty_buffer ()

Writes buffered characters to the process' stdin pipe.

bool fill_buffer ()

char_type * rbuffer ()

Return the active input buffer.

buf_read_src switch_read_buffer (buf_read_src)

Related Functions

(Note that these are not member functions.)

void close_fd_array (int *filedes, std::size_t count)

Helper function to close an array of file descriptors.

Detailed Description

template<typename CharT, typename Traits = std::char_traits<CharT>>
class IXE::io::basic_pstreambuf< CharT, Traits >

Class template for stream buffer.

Definition at line 957 of file pstream.h.

Member Typedef Documentation

template<typename CharT , typename Traits = std::char_traits<CharT>>

typedef fd_type IXE::io::basic_pstreambuf< CharT, Traits >::fd_t

Deprecated:: use fd_type instead.

Definition at line 971 of file pstream.h.

Constructor & Destructor Documentation

template<typename C , typename T >

IXE::io::basic_pstreambuf< C, T >::basic_pstreambuf ( ) [inline]

Default constructor.

Creates an uninitialised stream buffer.

Definition at line 1761 of file pstream.h.

template<typename C , typename T >

IXE::io::basic_pstreambuf< C, T >::basic_pstreambuf	(	const std::string &	command,
		pmode	mode
	)			`[inline]`

Constructor that initialises the buffer with command.

Initialises the stream buffer by calling open() with the supplied arguments.

Parameters:

	command	a string containing a shell command.
	mode	the I/O mode to use when opening the pipe.

See also:: open()

Definition at line 1782 of file pstream.h.

References IXE::io::basic_pstreambuf< CharT, Traits >::open().

template<typename C , typename T >

IXE::io::basic_pstreambuf< C, T >::basic_pstreambuf	(	const std::string &	file,
		const argv_type &	argv,
		pmode	mode
	)			`[inline]`

Constructor that initialises the buffer with file and argv.

Initialises the stream buffer by calling open() with the supplied arguments.

Parameters:

	file	a string containing the name of a program to execute.
	argv	a vector of argument strings passsed to the new program.
	mode	the I/O mode to use when opening the pipe.

See also:: open()

Definition at line 1805 of file pstream.h.

References IXE::io::basic_pstreambuf< CharT, Traits >::open().

template<typename C , typename T >

IXE::io::basic_pstreambuf< C, T >::~basic_pstreambuf ( ) [inline]

Destructor.

Closes the stream by calling close().

See also:: close()

Definition at line 1825 of file pstream.h.

References IXE::io::basic_pstreambuf< CharT, Traits >::close().

Member Function Documentation

template<typename C , typename T >

basic_pstreambuf< C, T > * IXE::io::basic_pstreambuf< C, T >::close ( ) [inline]

Close the stream buffer and wait for the process to exit.

Closes all pipes and calls wait() to wait for the process to finish.

If an error occurs the error code will be set to one of the possible errors for waitpid(). See your system's documentation for these errors.

Returns:: this on successful close or NULL if there is no process to close or if an error occurs.

Definition at line 2103 of file pstream.h.

References IXE::io::basic_pstreambuf< CharT, Traits >::close_fd_array(), IXE::io::basic_pstreambuf< CharT, Traits >::is_open(), IXE::io::pstreams::pstderr, IXE::io::pstreams::pstdin, IXE::io::pstreams::pstdout, IXE::io::basic_pstreambuf< CharT, Traits >::sync(), and IXE::io::basic_pstreambuf< CharT, Traits >::wait().

Referenced by IXE::io::pstream_common< CharT, Traits >::close(), IXE::io::basic_pstreambuf< CharT, Traits >::fork(), and IXE::io::basic_pstreambuf< CharT, Traits >::~basic_pstreambuf().

template<typename C , typename T >

bool IXE::io::basic_pstreambuf< C, T >::empty_buffer ( ) [inline, protected]

Writes buffered characters to the process' stdin pipe.

Returns:: true if the buffer was emptied, false otherwise.

Definition at line 2422 of file pstream.h.

References IXE::io::basic_pstreambuf< CharT, Traits >::write().

Referenced by IXE::io::basic_pstreambuf< CharT, Traits >::overflow(), and IXE::io::basic_pstreambuf< CharT, Traits >::sync().

template<typename C , typename T >

int IXE::io::basic_pstreambuf< C, T >::error ( ) const [inline]

Return the error number for the most recent failed operation.

Returns:: The error code of the most recently failed operation, or zero.

Definition at line 2305 of file pstream.h.

template<typename C , typename T >

bool IXE::io::basic_pstreambuf< C, T >::exited ( ) [inline]

Report whether the process has exited.

Returns:: True if the associated process has exited, false otherwise.

See also:: basic_pstreambuf<C,T>::close()

Definition at line 2282 of file pstream.h.

References IXE::io::basic_pstreambuf< CharT, Traits >::wait().

Referenced by IXE::io::basic_pstreambuf< CharT, Traits >::sync(), and IXE::io::basic_pstreambuf< CharT, Traits >::wait().

template<typename C , typename T >

bool IXE::io::basic_pstreambuf< C, T >::fill_buffer ( ) [inline, protected]

Returns:: true if the buffer was filled, false otherwise.

Definition at line 2480 of file pstream.h.

References IXE::io::basic_pstreambuf< CharT, Traits >::rbuffer(), and IXE::io::basic_pstreambuf< CharT, Traits >::read().

Referenced by IXE::io::basic_pstreambuf< CharT, Traits >::underflow().

template<typename C , typename T >

pid_t IXE::io::basic_pstreambuf< C, T >::fork ( pmode mode ) [inline, protected]

Initialise pipes and fork process.

Creates pipes as specified by mode and calls fork() to create a new process.

If the fork is successful the parent process stores the child's PID and the opened pipes and the child process replaces its standard streams with the opened pipes.

If an error occurs the error code will be set to one of the possile errors for pipe() or fork(). See your system's documentation for these error codes.

Parameters:

mode

an OR of pmodes specifying which of the child's standard streams to connect to.

Returns:: On success the PID of the child is returned in the parent's context and zero is returned in the child's context. On error -1 is returned and the error code is set appropriately.

Definition at line 1985 of file pstream.h.

References IXE::io::basic_pstreambuf< CharT, Traits >::close(), IXE::io::basic_pstreambuf< CharT, Traits >::close_fd_array(), IXE::io::pstreams::pstderr, IXE::io::pstreams::pstdin, IXE::io::pstreams::pstdout, and IXE::io::basic_pstreambuf< CharT, Traits >::read_err().

Referenced by IXE::io::basic_pstreambuf< CharT, Traits >::open().

template<typename C , typename T >

bool IXE::io::basic_pstreambuf< C, T >::is_open ( ) const [inline]

Report whether the stream buffer has been initialised.

Returns:: true if a previous call to open() succeeded and wait() has not been called and determined that the process has exited, false otherwise.

Warning:: This function can not be used to determine whether the command used to initialise the buffer was successfully executed or not. If the shell command failed this function will still return true. You can use exited() to see if it's still open.

Definition at line 2335 of file pstream.h.

Referenced by IXE::io::basic_pstreambuf< CharT, Traits >::close(), IXE::io::pstream_common< CharT, Traits >::is_open(), IXE::io::basic_pstreambuf< CharT, Traits >::kill(), IXE::io::basic_pstreambuf< CharT, Traits >::open(), and IXE::io::basic_pstreambuf< CharT, Traits >::wait().

template<typename C , typename T >

basic_pstreambuf< C, T > * IXE::io::basic_pstreambuf< C, T >::kill ( int signal = SIGTERM ) [inline]

Send a signal to the process.

Sends the specified signal to the process.

A signal can be used to terminate a child process that would not exit otherwise.

If an error occurs the error code will be set to one of the possible errors for kill(). See your system's documentation for these errors.

Parameters:

signal

A signal to send to the child process.

Returns:: this or NULL if kill() fails.

Definition at line 2260 of file pstream.h.

References IXE::io::basic_pstreambuf< CharT, Traits >::is_open().

template<typename C , typename T >

basic_pstreambuf< C, T > * IXE::io::basic_pstreambuf< C, T >::open	(	const std::string &	file,
		const argv_type &	argv,
		pmode	mode
	)			`[inline]`

Initialise the stream buffer with file and argv.

Starts a new process by executing file with the arguments in argv and opens pipes to the process with the specified mode.

By convention argv[0] should be the file name of the file being executed. Will duplicate the actions of the shell in searching for an executable file if the specified file name does not contain a slash (/) character.

Parameters:

	file	a string containing the pathname of a program to execute.
	argv	a vector of argument strings passed to the new program.
	mode	a bitwise OR of one or more of `out`, `in` and `err`.

Returns:: NULL if a pipe could not be opened or if the program could not be executed, this otherwise.

See also:: execvp(3)

Definition at line 1900 of file pstream.h.

References IXE::io::basic_pstreambuf< CharT, Traits >::fork(), and IXE::io::basic_pstreambuf< CharT, Traits >::is_open().

template<typename C , typename T >

basic_pstreambuf< C, T > * IXE::io::basic_pstreambuf< C, T >::open	(	const std::string &	command,
		pmode	mode
	)			`[inline]`

Initialise the stream buffer with command.

Starts a new process by passing command to the shell and opens pipes to the process with the specified mode.

There is no way to tell whether the shell command succeeded, this function will always succeed unless resource limits (such as memory usage, or number of processes or open files) are exceeded.

Parameters:

	command	a string containing a shell command.
	mode	a bitwise OR of one or more of `out`, `in`, `err`.

Returns:: NULL if the shell could not be started or the pipes could not be opened, this otherwise.

See also:: execlp(3)

Definition at line 1846 of file pstream.h.

References IXE::io::basic_pstreambuf< CharT, Traits >::fork(), and IXE::io::basic_pstreambuf< CharT, Traits >::is_open().

Referenced by IXE::io::basic_pstreambuf< CharT, Traits >::basic_pstreambuf(), and IXE::io::pstream_common< CharT, Traits >::do_open().

template<typename C , typename T >

basic_pstreambuf< C, T >::int_type IXE::io::basic_pstreambuf< C, T >::overflow ( int_type c ) [inline, protected]

Transfer characters to the pipe when character buffer overflows.

Called when the internal character buffer is not present or is full, to transfer the buffer contents to the pipe.

For unbuffered streams this is called for every insertion.

Parameters:

c

a character to be written to the pipe.

Returns:: traits_type::not_eof(c) if c is equal to traits_type::eof(). Otherwise returns c if c can be written to the pipe, or traits_type::eof() if not.

Definition at line 2373 of file pstream.h.

References IXE::io::basic_pstreambuf< CharT, Traits >::empty_buffer().

template<typename C , typename T >

basic_pstreambuf< C, T >::int_type IXE::io::basic_pstreambuf< C, T >::pbackfail ( int_type c = traits_type::eof() ) [inline, protected]

Make a character available to be returned by the next extraction.

Attempts to make c available as the next character to be read by sgetc().

Parameters:

c

a character to make available for extraction.

Returns:: c if the character can be made available, traits_type::eof() otherwise.

Definition at line 2462 of file pstream.h.

template<typename C , typename T >

void IXE::io::basic_pstreambuf< C, T >::peof ( ) [inline]

Close the pipe connected to the process' stdin.

Closes the output pipe, causing the child process to receive the End Of File indicator on subsequent reads from its stdin stream.

Definition at line 2316 of file pstream.h.

References IXE::io::basic_pstreambuf< CharT, Traits >::close_fd_array(), and IXE::io::basic_pstreambuf< CharT, Traits >::sync().

template<typename C , typename T >

basic_pstreambuf< C, T >::char_type * IXE::io::basic_pstreambuf< C, T >::rbuffer ( ) [inline, protected]

Return the active input buffer.

Returns:: a pointer to the start of the active input buffer area.

Definition at line 2565 of file pstream.h.

Referenced by IXE::io::basic_pstreambuf< CharT, Traits >::fill_buffer().

template<typename C , typename T >

std::streamsize IXE::io::basic_pstreambuf< C, T >::read	(	char_type *	s,
		std::streamsize	n
	)			`[inline, protected]`

Extract a sequence of characters from the pipe.

Reads up to n characters from the pipe to the buffer s.

This currently only works for fixed width character encodings where each character uses sizeof(char_type) bytes.

Parameters:

	s	character buffer.
	n	buffer length.

Returns:: the number of characters read.

Definition at line 2533 of file pstream.h.

References IXE::io::basic_pstreambuf< CharT, Traits >::rpipe().

Referenced by IXE::io::basic_pstreambuf< CharT, Traits >::fill_buffer().

template<typename C , typename T >

bool IXE::io::basic_pstreambuf< C, T >::read_err ( bool readerr = true ) [inline]

Change active input source.

Toggle the stream used for reading.

If readerr is true then the process' stderr output will be used for subsequent extractions, if readerr is false the the process' stdout will be used.

Parameters:

readerr true to read stderr, false to read stdout.

Returns:: true if the requested stream is open and will be used for subsequent extractions, false otherwise.

Definition at line 2350 of file pstream.h.

Referenced by IXE::io::basic_pstreambuf< CharT, Traits >::fork().

template<typename C , typename T >

basic_pstreambuf< C, T >::fd_type & IXE::io::basic_pstreambuf< C, T >::rpipe ( buf_read_src which ) [inline, protected]

Return the file descriptor for the specified input pipe.

Returns:: a reference to the specified input file descriptor

Definition at line 2557 of file pstream.h.

template<typename C , typename T >

basic_pstreambuf< C, T >::fd_type & IXE::io::basic_pstreambuf< C, T >::rpipe ( ) [inline, protected]

Return the file descriptor for the active input pipe.

Returns:: a reference to the active input file descriptor

Definition at line 2549 of file pstream.h.

Referenced by IXE::io::basic_pstreambuf< CharT, Traits >::read().

template<typename C , typename T >

int IXE::io::basic_pstreambuf< C, T >::status ( ) const [inline]

Return the exit status of the process.

Returns:: The exit status of the child process, or -1 if close() has not yet been called to wait for the child to exit.

See also:: basic_pstreambuf<C,T>::close()

Definition at line 2295 of file pstream.h.

Referenced by IXE::io::basic_pstreambuf< CharT, Traits >::wait().

template<typename C , typename T >

basic_pstreambuf< C, T >::int_type IXE::io::basic_pstreambuf< C, T >::underflow ( ) [inline, protected]

Transfer characters from the pipe when the character buffer is empty.

Called when the internal character buffer is is empty, to re-fill it from the pipe.

Returns:: The first available character in the buffer, or traits_type::eof() in case of failure.

See also:: uflow()

Definition at line 2444 of file pstream.h.

References IXE::io::basic_pstreambuf< CharT, Traits >::fill_buffer().

template<typename C , typename T >

int IXE::io::basic_pstreambuf< C, T >::wait ( bool nohang = false ) [inline, protected]

Wait for the child process to exit.

Suspends execution and waits for the associated process to exit, or until a signal is delivered whose action is to terminate the current process or to call a signal handling function.

If the process has already exited wait() returns immediately.

Parameters:

nohang

true to return immediately if the process has not exited.

Returns:: 1 if the process has exited. 0 if nohang is true and the process has not exited yet. -1 if no process has been started or if an error occurs, in which case the error can be found using error().

Definition at line 2219 of file pstream.h.

References IXE::io::basic_pstreambuf< CharT, Traits >::close_fd_array(), IXE::io::basic_pstreambuf< CharT, Traits >::exited(), IXE::io::basic_pstreambuf< CharT, Traits >::is_open(), and IXE::io::basic_pstreambuf< CharT, Traits >::status().

Referenced by IXE::io::basic_pstreambuf< CharT, Traits >::close(), and IXE::io::basic_pstreambuf< CharT, Traits >::exited().

template<typename C , typename T >

basic_pstreambuf< C, T >::fd_type & IXE::io::basic_pstreambuf< C, T >::wpipe ( ) [inline, protected]

Return the file descriptor for the output pipe.

Returns:: a reference to the output file descriptor

Definition at line 2541 of file pstream.h.

Referenced by IXE::io::basic_pstreambuf< CharT, Traits >::write().

template<typename C , typename T >

std::streamsize IXE::io::basic_pstreambuf< C, T >::write	(	char_type *	s,
		std::streamsize	n
	)			`[inline, protected]`

Insert a sequence of characters into the pipe.

Writes up to n characters to the pipe from the buffer s.

This currently only works for fixed width character encodings where each character uses sizeof(char_type) bytes.

Parameters:

	s	character buffer.
	n	buffer length.

Returns:: the number of characters written.

Definition at line 2517 of file pstream.h.

References IXE::io::basic_pstreambuf< CharT, Traits >::wpipe().

Referenced by IXE::io::basic_pstreambuf< CharT, Traits >::empty_buffer().

template<typename C , typename T >

std::streamsize IXE::io::basic_pstreambuf< C, T >::xsputn	(	const char_type *	s,
		std::streamsize	n
	)			`[inline, protected]`

Insert multiple characters into the pipe.

Parameters:

	s	character buffer.
	n	buffer length.

Returns:: the number of characters written.

Definition at line 2398 of file pstream.h.

Friends And Related Function Documentation

template<typename CharT , typename Traits = std::char_traits<CharT>>

void close_fd_array	(	int *	filedes,
		std::size_t	count
	)			`[related]`

Helper function to close an array of file descriptors.

Inspects each of the count file descriptors in the array filedes and calls close() if they have a non-negative value.

Parameters:

	filedes	an array of file descriptors
	count	size of the array.

Definition at line 1959 of file pstream.h.

Referenced by IXE::io::basic_pstreambuf< CharT, Traits >::close(), IXE::io::basic_pstreambuf< CharT, Traits >::fork(), IXE::io::basic_pstreambuf< CharT, Traits >::peof(), and IXE::io::basic_pstreambuf< CharT, Traits >::wait().

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

ixe/io/pstream.h


Public Types
typedef CharT	char_type
typedef Traits	traits_type
typedef traits_type::int_type	int_type
typedef traits_type::off_type	off_type
typedef traits_type::pos_type	pos_type
typedef int	fd_type
	Type used for file descriptors.
typedef fd_type	fd_t
Public Member Functions
	basic_pstreambuf ()
	Default constructor.
	basic_pstreambuf (const std::string &command, pmode mode)
	Constructor that initialises the buffer with command.
	basic_pstreambuf (const std::string &file, const argv_type &argv, pmode mode)
	Constructor that initialises the buffer with file and argv.
	~basic_pstreambuf ()
	Destructor.
basic_pstreambuf *	open (const std::string &command, pmode mode)
	Initialise the stream buffer with command.
basic_pstreambuf *	open (const std::string &file, const argv_type &argv, pmode mode)
	Initialise the stream buffer with file and argv.
basic_pstreambuf *	close ()
	Close the stream buffer and wait for the process to exit.
basic_pstreambuf *	kill (int signal=SIGTERM)
	Send a signal to the process.
void	peof ()
	Close the pipe connected to the process' stdin.
bool	read_err (bool readerr=true)
	Change active input source.
bool	is_open () const
	Report whether the stream buffer has been initialised.
bool	exited ()
	Report whether the process has exited.
int	status () const
	Return the exit status of the process.
int	error () const
	Return the error number for the most recent failed operation.
Protected Types
enum	buf_read_src { rsrc_out = 0, rsrc_err = 1 }
	Enumerated type to indicate whether stdout or stderr is to be read.
Protected Member Functions
int_type	overflow (int_type c)
	Transfer characters to the pipe when character buffer overflows.
int_type	underflow ()
	Transfer characters from the pipe when the character buffer is empty.
int_type	pbackfail (int_type c=traits_type::eof())
	Make a character available to be returned by the next extraction.
int	sync ()
	Write any buffered characters to the stream.
std::streamsize	xsputn (const char_type *s, std::streamsize n)
	Insert multiple characters into the pipe.
std::streamsize	write (char_type *s, std::streamsize n)
	Insert a sequence of characters into the pipe.
std::streamsize	read (char_type *s, std::streamsize n)
	Extract a sequence of characters from the pipe.
pid_t	fork (pmode mode)
	Initialise pipes and fork process.
int	wait (bool nohang=false)
	Wait for the child process to exit.
fd_type &	wpipe ()
	Return the file descriptor for the output pipe.
fd_type &	rpipe ()
	Return the file descriptor for the active input pipe.
fd_type &	rpipe (buf_read_src which)
	Return the file descriptor for the specified input pipe.
void	create_buffers (pmode mode)
void	destroy_buffers (pmode mode)
bool	empty_buffer ()
	Writes buffered characters to the process' stdin pipe.
bool	fill_buffer ()
char_type *	rbuffer ()
	Return the active input buffer.
buf_read_src	switch_read_buffer (buf_read_src)
Related Functions
(Note that these are not member functions.)
void	close_fd_array (int *filedes, std::size_t count)
	Helper function to close an array of file descriptors.

IXE::io::basic_pstreambuf< CharT, Traits > Class Template Reference

Public Types

Public Member Functions

Protected Types

Protected Member Functions

Related Functions

Detailed Description

template<typename CharT, typename Traits = std::char_traits<CharT>> class IXE::io::basic_pstreambuf< CharT, Traits >

Member Typedef Documentation

Constructor & Destructor Documentation

Member Function Documentation

Friends And Related Function Documentation

template<typename CharT, typename Traits = std::char_traits<CharT>>
class IXE::io::basic_pstreambuf< CharT, Traits >