Man Linux: Main Page and Category List

NAME

       redi::basic_pstreambuf - Class template for stream buffer.

SYNOPSIS

       #include <pstream.h>

       Inherits 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 &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.

   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.

   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 ()
       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.
       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 & 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()

   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()

   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
       () const [inline]
       Return the error number 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.

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

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

   template<typename C, typename T> bool redi::basic_pstreambuf< C, T
       >::fill_buffer () [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
       childs 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 systems 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 () 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.

   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 systems 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 >::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. 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. Note
       that exited() will return true if file cannot be executed, since the
       child process will have exited.

       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 > *
       redi::basic_pstreambuf< C, T >::open (const std::string & command,
       pmode mode)
       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.

       Will duplicate the actions of the shell in searching for an executable
       file if the specified file name does not contain a slash (/) character.

       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.

       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)

   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::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.

   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.

   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. 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.

   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.

   template<typename C, typename T> basic_pstreambuf< C, T >::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> basic_pstreambuf< C, T >::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> int redi::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()

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

   template<typename C, typename T> basic_pstreambuf< C, T >::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. 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.

   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<typename CharT, typename Traits = std::char_traits<CharT>> 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.