deleted: src/include/pstream.h

git-svn-id: http://svn.miranda-ng.org/main/trunk@3408 1316c22d-e87f-b044-9b9b-93d7a3e3ba9c

1 files changed, 0 insertions, 2095 deletions

diff --git a/plugins/New_GPG/src/include/pstream.h b/plugins/New_GPG/src/include/pstream.h
deleted file mode 100644
index c0a1f964dd..0000000000
--- a/plugins/New_GPG/src/include/pstream.h
+++ /dev/null
@@ -1,2095 +0,0 @@
-/* $Id: pstream.h,v 1.112 2010/03/20 14:50:47 redi Exp $
-PStreams - POSIX Process I/O for C++
-Copyright (C) 2001,2002,2003,2004,2005,2006,2007,2008 Jonathan Wakely
-
-This file is part of PStreams.
-
-PStreams is free software; you can redistribute it and/or modify
-it under the terms of the GNU Lesser General Public License as published by
-the Free Software Foundation; either version 3 of the License, or
-(at your option) any later version.
-
-PStreams is distributed in the hope that it will be useful,
-but WITHOUT ANY WARRANTY; without even the implied warranty of
-MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
-GNU Lesser General Public License for more details.
-
-You should have received a copy of the GNU Lesser General Public License
-along with this program.  If not, see <http://www.gnu.org/licenses/>.
-*/
-
-/**
- * @file pstream.h
- * @brief Declares all PStreams classes.
- * @author Jonathan Wakely
- *
- * Defines classes redi::ipstream, redi::opstream, redi::pstream
- * and redi::rpstream.
- */
-
-#ifndef REDI_PSTREAM_H_SEEN
-#define REDI_PSTREAM_H_SEEN
-
-#include <ios>
-#include <streambuf>
-#include <istream>
-#include <ostream>
-#include <string>
-#include <vector>
-#include <algorithm>    // for min()
-#include <cerrno>       // for errno
-#include <cstddef>      // for size_t
-#include <cstdlib>      // for exit()
-#include <sys/types.h>  // for pid_t
-#include <sys/wait.h>   // for waitpid()
-#include <sys/ioctl.h>  // for ioctl() and FIONREAD
-#if defined(__sun)
-# include <sys/filio.h> // for FIONREAD on Solaris 2.5
-#endif
-#include <unistd.h>     // for pipe() fork() exec() and filedes functions
-#include <signal.h>     // for kill()
-#include <fcntl.h>      // for fcntl()
-#if REDI_EVISCERATE_PSTREAMS
-# include <stdio.h>     // for FILE, fdopen()
-#endif
-
-
-/// The library version.
-#define PSTREAMS_VERSION 0x0070   // 0.7.0
-
-/**
- *  @namespace redi
- *  @brief  All PStreams classes are declared in namespace redi.
- *
- *  Like the standard iostreams, PStreams is a set of class templates,
- *  taking a character type and traits type. As with the standard streams
- *  they are most likely to be used with @c char and the default
- *  traits type, so typedefs for this most common case are provided.
- *
- *  The @c pstream_common class template is not intended to be used directly,
- *  it is used internally to provide the common functionality for the
- *  other stream classes.
- */
-namespace redi
-{
-  /// Common base class providing constants and typenames.
-  struct pstreams
-  {
-    /// Type used to specify how to connect to the process.
-    typedef std::ios_base::openmode           pmode;
-
-    /// Type used to hold the arguments for a command.
-    typedef std::vector<std::string>          argv_type;
-
-    /// Type used for file descriptors.
-    typedef int                               fd_type;
-
-    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:
-    enum { bufsz = 32 };  ///< Size of pstreambuf buffers.
-    enum { pbsz  = 2 };   ///< Number of putback characters kept.
-  };
-
-  /// Class template for stream buffer.
-  template <typename CharT, typename Traits = std::char_traits<CharT> >
-    class basic_pstreambuf
-    : public std::basic_streambuf<CharT, Traits>
-    , public pstreams
-    {
-    public:
-      // Type definitions for dependent types
-      typedef CharT                             char_type;
-      typedef Traits                            traits_type;
-      typedef typename traits_type::int_type    int_type;
-      typedef typename traits_type::off_type    off_type;
-      typedef typename traits_type::pos_type    pos_type;
-      /** @deprecated use pstreams::fd_type instead. */
-      typedef fd_type                           fd_t;
-
-      /// Default constructor.
-      basic_pstreambuf();
-
-      /// Constructor that initialises the buffer with @a command.
-      basic_pstreambuf(const std::string& command, pmode mode);
-
-      /// Constructor that initialises the buffer with @a file and @a argv.
-      basic_pstreambuf( const std::string& file,
-                        const argv_type& argv,
-                        pmode mode );
-
-      /// Destructor.
-      ~basic_pstreambuf();
-
-      /// Initialise the stream buffer with @a command.
-      basic_pstreambuf*
-      open(const std::string& command, pmode mode);
-
-      /// Initialise the stream buffer with @a file and @a argv.
-      basic_pstreambuf*
-      open(const std::string& file, const argv_type& argv, pmode mode);
-
-      /// Close the stream buffer and wait for the process to exit.
-      basic_pstreambuf*
-      close();
-
-      /// Send a signal to the process.
-      basic_pstreambuf*
-      kill(int signal = SIGTERM);
-
-      /// Close the pipe connected to the process' stdin.
-      void
-      peof();
-
-      /// Change active input source.
-      bool
-      read_err(bool readerr = true);
-
-      /// Report whether the stream buffer has been initialised.
-      bool
-      is_open() const;
-
-      /// Report whether the process has exited.
-      bool
-      exited();
-
-#if REDI_EVISCERATE_PSTREAMS
-      /// Obtain FILE pointers for each of the process' standard streams.
-      std::size_t
-      fopen(FILE*& in, FILE*& out, FILE*& err);
-#endif
-
-      /// Return the exit status of the process.
-      int
-      status() const;
-
-      /// Return the error number (errno) for the most recent failed operation.
-      int
-      error() const;
-
-    protected:
-      /// Transfer characters to the pipe when character buffer overflows.
-      int_type
-      overflow(int_type c);
-
-      /// Transfer characters from the pipe when the character buffer is empty.
-      int_type
-      underflow();
-
-      /// Make a character available to be returned by the next extraction.
-      int_type
-      pbackfail(int_type c = traits_type::eof());
-
-      /// Write any buffered characters to the stream.
-      int
-      sync();
-
-      /// Insert multiple characters into the pipe.
-      std::streamsize
-      xsputn(const char_type* s, std::streamsize n);
-
-      /// Insert a sequence of characters into the pipe.
-      std::streamsize
-      write(const char_type* s, std::streamsize n);
-
-      /// Extract a sequence of characters from the pipe.
-      std::streamsize
-      read(char_type* s, std::streamsize n);
-
-      /// Report how many characters can be read from active input without blocking.
-      std::streamsize
-      showmanyc();
-
-    protected:
-      /// Enumerated type to indicate whether stdout or stderr is to be read.
-      enum buf_read_src { rsrc_out = 0, rsrc_err = 1 };
-
-      /// Initialise pipes and fork process.
-      pid_t
-      fork(pmode mode);
-
-      /// Wait for the child process to exit.
-      int
-      wait(bool nohang = false);
-
-      /// Return the file descriptor for the output pipe.
-      fd_type&
-      wpipe();
-
-      /// Return the file descriptor for the active input pipe.
-      fd_type&
-      rpipe();
-
-      /// Return the file descriptor for the specified input pipe.
-      fd_type&
-      rpipe(buf_read_src which);
-
-      void
-      create_buffers(pmode mode);
-
-      void
-      destroy_buffers(pmode mode);
-
-      /// Writes buffered characters to the process' stdin pipe.
-      bool
-      empty_buffer();
-
-      bool
-      fill_buffer(bool non_blocking = false);
-
-      /// Return the active input buffer.
-      char_type*
-      rbuffer();
-
-      buf_read_src
-      switch_read_buffer(buf_read_src);
-
-    private:
-      basic_pstreambuf(const basic_pstreambuf&);
-      basic_pstreambuf& operator=(const basic_pstreambuf&);
-
-      void
-      init_rbuffers();
-
-      pid_t         ppid_;        // pid of process
-      fd_type       wpipe_;       // pipe used to write to process' stdin
-      fd_type       rpipe_[2];    // two pipes to read from, stdout and stderr
-      char_type*    wbuffer_;
-      char_type*    rbuffer_[2];
-      char_type*    rbufstate_[3];
-      /// Index into rpipe_[] to indicate active source for read operations.
-      buf_read_src  rsrc_;
-      int           status_;      // hold exit status of child process
-      int           error_;       // hold errno if fork() or exec() fails
-    };
-
-  /// Class template for common base class.
-  template <typename CharT, typename Traits = std::char_traits<CharT> >
-    class pstream_common
-    : virtual public std::basic_ios<CharT, Traits>
-    , virtual public pstreams
-    {
-    protected:
-      typedef basic_pstreambuf<CharT, Traits>       streambuf_type;
-
-      typedef pstreams::pmode                       pmode;
-      typedef pstreams::argv_type                   argv_type;
-
-      /// Default constructor.
-      pstream_common();
-
-      /// Constructor that initialises the stream by starting a process.
-      pstream_common(const std::string& command, pmode mode);
-
-      /// Constructor that initialises the stream by starting a process.
-      pstream_common(const std::string& file, const argv_type& argv, pmode mode);
-
-      /// Pure virtual destructor.
-      virtual
-      ~pstream_common() = 0;
-
-      /// Start a process.
-      void
-      do_open(const std::string& command, pmode mode);
-
-      /// Start a process.
-      void
-      do_open(const std::string& file, const argv_type& argv, pmode mode);
-
-    public:
-      /// Close the pipe.
-      void
-      close();
-
-      /// Report whether the stream's buffer has been initialised.
-      bool
-      is_open() const;
-
-      /// Return the command used to initialise the stream.
-      const std::string&
-      command() const;
-
-      /// Return a pointer to the stream buffer.
-      streambuf_type*
-      rdbuf() const;
-
-#if REDI_EVISCERATE_PSTREAMS
-      /// Obtain FILE pointers for each of the process' standard streams.
-      std::size_t
-      fopen(FILE*& in, FILE*& out, FILE*& err);
-#endif
-
-    protected:
-      std::string       command_; ///< The command used to start the process.
-      streambuf_type    buf_;     ///< The stream buffer.
-    };
-
-
-  /**
-   * @class basic_ipstream
-   * @brief Class template for Input PStreams.
-   *
-   * Reading from an ipstream reads the command's standard output and/or
-   * standard error (depending on how the ipstream is opened)
-   * and the command's standard input is the same as that of the process
-   * that created the object, unless altered by the command itself.
-   */
-
-  template <typename CharT, typename Traits = std::char_traits<CharT> >
-    class basic_ipstream
-    : public std::basic_istream<CharT, Traits>
-    , public pstream_common<CharT, Traits>
-    , virtual public pstreams
-    {
-      typedef std::basic_istream<CharT, Traits>     istream_type;
-      typedef pstream_common<CharT, Traits>         pbase_type;
-
-      using pbase_type::buf_;  // declare name in this scope
-
-      pmode readable(pmode mode)
-      {
-        if (!(mode & (pstdout|pstderr)))
-          mode |= pstdout;
-        return mode;
-      }
-
-    public:
-      /// Type used to specify how to connect to the process.
-      typedef typename pbase_type::pmode            pmode;
-
-      /// Type used to hold the arguments for a command.
-      typedef typename pbase_type::argv_type        argv_type;
-
-      /// Default constructor, creates an uninitialised stream.
-      basic_ipstream()
-      : istream_type(NULL), pbase_type()
-      { }
-
-      /**
-       * @brief Constructor that initialises the stream by starting a process.
-       *
-       * Initialises the stream buffer by calling do_open() with the supplied
-       * arguments.
-       *
-       * @param command  a string containing a shell command.
-       * @param mode     the I/O mode to use when opening the pipe.
-       * @see   do_open(const std::string&, pmode)
-       */
-      basic_ipstream(const std::string& command, pmode mode = pstdout)
-      : istream_type(NULL), pbase_type(command, readable(mode))
-      { }
-
-      /**
-       * @brief Constructor that initialises the stream by starting a process.
-       *
-       * Initialises the stream buffer by calling do_open() with the supplied
-       * arguments.
-       *
-       * @param file  a string containing the pathname of a program to execute.
-       * @param argv  a vector of argument strings passed to the new program.
-       * @param mode  the I/O mode to use when opening the pipe.
-       * @see   do_open(const std::string&, const argv_type&, pmode)
-       */
-      basic_ipstream( const std::string& file,
-                      const argv_type& argv,
-                      pmode mode = pstdout )
-      : istream_type(NULL), pbase_type(file, argv, readable(mode))
-      { }
-
-      /**
-       * @brief Destructor.
-       *
-       * Closes the stream and waits for the child to exit.
-       */
-      ~basic_ipstream()
-      { }
-
-      /**
-       * @brief Start a process.
-       *
-       * Calls do_open( @a %command , @a mode|pstdout ).
-       *
-       * @param command  a string containing a shell command.
-       * @param mode     the I/O mode to use when opening the pipe.
-       * @see   do_open(const std::string&, pmode)
-       */
-      void
-      open(const std::string& command, pmode mode = pstdout)
-      {
-        this->do_open(command, readable(mode));
-      }
-
-      /**
-       * @brief Start a process.
-       *
-       * Calls do_open( @a file , @a argv , @a mode|pstdout ).
-       *
-       * @param file  a string containing the pathname of a program to execute.
-       * @param argv  a vector of argument strings passed to the new program.
-       * @param mode  the I/O mode to use when opening the pipe.
-       * @see   do_open(const std::string&, const argv_type&, pmode)
-       */
-      void
-      open( const std::string& file,
-            const argv_type& argv,
-            pmode mode = pstdout )
-      {
-        this->do_open(file, argv, readable(mode));
-      }
-
-      /**
-       * @brief Set streambuf to read from process' @c stdout.
-       * @return  @c *this
-       */
-      basic_ipstream&
-      out()
-      {
-        this->buf_.read_err(false);
-        return *this;
-      }
-
-      /**
-       * @brief Set streambuf to read from process' @c stderr.
-       * @return  @c *this
-       */
-      basic_ipstream&
-      err()
-      {
-        this->buf_.read_err(true);
-        return *this;
-      }
-    };
-
-
-  /**
-   * @class basic_opstream
-   * @brief Class template for Output PStreams.
-   *
-   * Writing to an open opstream writes to the standard input of the command;
-   * the command's standard output is the same as that of the process that
-   * created the pstream object, unless altered by the command itself.
-   */
-
-  template <typename CharT, typename Traits = std::char_traits<CharT> >
-    class basic_opstream
-    : public std::basic_ostream<CharT, Traits>
-    , public pstream_common<CharT, Traits>
-    , virtual public pstreams
-    {
-      typedef std::basic_ostream<CharT, Traits>     ostream_type;
-      typedef pstream_common<CharT, Traits>         pbase_type;
-
-      using pbase_type::buf_;  // declare name in this scope
-
-    public:
-      /// Type used to specify how to connect to the process.
-      typedef typename pbase_type::pmode            pmode;
-
-      /// Type used to hold the arguments for a command.
-      typedef typename pbase_type::argv_type        argv_type;
-
-      /// Default constructor, creates an uninitialised stream.
-      basic_opstream()
-      : ostream_type(NULL), pbase_type()
-      { }
-
-      /**
-       * @brief Constructor that initialises the stream by starting a process.
-       *
-       * Initialises the stream buffer by calling do_open() with the supplied
-       * arguments.
-       *
-       * @param command  a string containing a shell command.
-       * @param mode     the I/O mode to use when opening the pipe.
-       * @see   do_open(const std::string&, pmode)
-       */
-      basic_opstream(const std::string& command, pmode mode = pstdin)
-      : ostream_type(NULL), pbase_type(command, mode|pstdin)
-      { }
-
-      /**
-       * @brief Constructor that initialises the stream by starting a process.
-       *
-       * Initialises the stream buffer by calling do_open() with the supplied
-       * arguments.
-       *
-       * @param file  a string containing the pathname of a program to execute.
-       * @param argv  a vector of argument strings passed to the new program.
-       * @param mode  the I/O mode to use when opening the pipe.
-       * @see   do_open(const std::string&, const argv_type&, pmode)
-       */
-      basic_opstream( const std::string& file,
-                      const argv_type& argv,
-                      pmode mode = pstdin )
-      : ostream_type(NULL), pbase_type(file, argv, mode|pstdin)
-      { }
-
-      /**
-       * @brief Destructor
-       *
-       * Closes the stream and waits for the child to exit.
-       */
-      ~basic_opstream() { }
-
-      /**
-       * @brief Start a process.
-       *
-       * Calls do_open( @a %command , @a mode|pstdin ).
-       *
-       * @param command  a string containing a shell command.
-       * @param mode     the I/O mode to use when opening the pipe.
-       * @see   do_open(const std::string&, pmode)
-       */
-      void
-      open(const std::string& command, pmode mode = pstdin)
-      {
-        this->do_open(command, mode|pstdin);
-      }
-
-      /**
-       * @brief Start a process.
-       *
-       * Calls do_open( @a file , @a argv , @a mode|pstdin ).
-       *
-       * @param file  a string containing the pathname of a program to execute.
-       * @param argv  a vector of argument strings passed to the new program.
-       * @param mode  the I/O mode to use when opening the pipe.
-       * @see   do_open(const std::string&, const argv_type&, pmode)
-       */
-      void
-      open( const std::string& file,
-            const argv_type& argv,
-            pmode mode = pstdin)
-      {
-        this->do_open(file, argv, mode|pstdin);
-      }
-    };
-
-
-  /**
-   * @class basic_pstream
-   * @brief Class template for Bidirectional PStreams.
-   *
-   * Writing to a pstream opened with @c pmode @c pstdin writes to the
-   * standard input of the command.
-   * Reading from a pstream opened with @c pmode @c pstdout and/or @c pstderr
-   * reads the command's standard output and/or standard error.
-   * Any of the process' @c stdin, @c stdout or @c stderr that is not
-   * connected to the pstream (as specified by the @c pmode)
-   * will be the same as the process that created the pstream object,
-   * unless altered by the command itself.
-   */
-  template <typename CharT, typename Traits = std::char_traits<CharT> >
-    class basic_pstream
-    : public std::basic_iostream<CharT, Traits>
-    , public pstream_common<CharT, Traits>
-    , virtual public pstreams
-    {
-      typedef std::basic_iostream<CharT, Traits>    iostream_type;
-      typedef pstream_common<CharT, Traits>         pbase_type;
-
-      using pbase_type::buf_;  // declare name in this scope
-
-    public:
-      /// Type used to specify how to connect to the process.
-      typedef typename pbase_type::pmode            pmode;
-
-      /// Type used to hold the arguments for a command.
-      typedef typename pbase_type::argv_type        argv_type;
-
-      /// Default constructor, creates an uninitialised stream.
-      basic_pstream()
-      : iostream_type(NULL), pbase_type()
-      { }
-
-      /**
-       * @brief Constructor that initialises the stream by starting a process.
-       *
-       * Initialises the stream buffer by calling do_open() with the supplied
-       * arguments.
-       *
-       * @param command  a string containing a shell command.
-       * @param mode     the I/O mode to use when opening the pipe.
-       * @see   do_open(const std::string&, pmode)
-       */
-      basic_pstream(const std::string& command, pmode mode = pstdout|pstdin)
-      : iostream_type(NULL), pbase_type(command, mode)
-      { }
-
-      /**
-       * @brief Constructor that initialises the stream by starting a process.
-       *
-       * Initialises the stream buffer by calling do_open() with the supplied
-       * arguments.
-       *
-       * @param file  a string containing the pathname of a program to execute.
-       * @param argv  a vector of argument strings passed to the new program.
-       * @param mode  the I/O mode to use when opening the pipe.
-       * @see   do_open(const std::string&, const argv_type&, pmode)
-       */
-      basic_pstream( const std::string& file,
-                     const argv_type& argv,
-                     pmode mode = pstdout|pstdin )
-      : iostream_type(NULL), pbase_type(file, argv, mode)
-      { }
-
-      /**
-       * @brief Destructor
-       *
-       * Closes the stream and waits for the child to exit.
-       */
-      ~basic_pstream() { }
-
-      /**
-       * @brief Start a process.
-       *
-       * Calls do_open( @a %command , @a mode ).
-       *
-       * @param command  a string containing a shell command.
-       * @param mode     the I/O mode to use when opening the pipe.
-       * @see   do_open(const std::string&, pmode)
-       */
-      void
-      open(const std::string& command, pmode mode = pstdout|pstdin)
-      {
-        this->do_open(command, mode);
-      }
-
-      /**
-       * @brief Start a process.
-       *
-       * Calls do_open( @a file , @a argv , @a mode ).
-       *
-       * @param file  a string containing the pathname of a program to execute.
-       * @param argv  a vector of argument strings passed to the new program.
-       * @param mode  the I/O mode to use when opening the pipe.
-       * @see   do_open(const std::string&, const argv_type&, pmode)
-       */
-      void
-      open( const std::string& file,
-            const argv_type& argv,
-            pmode mode = pstdout|pstdin )
-      {
-        this->do_open(file, argv, mode);
-      }
-
-      /**
-       * @brief Set streambuf to read from process' @c stdout.
-       * @return  @c *this
-       */
-      basic_pstream&
-      out()
-      {
-        this->buf_.read_err(false);
-        return *this;
-      }
-
-      /**
-       * @brief Set streambuf to read from process' @c stderr.
-       * @return  @c *this
-       */
-      basic_pstream&
-      err()
-      {
-        this->buf_.read_err(true);
-        return *this;
-      }
-    };
-
-
-  /**
-   * @class basic_rpstream
-   * @brief template for Restricted PStreams.
-   *
-   * Writing to an rpstream opened with @c pmode @c pstdin writes to the
-   * standard input of the command.
-   * It is not possible to read directly from an rpstream object, to use
-   * an rpstream as in istream you must call either basic_rpstream::out()
-   * or basic_rpstream::err(). This is to prevent accidental reads from
-   * the wrong input source. If the rpstream was not opened with @c pmode
-   * @c pstderr then the class cannot read the process' @c stderr, and
-   * basic_rpstream::err() will return an istream that reads from the
-   * process' @c stdout, and vice versa.
-   * Reading from an rpstream opened with @c pmode @c pstdout and/or
-   * @c pstderr reads the command's standard output and/or standard error.
-   * Any of the process' @c stdin, @c stdout or @c stderr that is not
-   * connected to the pstream (as specified by the @c pmode)
-   * will be the same as the process that created the pstream object,
-   * unless altered by the command itself.
-   */
-
-  template <typename CharT, typename Traits = std::char_traits<CharT> >
-    class basic_rpstream
-    : public std::basic_ostream<CharT, Traits>
-    , private std::basic_istream<CharT, Traits>
-    , private pstream_common<CharT, Traits>
-    , virtual public pstreams
-    {
-      typedef std::basic_ostream<CharT, Traits>     ostream_type;
-      typedef std::basic_istream<CharT, Traits>     istream_type;
-      typedef pstream_common<CharT, Traits>         pbase_type;
-
-      using pbase_type::buf_;  // declare name in this scope
-
-    public:
-      /// Type used to specify how to connect to the process.
-      typedef typename pbase_type::pmode            pmode;
-
-      /// Type used to hold the arguments for a command.
-      typedef typename pbase_type::argv_type        argv_type;
-
-      /// Default constructor, creates an uninitialised stream.
-      basic_rpstream()
-      : ostream_type(NULL), istream_type(NULL), pbase_type()
-      { }
-
-      /**
-       * @brief  Constructor that initialises the stream by starting a process.
-       *
-       * Initialises the stream buffer by calling do_open() with the supplied
-       * arguments.
-       *
-       * @param command a string containing a shell command.
-       * @param mode the I/O mode to use when opening the pipe.
-       * @see   do_open(const std::string&, pmode)
-       */
-      basic_rpstream(const std::string& command, pmode mode = pstdout|pstdin)
-      : ostream_type(NULL) , istream_type(NULL) , pbase_type(command, mode)
-      { }
-
-      /**
-       * @brief  Constructor that initialises the stream by starting a process.
-       *
-       * Initialises the stream buffer by calling do_open() with the supplied
-       * arguments.
-       *
-       * @param file a string containing the pathname of a program to execute.
-       * @param argv a vector of argument strings passed to the new program.
-       * @param mode the I/O mode to use when opening the pipe.
-       * @see   do_open(const std::string&, const argv_type&, pmode)
-       */
-      basic_rpstream( const std::string& file,
-                      const argv_type& argv,
-                      pmode mode = pstdout|pstdin )
-      : ostream_type(NULL), istream_type(NULL), pbase_type(file, argv, mode)
-      { }
-
-      /// Destructor
-      ~basic_rpstream() { }
-
-      /**
-       * @brief  Start a process.
-       *
-       * Calls do_open( @a %command , @a mode ).
-       *
-       * @param command a string containing a shell command.
-       * @param mode the I/O mode to use when opening the pipe.
-       * @see   do_open(const std::string&, pmode)
-       */
-      void
-      open(const std::string& command, pmode mode = pstdout|pstdin)
-      {
-        this->do_open(command, mode);
-      }
-
-      /**
-       * @brief  Start a process.
-       *
-       * Calls do_open( @a file , @a argv , @a mode ).
-       *
-       * @param file a string containing the pathname of a program to execute.
-       * @param argv a vector of argument strings passed to the new program.
-       * @param mode the I/O mode to use when opening the pipe.
-       * @see   do_open(const std::string&, const argv_type&, pmode)
-       */
-      void
-      open( const std::string& file,
-            const argv_type& argv,
-            pmode mode = pstdout|pstdin )
-      {
-        this->do_open(file, argv, mode);
-      }
-
-      /**
-       * @brief  Obtain a reference to the istream that reads
-       *         the process' @c stdout.
-       * @return @c *this
-       */
-      istream_type&
-      out()
-      {
-        this->buf_.read_err(false);
-        return *this;
-      }
-
-      /**
-       * @brief  Obtain a reference to the istream that reads
-       *         the process' @c stderr.
-       * @return @c *this
-       */
-      istream_type&
-      err()
-      {
-        this->buf_.read_err(true);
-        return *this;
-      }
-    };
-
-
-  /// Type definition for common template specialisation.
-  typedef basic_pstreambuf<char> pstreambuf;
-  /// Type definition for common template specialisation.
-  typedef basic_ipstream<char> ipstream;
-  /// Type definition for common template specialisation.
-  typedef basic_opstream<char> opstream;
-  /// Type definition for common template specialisation.
-  typedef basic_pstream<char> pstream;
-  /// Type definition for common template specialisation.
-  typedef basic_rpstream<char> rpstream;
-
-
-  /**
-   * When inserted into an output pstream the manipulator calls
-   * basic_pstreambuf<C,T>::peof() to close the output pipe,
-   * causing the child process to receive the end-of-file indicator
-   * on subsequent reads from its @c stdin stream.
-   *
-   * @brief   Manipulator to close the pipe connected to the process' stdin.
-   * @param   s  An output PStream class.
-   * @return  The stream object the manipulator was invoked on.
-   * @see     basic_pstreambuf<C,T>::peof()
-   * @relates basic_opstream basic_pstream basic_rpstream
-   */
-  template <typename C, typename T>
-    inline std::basic_ostream<C,T>&
-    peof(std::basic_ostream<C,T>& s)
-    {
-      typedef basic_pstreambuf<C,T> pstreambuf;
-      if (pstreambuf* p = dynamic_cast<pstreambuf*>(s.rdbuf()))
-        p->peof();
-      return s;
-    }
-
-
-  /*
-   * member definitions for pstreambuf
-   */
-
-
-  /**
-   * @class basic_pstreambuf
-   * Provides underlying streambuf functionality for the PStreams classes.
-   */
-
-  /** Creates an uninitialised stream buffer. */
-  template <typename C, typename T>
-    inline
-    basic_pstreambuf<C,T>::basic_pstreambuf()
-    : ppid_(-1)   // initialise to -1 to indicate no process run yet.
-    , wpipe_(-1)
-    , wbuffer_(NULL)
-    , rsrc_(rsrc_out)
-    , status_(-1)
-    , error_(0)
-    {
-      init_rbuffers();
-    }
-
-  /**
-   * Initialises the stream buffer by calling open() with the supplied
-   * arguments.
-   *
-   * @param command a string containing a shell command.
-   * @param mode    the I/O mode to use when opening the pipe.
-   * @see   open()
-   */
-  template <typename C, typename T>
-    inline
-    basic_pstreambuf<C,T>::basic_pstreambuf(const std::string& command, pmode mode)
-    : ppid_(-1)   // initialise to -1 to indicate no process run yet.
-    , wpipe_(-1)
-    , wbuffer_(NULL)
-    , rsrc_(rsrc_out)
-    , status_(-1)
-    , error_(0)
-    {
-      init_rbuffers();
-      open(command, mode);
-    }
-
-  /**
-   * Initialises the stream buffer by calling open() with the supplied
-   * arguments.
-   *
-   * @param file  a string containing the name of a program to execute.
-   * @param argv  a vector of argument strings passsed to the new program.
-   * @param mode  the I/O mode to use when opening the pipe.
-   * @see   open()
-   */
-  template <typename C, typename T>
-    inline
-    basic_pstreambuf<C,T>::basic_pstreambuf( const std::string& file,
-                                             const argv_type& argv,
-                                             pmode mode )
-    : ppid_(-1)   // initialise to -1 to indicate no process run yet.
-    , wpipe_(-1)
-    , wbuffer_(NULL)
-    , rsrc_(rsrc_out)
-    , status_(-1)
-    , error_(0)
-    {
-      init_rbuffers();
-      open(file, argv, mode);
-    }
-
-  /**
-   * Closes the stream by calling close().
-   * @see close()
-   */
-  template <typename C, typename T>
-    inline
-    basic_pstreambuf<C,T>::~basic_pstreambuf()
-    {
-      close();
-    }
-
-  /**
-   * Starts a new process by passing @a command to the shell (/bin/sh)
-   * and opens pipes to the process with the specified @a mode.
-   *
-   * If @a mode contains @c pstdout the initial read source will be
-   * the child process' stdout, otherwise if @a mode  contains @c 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 @a 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.
-   *
-   * @param   command  a string containing a shell command.
-   * @param   mode     a bitwise OR of one or more of @c out, @c in, @c err.
-   * @return  NULL if the shell could not be started or the
-   *          pipes could not be opened, @c this otherwise.
-   * @see     <b>execl</b>(3)
-   */
-  template <typename C, typename T>
-    basic_pstreambuf<C,T>*
-    basic_pstreambuf<C,T>::open(const std::string& command, pmode mode)
-    {
-      const char * shell_path = "/bin/sh";
-#if 0
-      const std::string argv[] = { "sh", "-c", command };
-      return this->open(shell_path, argv_type(argv, argv+3), mode);
-#else
-      basic_pstreambuf<C,T>* ret = NULL;
-
-      if (!is_open())
-      {
-        switch(fork(mode))
-        {
-        case 0 :
-          // this is the new process, exec command
-          ::execl(shell_path, "sh", "-c", command.c_str(), (char*)NULL);
-
-          // can only reach this point if exec() failed
-
-          // parent can get exit code from waitpid()
-          ::_exit(errno);
-          // using std::exit() would make static dtors run twice
-
-        case -1 :
-          // couldn't fork, error already handled in pstreambuf::fork()
-          break;
-
-        default :
-          // this is the parent process
-          // activate buffers
-          create_buffers(mode);
-          ret = this;
-        }
-      }
-      return ret;
-#endif
-    }
-
-  /**
-   * @brief  Helper function to close a file descriptor.
-   *
-   * Inspects @a fd and calls <b>close</b>(3) if it has a non-negative value.
-   *
-   * @param   fd  a file descriptor.
-   * @relates basic_pstreambuf
-   */
-  inline void
-  close_fd(pstreams::fd_type& fd)
-  {
-    if (fd >= 0 && ::close(fd) == 0)
-      fd = -1;
-  }
-
-  /**
-   * @brief  Helper function to close an array of file descriptors.
-   *
-   * Calls @c close_fd() on each member of the array.
-   * The length of the array is determined automatically by
-   * template argument deduction to avoid errors.
-   *
-   * @param   fds  an array of file descriptors.
-   * @relates basic_pstreambuf
-   */
-  template <int N>
-    inline void
-    close_fd_array(pstreams::fd_type (&fds)[N])
-    {
-      for (std::size_t i = 0; i < N; ++i)
-        close_fd(fds[i]);
-    }
-
-  /**
-   * Starts a new process by executing @a file with the arguments in
-   * @a argv and opens pipes to the process with the specified @a mode.
-   *
-   * By convention @c argv[0] should be the file name of the file being
-   * executed.
-   *
-   * If @a mode contains @c pstdout the initial read source will be
-   * the child process' stdout, otherwise if @a mode  contains @c 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 @a file is successfully executed then is_open() will return true.
-   * Otherwise, pstreambuf::error() can be used to obtain the value of
-   * @c errno that was set by <b>execvp</b>(3) in the child process.
-   *
-   * The exit status of the new process will be returned by
-   * pstreambuf::status() after pstreambuf::exited() returns true.
-   *
-   * @param   file  a string containing the pathname of a program to execute.
-   * @param   argv  a vector of argument strings passed to the new program.
-   * @param   mode  a bitwise OR of one or more of @c out, @c in and @c err.
-   * @return  NULL if a pipe could not be opened or if the program could
-   *          not be executed, @c this otherwise.
-   * @see     <b>execvp</b>(3)
-   */
-  template <typename C, typename T>
-    basic_pstreambuf<C,T>*
-    basic_pstreambuf<C,T>::open( const std::string& file,
-                                 const argv_type& argv,
-                                 pmode mode )
-    {
-      basic_pstreambuf<C,T>* ret = NULL;
-
-      if (!is_open())
-      {
-        // constants for read/write ends of pipe
-        enum { RD, WR };
-
-        // open another pipe and set close-on-exec
-        fd_type ck_exec[] = { -1, -1 };
-        if (-1 == ::pipe(ck_exec)
-            || -1 == ::fcntl(ck_exec[RD], F_SETFD, FD_CLOEXEC)
-            || -1 == ::fcntl(ck_exec[WR], F_SETFD, FD_CLOEXEC))
-        {
-          error_ = errno;
-          close_fd_array(ck_exec);
-        }
-        else
-        {
-          switch(fork(mode))
-          {
-          case 0 :
-            // this is the new process, exec command
-            {
-              char** arg_v = new char*[argv.size()+1];
-              for (std::size_t i = 0; i < argv.size(); ++i)
-              {
-                const std::string& src = argv[i];
-                char*& dest = arg_v[i];
-                dest = new char[src.size()+1];
-                dest[ src.copy(dest, src.size()) ] = '\0';
-              }
-              arg_v[argv.size()] = NULL;
-
-              ::execvp(file.c_str(), arg_v);
-
-              // can only reach this point if exec() failed
-
-              // parent can get error code from ck_exec pipe
-              error_ = errno;
-
-              ::write(ck_exec[WR], &error_, sizeof(error_));
-              ::close(ck_exec[WR]);
-              ::close(ck_exec[RD]);
-
-              ::_exit(error_);
-              // using std::exit() would make static dtors run twice
-            }
-
-          case -1 :
-            // couldn't fork, error already handled in pstreambuf::fork()
-            close_fd_array(ck_exec);
-            break;
-
-          default :
-            // this is the parent process
-
-            // check child called exec() successfully
-            ::close(ck_exec[WR]);
-            switch (::read(ck_exec[RD], &error_, sizeof(error_)))
-            {
-            case 0:
-              // activate buffers
-              create_buffers(mode);
-              ret = this;
-              break;
-            case -1:
-              error_ = errno;
-              break;
-            default:
-              // error_ contains error code from child
-              // call wait() to clean up and set ppid_ to 0
-              this->wait();
-              break;
-            }
-            ::close(ck_exec[RD]);
-          }
-        }
-      }
-      return ret;
-    }
-
-  /**
-   * Creates pipes as specified by @a mode and calls @c 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 @c pipe() or @c fork().
-   * See your system's documentation for these error codes.
-   *
-   * @param   mode  an OR of pmodes specifying which of the child's
-   *                standard streams to connect to.
-   * @return  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>
-    pid_t
-    basic_pstreambuf<C,T>::fork(pmode mode)
-    {
-      pid_t pid = -1;
-
-      // Three pairs of file descriptors, for pipes connected to the
-      // process' stdin, stdout and stderr
-      // (stored in a single array so close_fd_array() can close all at once)
-      fd_type fd[] = { -1, -1, -1, -1, -1, -1 };
-      fd_type* const pin = fd;
-      fd_type* const pout = fd+2;
-      fd_type* const perr = fd+4;
-
-      // constants for read/write ends of pipe
-      enum { RD, WR };
-
-      // N.B.
-      // For the pstreambuf pin is an output stream and
-      // pout and perr are input streams.
-
-      if (!error_ && mode&pstdin && ::pipe(pin))
-        error_ = errno;
-
-      if (!error_ && mode&pstdout && ::pipe(pout))
-        error_ = errno;
-
-      if (!error_ && mode&pstderr && ::pipe(perr))
-        error_ = errno;
-
-      if (!error_)
-      {
-        pid = ::fork();
-        switch (pid)
-        {
-          case 0 :
-          {
-            // this is the new process
-
-            // for each open pipe close one end and redirect the
-            // respective standard stream to the other end
-
-            if (*pin >= 0)
-            {
-              ::close(pin[WR]);
-              ::dup2(pin[RD], STDIN_FILENO);
-              ::close(pin[RD]);
-            }
-            if (*pout >= 0)
-            {
-              ::close(pout[RD]);
-              ::dup2(pout[WR], STDOUT_FILENO);
-              ::close(pout[WR]);
-            }
-            if (*perr >= 0)
-            {
-              ::close(perr[RD]);
-              ::dup2(perr[WR], STDERR_FILENO);
-              ::close(perr[WR]);
-            }
-            break;
-          }
-          case -1 :
-          {
-            // couldn't fork for some reason
-            error_ = errno;
-            // close any open pipes
-            close_fd_array(fd);
-            break;
-          }
-          default :
-          {
-            // this is the parent process, store process' pid
-            ppid_ = pid;
-
-            // store one end of open pipes and close other end
-            if (*pin >= 0)
-            {
-              wpipe_ = pin[WR];
-              ::close(pin[RD]);
-            }
-            if (*pout >= 0)
-            {
-              rpipe_[rsrc_out] = pout[RD];
-              ::close(pout[WR]);
-            }
-            if (*perr >= 0)
-            {
-              rpipe_[rsrc_err] = perr[RD];
-              ::close(perr[WR]);
-            }
-          }
-        }
-      }
-      else
-      {
-        // close any pipes we opened before failure
-        close_fd_array(fd);
-      }
-      return pid;
-    }
-
-  /**
-   * 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 @c waitpid().
-   * See your system's documentation for these errors.
-   *
-   * @return  @c this on successful close or @c NULL if there is no
-   *          process to close or if an error occurs.
-   */
-  template <typename C, typename T>
-    basic_pstreambuf<C,T>*
-    basic_pstreambuf<C,T>::close()
-    {
-      const bool running = is_open();
-
-      sync(); // this might call wait() and reap the child process
-
-      // rather than trying to work out whether or not we need to clean up
-      // just do it anyway, all cleanup functions are safe to call twice.
-
-      destroy_buffers(pstdin|pstdout|pstderr);
-
-      // close pipes before wait() so child gets EOF/SIGPIPE
-      close_fd(wpipe_);
-      close_fd_array(rpipe_);
-
-      do
-      {
-        error_ = 0;
-      } while (wait() == -1 && error() == EINTR);
-
-      return running ? this : NULL;
-    }
-
-  /**
-   *  Called on construction to initialise the arrays used for reading.
-   */
-  template <typename C, typename T>
-    inline void
-    basic_pstreambuf<C,T>::init_rbuffers()
-    {
-      rpipe_[rsrc_out] = rpipe_[rsrc_err] = -1;
-      rbuffer_[rsrc_out] = rbuffer_[rsrc_err] = NULL;
-      rbufstate_[0] = rbufstate_[1] = rbufstate_[2] = NULL;
-    }
-
-  template <typename C, typename T>
-    void
-    basic_pstreambuf<C,T>::create_buffers(pmode mode)
-    {
-      if (mode & pstdin)
-      {
-        delete[] wbuffer_;
-        wbuffer_ = new char_type[bufsz];
-        this->setp(wbuffer_, wbuffer_ + bufsz);
-      }
-      if (mode & pstdout)
-      {
-        delete[] rbuffer_[rsrc_out];
-        rbuffer_[rsrc_out] = new char_type[bufsz];
-        rsrc_ = rsrc_out;
-        this->setg(rbuffer_[rsrc_out] + pbsz, rbuffer_[rsrc_out] + pbsz,
-            rbuffer_[rsrc_out] + pbsz);
-      }
-      if (mode & pstderr)
-      {
-        delete[] rbuffer_[rsrc_err];
-        rbuffer_[rsrc_err] = new char_type[bufsz];
-        if (!(mode & pstdout))
-        {
-          rsrc_ = rsrc_err;
-          this->setg(rbuffer_[rsrc_err] + pbsz, rbuffer_[rsrc_err] + pbsz,
-              rbuffer_[rsrc_err] + pbsz);
-        }
-      }
-    }
-
-  template <typename C, typename T>
-    void
-    basic_pstreambuf<C,T>::destroy_buffers(pmode mode)
-    {
-      if (mode & pstdin)
-      {
-        this->setp(NULL, NULL);
-        delete[] wbuffer_;
-        wbuffer_ = NULL;
-      }
-      if (mode & pstdout)
-      {
-        if (rsrc_ == rsrc_out)
-          this->setg(NULL, NULL, NULL);
-        delete[] rbuffer_[rsrc_out];
-        rbuffer_[rsrc_out] = NULL;
-      }
-      if (mode & pstderr)
-      {
-        if (rsrc_ == rsrc_err)
-          this->setg(NULL, NULL, NULL);
-        delete[] rbuffer_[rsrc_err];
-        rbuffer_[rsrc_err] = NULL;
-      }
-    }
-
-  template <typename C, typename T>
-    typename basic_pstreambuf<C,T>::buf_read_src
-    basic_pstreambuf<C,T>::switch_read_buffer(buf_read_src src)
-    {
-      if (rsrc_ != src)
-      {
-        char_type* tmpbufstate[] = {this->eback(), this->gptr(), this->egptr()};
-        this->setg(rbufstate_[0], rbufstate_[1], rbufstate_[2]);
-        for (std::size_t i = 0; i < 3; ++i)
-          rbufstate_[i] = tmpbufstate[i];
-        rsrc_ = src;
-      }
-      return rsrc_;
-    }
-
-  /**
-   * 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.
-   *
-   * @param   nohang  true to return immediately if the process has not exited.
-   * @return  1 if the process has exited and wait() has not yet been called.
-   *          0 if @a 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>
-    int
-    basic_pstreambuf<C,T>::wait(bool nohang)
-    {
-      int exited = -1;
-      if (is_open())
-      {
-        int status;
-        switch(::waitpid(ppid_, &status, nohang ? WNOHANG : 0))
-        {
-          case 0 :
-            // nohang was true and process has not exited
-            exited = 0;
-            break;
-          case -1 :
-            error_ = errno;
-            break;
-          default :
-            // process has exited
-            ppid_ = 0;
-            status_ = status;
-            exited = 1;
-            // Close wpipe, would get SIGPIPE if we used it.
-            destroy_buffers(pstdin);
-            close_fd(wpipe_);
-            // Must free read buffers and pipes on destruction
-            // or next call to open()/close()
-            break;
-        }
-      }
-      return exited;
-    }
-
-  /**
-   * 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 @c kill().  See your system's documentation for these errors.
-   *
-   * @param   signal  A signal to send to the child process.
-   * @return  @c this or @c NULL if @c kill() fails.
-   */
-  template <typename C, typename T>
-    inline basic_pstreambuf<C,T>*
-    basic_pstreambuf<C,T>::kill(int signal)
-    {
-      basic_pstreambuf<C,T>* ret = NULL;
-      if (is_open())
-      {
-        if (::kill(ppid_, signal))
-          error_ = errno;
-        else
-        {
-#if 0
-          // TODO call exited() to check for exit and clean up? leave to user?
-          if (signal==SIGTERM || signal==SIGKILL)
-            this->exited();
-#endif
-          ret = this;
-        }
-      }
-      return ret;
-    }
-
-  /**
-   *  This function can call pstreambuf::wait() and so may change the
-   *  object's state if the child process has already exited.
-   *
-   *  @return  True if the associated process has exited, false otherwise.
-   *  @see     basic_pstreambuf<C,T>::wait()
-   */
-  template <typename C, typename T>
-    inline bool
-    basic_pstreambuf<C,T>::exited()
-    {
-      return ppid_ == 0 || wait(true)==1;
-    }
-
-
-  /**
-   *  @return  The exit status of the child process, or -1 if wait()
-   *           has not yet been called to wait for the child to exit.
-   *  @see     basic_pstreambuf<C,T>::wait()
-   */
-  template <typename C, typename T>
-    inline int
-    basic_pstreambuf<C,T>::status() const
-    {
-      return status_;
-    }
-
-  /**
-   *  @return  The error code of the most recently failed operation, or zero.
-   */
-  template <typename C, typename T>
-    inline int
-    basic_pstreambuf<C,T>::error() const
-    {
-      return error_;
-    }
-
-  /**
-   *  Closes the output pipe, causing the child process to receive the
-   *  end-of-file indicator on subsequent reads from its @c stdin stream.
-   */
-  template <typename C, typename T>
-    inline void
-    basic_pstreambuf<C,T>::peof()
-    {
-      sync();
-      destroy_buffers(pstdin);
-      close_fd(wpipe_);
-    }
-
-  /**
-   * 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.)
-   *
-   * @return  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>
-    inline bool
-    basic_pstreambuf<C,T>::is_open() const
-    {
-      return ppid_ > 0;
-    }
-
-  /**
-   * Toggle the stream used for reading. If @a readerr is @c true then the
-   * process' @c stderr output will be used for subsequent extractions, if
-   * @a readerr is false the the process' stdout will be used.
-   * @param   readerr  @c true to read @c stderr, @c false to read @c stdout.
-   * @return  @c true if the requested stream is open and will be used for
-   *          subsequent extractions, @c false otherwise.
-   */
-  template <typename C, typename T>
-    inline bool
-    basic_pstreambuf<C,T>::read_err(bool readerr)
-    {
-      buf_read_src src = readerr ? rsrc_err : rsrc_out;
-      if (rpipe_[src]>=0)
-      {
-        switch_read_buffer(src);
-        return true;
-      }
-      return false;
-    }
-
-  /**
-   * Called when the internal character buffer is not present or is full,
-   * to transfer the buffer contents to the pipe.
-   *
-   * @param   c  a character to be written to the pipe.
-   * @return  @c traits_type::eof() if an error occurs, otherwise if @a c
-   *          is not equal to @c traits_type::eof() it will be buffered and
-   *          a value other than @c traits_type::eof() returned to indicate
-   *          success.
-   */
-  template <typename C, typename T>
-    typename basic_pstreambuf<C,T>::int_type
-    basic_pstreambuf<C,T>::overflow(int_type c)
-    {
-      if (!empty_buffer())
-        return traits_type::eof();
-      else if (!traits_type::eq_int_type(c, traits_type::eof()))
-        return this->sputc(c);
-      else
-        return traits_type::not_eof(c);
-    }
-
-
-  template <typename C, typename T>
-    int
-    basic_pstreambuf<C,T>::sync()
-    {
-      return !exited() && empty_buffer() ? 0 : -1;
-    }
-
-  /**
-   * @param   s  character buffer.
-   * @param   n  buffer length.
-   * @return  the number of characters written.
-   */
-  template <typename C, typename T>
-    std::streamsize
-    basic_pstreambuf<C,T>::xsputn(const char_type* s, std::streamsize n)
-    {
-      if (n < this->epptr() - this->pptr())
-      {
-        traits_type::copy(this->pptr(), s, n);
-        this->pbump(n);
-        return n;
-      }
-      else
-      {
-        for (std::streamsize i = 0; i < n; ++i)
-        {
-          if (traits_type::eq_int_type(this->sputc(s[i]), traits_type::eof()))
-            return i;
-        }
-        return n;
-      }
-    }
-
-  /**
-   * @return  true if the buffer was emptied, false otherwise.
-   */
-  template <typename C, typename T>
-    bool
-    basic_pstreambuf<C,T>::empty_buffer()
-    {
-      const std::streamsize count = this->pptr() - this->pbase();
-      if (count > 0)
-      {
-        const std::streamsize written = this->write(this->wbuffer_, count);
-        if (written > 0)
-        {
-          if (const std::streamsize unwritten = count - written)
-            traits_type::move(this->pbase(), this->pbase()+written, unwritten);
-          this->pbump(-written);
-          return true;
-        }
-      }
-      return false;
-    }
-
-  /**
-   * Called when the internal character buffer is is empty, to re-fill it
-   * from the pipe.
-   *
-   * @return The first available character in the buffer,
-   * or @c traits_type::eof() in case of failure.
-   */
-  template <typename C, typename T>
-    typename basic_pstreambuf<C,T>::int_type
-    basic_pstreambuf<C,T>::underflow()
-    {
-      if (this->gptr() < this->egptr() || fill_buffer())
-        return traits_type::to_int_type(*this->gptr());
-      else
-        return traits_type::eof();
-    }
-
-  /**
-   * Attempts to make @a c available as the next character to be read by
-   * @c sgetc().
-   *
-   * @param   c   a character to make available for extraction.
-   * @return  @a c if the character can be made available,
-   *          @c traits_type::eof() otherwise.
-   */
-  template <typename C, typename T>
-    typename basic_pstreambuf<C,T>::int_type
-    basic_pstreambuf<C,T>::pbackfail(int_type c)
-    {
-      if (this->gptr() != this->eback())
-      {
-        this->gbump(-1);
-        if (!traits_type::eq_int_type(c, traits_type::eof()))
-          *this->gptr() = traits_type::to_char_type(c);
-        return traits_type::not_eof(c);
-      }
-      else
-         return traits_type::eof();
-    }
-
-  template <typename C, typename T>
-    std::streamsize
-    basic_pstreambuf<C,T>::showmanyc()
-    {
-      int avail = 0;
-      if (sizeof(char_type) == 1)
-        avail = fill_buffer(true) ? this->egptr() - this->gptr() : -1;
-#ifdef FIONREAD
-      else
-      {
-        if (::ioctl(rpipe(), FIONREAD, &avail) == -1)
-          avail = -1;
-        else if (avail)
-          avail /= sizeof(char_type);
-      }
-#endif
-      return std::streamsize(avail);
-    }
-
-  /**
-   * @return  true if the buffer was filled, false otherwise.
-   */
-  template <typename C, typename T>
-    bool
-    basic_pstreambuf<C,T>::fill_buffer(bool non_blocking)
-    {
-      const std::streamsize pb1 = this->gptr() - this->eback();
-      const std::streamsize pb2 = pbsz;
-      const std::streamsize npb = std::min(pb1, pb2);
-
-      char_type* const rbuf = rbuffer();
-
-      traits_type::move(rbuf + pbsz - npb, this->gptr() - npb, npb);
-
-      std::streamsize rc = -1;
-
-      if (non_blocking)
-      {
-        const int flags = ::fcntl(rpipe(), F_GETFL);
-        if (flags != -1)
-        {
-          const bool blocking = !(flags & O_NONBLOCK);
-          if (blocking)
-            ::fcntl(rpipe(), F_SETFL, flags | O_NONBLOCK);  // set non-blocking
-
-          error_ = 0;
-          rc = read(rbuf + pbsz, bufsz - pbsz);
-
-          if (rc == -1 && error_ == EAGAIN)  // nothing available
-            rc = 0;
-          else if (rc == 0)  // EOF
-            rc = -1;
-
-          if (blocking)
-            ::fcntl(rpipe(), F_SETFL, flags); // restore
-        }
-      }
-      else
-        rc = read(rbuf + pbsz, bufsz - pbsz);
-
-      if (rc > 0 || (rc == 0 && non_blocking))
-      {
-        this->setg( rbuf + pbsz - npb,
-                    rbuf + pbsz,
-                    rbuf + pbsz + rc );
-        return true;
-      }
-      else
-      {
-        this->setg(NULL, NULL, NULL);
-        return false;
-      }
-    }
-
-  /**
-   * Writes up to @a n characters to the pipe from the buffer @a s.
-   *
-   * @param   s  character buffer.
-   * @param   n  buffer length.
-   * @return  the number of characters written.
-   */
-  template <typename C, typename T>
-    inline std::streamsize
-    basic_pstreambuf<C,T>::write(const char_type* s, std::streamsize n)
-    {
-      std::streamsize nwritten = 0;
-      if (wpipe() >= 0)
-      {
-        nwritten = ::write(wpipe(), s, n * sizeof(char_type));
-        if (nwritten == -1)
-          error_ = errno;
-        else
-          nwritten /= sizeof(char_type);
-      }
-      return nwritten;
-    }
-
-  /**
-   * Reads up to @a n characters from the pipe to the buffer @a s.
-   *
-   * @param   s  character buffer.
-   * @param   n  buffer length.
-   * @return  the number of characters read.
-   */
-  template <typename C, typename T>
-    inline std::streamsize
-    basic_pstreambuf<C,T>::read(char_type* s, std::streamsize n)
-    {
-      std::streamsize nread = 0;
-      if (rpipe() >= 0)
-      {
-        nread = ::read(rpipe(), s, n * sizeof(char_type));
-        if (nread == -1)
-          error_ = errno;
-        else
-          nread /= sizeof(char_type);
-      }
-      return nread;
-    }
-
-  /** @return a reference to the output file descriptor */
-  template <typename C, typename T>
-    inline typename basic_pstreambuf<C,T>::fd_type&
-    basic_pstreambuf<C,T>::wpipe()
-    {
-      return wpipe_;
-    }
-
-  /** @return a reference to the active input file descriptor */
-  template <typename C, typename T>
-    inline typename basic_pstreambuf<C,T>::fd_type&
-    basic_pstreambuf<C,T>::rpipe()
-    {
-      return rpipe_[rsrc_];
-    }
-
-  /** @return a reference to the specified input file descriptor */
-  template <typename C, typename T>
-    inline typename basic_pstreambuf<C,T>::fd_type&
-    basic_pstreambuf<C,T>::rpipe(buf_read_src which)
-    {
-      return rpipe_[which];
-    }
-
-  /** @return a pointer to the start of the active input buffer area. */
-  template <typename C, typename T>
-    inline typename basic_pstreambuf<C,T>::char_type*
-    basic_pstreambuf<C,T>::rbuffer()
-    {
-      return rbuffer_[rsrc_];
-    }
-
-
-  /*
-   * member definitions for pstream_common
-   */
-
-  /**
-   * @class pstream_common
-   * Abstract Base Class providing common functionality for basic_ipstream,
-   * basic_opstream and basic_pstream.
-   * pstream_common manages the basic_pstreambuf stream buffer that is used
-   * by the derived classes to initialise an iostream class.
-   */
-
-  /** Creates an uninitialised stream. */
-  template <typename C, typename T>
-    inline
-    pstream_common<C,T>::pstream_common()
-    : std::basic_ios<C,T>(NULL)
-    , command_()
-    , buf_()
-    {
-      this->init(&buf_);
-    }
-
-  /**
-   * Initialises the stream buffer by calling
-   * do_open( @a command , @a mode )
-   *
-   * @param command a string containing a shell command.
-   * @param mode    the I/O mode to use when opening the pipe.
-   * @see   do_open(const std::string&, pmode)
-   */
-  template <typename C, typename T>
-    inline
-    pstream_common<C,T>::pstream_common(const std::string& command, pmode mode)
-    : std::basic_ios<C,T>(NULL)
-    , command_(command)
-    , buf_()
-    {
-      this->init(&buf_);
-      do_open(command, mode);
-    }
-
-  /**
-   * Initialises the stream buffer by calling
-   * do_open( @a file , @a argv , @a mode )
-   *
-   * @param file  a string containing the pathname of a program to execute.
-   * @param argv  a vector of argument strings passed to the new program.
-   * @param mode  the I/O mode to use when opening the pipe.
-   * @see do_open(const std::string&, const argv_type&, pmode)
-   */
-  template <typename C, typename T>
-    inline
-    pstream_common<C,T>::pstream_common( const std::string& file,
-                                         const argv_type& argv,
-                                         pmode mode )
-    : std::basic_ios<C,T>(NULL)
-    , command_(file)
-    , buf_()
-    {
-      this->init(&buf_);
-      do_open(file, argv, mode);
-    }
-
-  /**
-   * This is a pure virtual function to make @c pstream_common abstract.
-   * Because it is the destructor it will be called by derived classes
-   * and so must be defined.  It is also protected, to discourage use of
-   * the PStreams classes through pointers or references to the base class.
-   *
-   * @sa If defining a pure virtual seems odd you should read
-   * http://www.gotw.ca/gotw/031.htm (and the rest of the site as well!)
-   */
-  template <typename C, typename T>
-    inline
-    pstream_common<C,T>::~pstream_common()
-    {
-    }
-
-  /**
-   * Calls rdbuf()->open( @a command , @a mode )
-   * and sets @c failbit on error.
-   *
-   * @param command a string containing a shell command.
-   * @param mode    the I/O mode to use when opening the pipe.
-   * @see   basic_pstreambuf::open(const std::string&, pmode)
-   */
-  template <typename C, typename T>
-    inline void
-    pstream_common<C,T>::do_open(const std::string& command, pmode mode)
-    {
-      if (!buf_.open((command_=command), mode))
-        this->setstate(std::ios_base::failbit);
-    }
-
-  /**
-   * Calls rdbuf()->open( @a file, @a  argv, @a mode )
-   * and sets @c failbit on error.
-   *
-   * @param file  a string containing the pathname of a program to execute.
-   * @param argv  a vector of argument strings passed to the new program.
-   * @param mode  the I/O mode to use when opening the pipe.
-   * @see   basic_pstreambuf::open(const std::string&, const argv_type&, pmode)
-   */
-  template <typename C, typename T>
-    inline void
-    pstream_common<C,T>::do_open( const std::string& file,
-                                  const argv_type& argv,
-                                  pmode mode )
-    {
-      if (!buf_.open((command_=file), argv, mode))
-        this->setstate(std::ios_base::failbit);
-    }
-
-  /** Calls rdbuf->close() and sets @c failbit on error. */
-  template <typename C, typename T>
-    inline void
-    pstream_common<C,T>::close()
-    {
-      if (!buf_.close())
-        this->setstate(std::ios_base::failbit);
-    }
-
-  /**
-   * @return  rdbuf()->is_open().
-   * @see     basic_pstreambuf::is_open()
-   */
-  template <typename C, typename T>
-    inline bool
-    pstream_common<C,T>::is_open() const
-    {
-      return buf_.is_open();
-    }
-
-  /** @return a string containing the command used to initialise the stream. */
-  template <typename C, typename T>
-    inline const std::string&
-    pstream_common<C,T>::command() const
-    {
-      return command_;
-    }
-
-  /** @return a pointer to the private stream buffer member. */
-  // TODO  document behaviour if buffer replaced.
-  template <typename C, typename T>
-    inline typename pstream_common<C,T>::streambuf_type*
-    pstream_common<C,T>::rdbuf() const
-    {
-      return const_cast<streambuf_type*>(&buf_);
-    }
-
-
-#if REDI_EVISCERATE_PSTREAMS
-  /**
-   * @def REDI_EVISCERATE_PSTREAMS
-   * If this macro has a non-zero value then certain internals of the
-   * @c basic_pstreambuf template class are exposed. In general this is
-   * a Bad Thing, as the internal implementation is largely undocumented
-   * and may be subject to change at any time, so this feature is only
-   * provided because it might make PStreams useful in situations where
-   * it is necessary to do Bad Things.
-   */
-
-  /**
-   * @warning  This function exposes the internals of the stream buffer and
-   *           should be used with caution. It is the caller's responsibility
-   *           to flush streams etc. in order to clear any buffered data.
-   *           The POSIX.1 function <b>fdopen</b>(3) is used to obtain the
-   *           @c FILE pointers from the streambuf's private file descriptor
-   *           members so consult your system's documentation for
-   *           <b>fdopen</b>(3).
-   *
-   * @param   in    A FILE* that will refer to the process' stdin.
-   * @param   out   A FILE* that will refer to the process' stdout.
-   * @param   err   A FILE* that will refer to the process' stderr.
-   * @return  An OR of zero or more of @c pstdin, @c pstdout, @c pstderr.
-   *
-   * For each open stream shared with the child process a @c FILE* is
-   * obtained and assigned to the corresponding parameter. For closed
-   * streams @c NULL is assigned to the parameter.
-   * The return value can be tested to see which parameters should be
-   * @c !NULL by masking with the corresponding @c pmode value.
-   *
-   * @see <b>fdopen</b>(3)
-   */
-  template <typename C, typename T>
-    std::size_t
-    basic_pstreambuf<C,T>::fopen(FILE*& in, FILE*& out, FILE*& err)
-    {
-      in = out = err = NULL;
-      std::size_t open_files = 0;
-      if (wpipe() > -1)
-      {
-        if ((in = ::fdopen(wpipe(), "w")))
-        {
-            open_files |= pstdin;
-        }
-      }
-      if (rpipe(rsrc_out) > -1)
-      {
-        if ((out = ::fdopen(rpipe(rsrc_out), "r")))
-        {
-            open_files |= pstdout;
-        }
-      }
-      if (rpipe(rsrc_err) > -1)
-      {
-        if ((err = ::fdopen(rpipe(rsrc_err), "r")))
-        {
-            open_files |= pstderr;
-        }
-      }
-      return open_files;
-    }
-
-  /**
-   *  @warning This function exposes the internals of the stream buffer and
-   *  should be used with caution.
-   *
-   *  @param  in   A FILE* that will refer to the process' stdin.
-   *  @param  out  A FILE* that will refer to the process' stdout.
-   *  @param  err  A FILE* that will refer to the process' stderr.
-   *  @return A bitwise-or of zero or more of @c pstdin, @c pstdout, @c pstderr.
-   *  @see    basic_pstreambuf::fopen()
-   */
-  template <typename C, typename T>
-    inline std::size_t
-    pstream_common<C,T>::fopen(FILE*& fin, FILE*& fout, FILE*& ferr)
-    {
-      return buf_.fopen(fin, fout, ferr);
-    }
-
-#endif // REDI_EVISCERATE_PSTREAMS
-
-
-} // namespace redi
-
-/**
- * @mainpage PStreams Reference
- * @htmlinclude mainpage.html
- */
-
-#endif  // REDI_PSTREAM_H_SEEN
-
-// vim: ts=2 sw=2 expandtab
-