Provided by: libpstreams-dev_1.0.3-1_all 
NAME
redi::basic_pstreambuf - Class template for stream buffer
SYNOPSIS
#include <pstream.h>
Inherits basic_streambuf< CharT, std::char_traits< CharT > >, and redi::pstreams.
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 fd_type fd_t
typedef std::ios_base::openmode pmode
Type used to specify how to connect to the process.
typedef std::vector< std::string > argv_type
Type used to hold the arguments for a command.
typedef int fd_type
Type used for file descriptors.
Public Member Functions
basic_pstreambuf ()
Default constructor.
basic_pstreambuf (const std::string &cmd, pmode mode)
Constructor that initialises the buffer with cmd.
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 &cmd, pmode mode)
Initialise the stream buffer with cmd.
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.
basic_pstreambuf * killpg (int signal=SIGTERM)
Send a signal to the process' process group.
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 (errno) for the most recent failed operation.
Static Public Attributes
static const pmode pstdin = std::ios_base::out
Write to stdin.
static const pmode pstdout = std::ios_base::in
Read from stdout.
static const pmode pstderr = std::ios_base::app
Read from stderr.
static const pmode newpg = std::ios_base::trunc
Create a new process group for the child process.
Protected Types
enum buf_read_src { rsrc_out = 0, rsrc_err = 1 }
Enumerated type to indicate whether stdout or stderr is to be read.
enum { bufsz = 32 }
enum { pbsz = 2 }
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 (const 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.
std::streamsize showmanyc ()
Report how many characters can be read from active input without blocking.
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 (bool non_blocking=false)
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 (pstreams::fd_type &fd)
Helper function to close a file descriptor.
template<int N> void close_fd_array (pstreams::fd_type(&fds)[N])
Helper function to close an array of file descriptors.
Detailed Description
template<typename CharT, typename Traits = std::char_traits<CharT>>
class redi::basic_pstreambuf< CharT, Traits >" Class template for stream buffer.
Provides underlying streambuf functionality for the PStreams classes.
Member Typedef Documentation
template<typename CharT , typename Traits = std::char_traits<CharT>> typedef fd_type
redi::basic_pstreambuf< CharT, Traits >::fd_t
Deprecated
use pstreams::fd_type instead.
Constructor & Destructor Documentation
template<typename C , typename T > redi::basic_pstreambuf< C, T >::basic_pstreambuf [inline]
Default constructor. Creates an uninitialised stream buffer.
template<typename C , typename T > redi::basic_pstreambuf< C, T >::basic_pstreambuf (const
std::string & cmd, pmode mode) [inline]
Constructor that initialises the buffer with cmd. Initialises the stream buffer by calling
open() with the supplied arguments.
Parameters
cmd a string containing a shell command.
mode the I/O mode to use when opening the pipe.
See also
open()
References redi::basic_pstreambuf< CharT, Traits >::open().
template<typename C , typename T > redi::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()
References redi::basic_pstreambuf< CharT, Traits >::open().
template<typename C , typename T > redi::basic_pstreambuf< C, T >::~basic_pstreambuf [inline]
Destructor. Closes the stream by calling close().
See also
close()
Member Function Documentation
template<typename C , typename T > basic_pstreambuf< C, T > * redi::basic_pstreambuf< C, T
>::close
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.
template<typename C , typename T > bool redi::basic_pstreambuf< C, T >::empty_buffer
[protected]
Writes buffered characters to the process' stdin pipe.
Returns
true if the buffer was emptied, false otherwise.
template<typename C , typename T > int redi::basic_pstreambuf< C, T >::error [inline]
Return the error number (errno) for the most recent failed operation.
Returns
The error code of the most recently failed operation, or zero.
template<typename C , typename T > bool redi::basic_pstreambuf< C, T >::exited [inline]
Report whether the process has exited. This function can call pstreambuf::wait() and so
may change the object's state if the child process has already exited.
Returns
True if the associated process has exited, false otherwise.
See also
basic_pstreambuf<C,T>::wait()
template<typename C , typename T > bool redi::basic_pstreambuf< C, T >::fill_buffer (bool
non_blocking = false) [protected]
Returns
true if the buffer was filled, false otherwise.
template<typename C , typename T > pid_t redi::basic_pstreambuf< C, T >::fork (pmode mode)
[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 possible 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.
template<typename C , typename T > bool redi::basic_pstreambuf< C, T >::is_open [inline]
Report whether the stream buffer has been initialised. Unlike pstreambuf::exited(), this
function will not call wait() and so will not change the object's state. This means that
once a child process is executed successfully this function will continue to return true
even after the process exits (until wait() is called.)
Returns
true if a previous call to open() succeeded and wait() has not been called and
determined that the process has exited, false otherwise.
template<typename C , typename T > basic_pstreambuf< C, T > * redi::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.
template<typename C , typename T > basic_pstreambuf< C, T > * redi::basic_pstreambuf< C, T
>::killpg (int signal = SIGTERM) [inline]
Send a signal to the process' process group. Sends the specified signal to the process
group of the child process. A signal can be used to terminate a child process that would
not exit otherwise, or to kill the process and its own children.
If an error occurs the error code will be set to one of the possible errors for getpgid()
or kill(). See your system's documentation for these errors. If the child is in the
current process group then NULL will be returned and the error code set to EPERM.
Parameters
signal A signal to send to the child process.
Returns
this on success or NULL on failure.
template<typename C , typename T > basic_pstreambuf< C, T > * redi::basic_pstreambuf< C, T
>::open (const std::string & command, pmode mode)
Initialise the stream buffer with cmd. Starts a new process by passing command to the
shell (/bin/sh) and opens pipes to the process with the specified mode.
If mode contains pstdout the initial read source will be the child process' stdout,
otherwise if mode contains pstderr the initial read source will be the child's stderr.
Will duplicate the actions of the shell in searching for an executable file if the
specified file name does not contain a slash (/) character.
Warning
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. This means is_open() will return true even if command cannot be
executed. Use pstreambuf::open(const std::string&, const argv_type&, pmode) if you
need to know whether the command failed to execute.
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
execl(3)
Referenced by redi::basic_pstreambuf< CharT, Traits >::basic_pstreambuf().
template<typename C , typename T > basic_pstreambuf< C, T > * redi::basic_pstreambuf< C, T
>::open (const std::string & file, const argv_type & argv, pmode mode)
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.
If mode contains pstdout the initial read source will be the child process' stdout,
otherwise if mode contains pstderr the initial read source will be the child's stderr.
Will duplicate the actions of the shell in searching for an executable file if the
specified file name does not contain a slash (/) character.
Iff file is successfully executed then is_open() will return true. Otherwise,
pstreambuf::error() can be used to obtain the value of errno that was set by execvp(3) in
the child process.
The exit status of the new process will be returned by pstreambuf::status() after
pstreambuf::exited() returns true.
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)
template<typename C , typename T > basic_pstreambuf< C, T >::int_type redi::basic_pstreambuf<
C, T >::overflow (int_type c) [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.
Parameters
c a character to be written to the pipe.
Returns
traits_type::eof() if an error occurs, otherwise if c is not equal to
traits_type::eof() it will be buffered and a value other than traits_type::eof()
returned to indicate success.
template<typename C , typename T > basic_pstreambuf< C, T >::int_type redi::basic_pstreambuf<
C, T >::pbackfail (int_type c = traits_type::eof()) [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.
template<typename C , typename T > void redi::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.
Referenced by redi::basic_opstream< CharT, Traits >::peof().
template<typename C , typename T > basic_pstreambuf< C, T >::char_type *
redi::basic_pstreambuf< C, T >::rbuffer [inline], [protected]
Return the active input buffer.
Returns
a pointer to the start of the active input buffer area.
template<typename C , typename T > std::streamsize redi::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.
Parameters
s character buffer.
n buffer length.
Returns
the number of characters read.
template<typename C , typename T > bool redi::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.
Referenced by redi::basic_ipstream< CharT, Traits >::err(), redi::basic_pstream< CharT,
Traits >::err(), redi::basic_rpstream< CharT, Traits >::err(), redi::basic_ipstream<
CharT, Traits >::out(), redi::basic_pstream< CharT, Traits >::out(), and
redi::basic_rpstream< CharT, Traits >::out().
template<typename C , typename T > pstreams::fd_type & redi::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
template<typename C , typename T > pstreams::fd_type & redi::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
template<typename C , typename T > int redi::basic_pstreambuf< C, T >::status [inline]
Return the exit status of the process.
Returns
The exit status of the child process, or -1 if wait() has not yet been called to wait
for the child to exit.
See also
basic_pstreambuf<C,T>::wait()
template<typename C , typename T > basic_pstreambuf< C, T >::int_type redi::basic_pstreambuf<
C, T >::underflow [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.
template<typename C , typename T > int redi::basic_pstreambuf< C, T >::wait (bool nohang =
false) [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 (i.e. it
is a 'zombie' process) then wait() returns immediately. Waiting for the child process
causes all its system resources to be freed.
error() will return EINTR if wait() is interrupted by a signal.
Parameters
nohang true to return immediately if the process has not exited.
Returns
1 if the process has exited and wait() has not yet been called. 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().
template<typename C , typename T > pstreams::fd_type & redi::basic_pstreambuf< C, T >::wpipe
[inline], [protected]
Return the file descriptor for the output pipe.
Returns
a reference to the output file descriptor
template<typename C , typename T > std::streamsize redi::basic_pstreambuf< C, T >::write
(const 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.
Parameters
s character buffer.
n buffer length.
Returns
the number of characters written.
template<typename C , typename T > std::streamsize redi::basic_pstreambuf< C, T >::xsputn
(const char_type * s, std::streamsize n) [protected]
Insert multiple characters into the pipe.
Parameters
s character buffer.
n buffer length.
Returns
the number of characters written.
Friends And Related Function Documentation
template<typename CharT , typename Traits = std::char_traits<CharT>> void close_fd
(pstreams::fd_type & fd) [related]
Helper function to close a file descriptor. Inspects fd and calls close(3) if it has a
non-negative value.
Parameters
fd a file descriptor.
template<int N> void close_fd_array (pstreams::fd_type(&) fds[N]) [related]
Helper function to close an array of file descriptors. Calls close_fd() on each member of
the array. The length of the array is determined automatically by template argument
deduction to avoid errors.
Parameters
fds an array of file descriptors.
Author
Generated automatically by Doxygen for PStreams from the source code.
PStreams Sun Dec 13 202redi::basic_pstreambuf< CharT, Traits >(3)