Extend fdstream

1 files changed, 259 insertions, 51 deletions

diff --git a/butl/fdstream b/butl/fdstream
index 23cc58c..bb14f25 100644
--- a/butl/fdstream
+++ b/butl/fdstream
@@ -5,24 +5,37 @@
 #ifndef BUTL_FDSTREAM
 #define BUTL_FDSTREAM
 
+#include <string>
 #include <istream>
 #include <ostream>
 #include <cstdint> // uint16_t
 
 #include <butl/path>
-#include <butl/filesystem>  // permissions
+#include <butl/filesystem> // permissions
 
 namespace butl
 {
-  // An iostream that is initialized with a file descriptor rather than
-  // a file name.
+  // An [io]fstream that can be initialized with a file descriptor in addition
+  // to a file name and that also by default enables exceptions on badbit and
+  // failbit. So instead of a dance like this:
+  //
+  // ifstream ifs;
+  // ifs.exceptions (ifstream::badbit | ifstream::failbit);
+  // ifs.open (path.string ());
+  //
+  // You can simply do:
+  //
+  // ifdstream ifs (path);
   //
   // Notes and limitations:
   //
   // - char only
   // - input or output but not both
   // - no support for put back
-  // - throws std::system_error in case of a read()/write() error
+  // - throws ios::failure in case of open()/read()/write()/close() errors
+  // - exception mask has at least badbit
+  // - after catching an exception caused by badbit the stream is no longer
+  //   used
   // - not movable, though can be easily supported
   //
   class fdbuf: public std::basic_streambuf<char>
@@ -80,81 +93,262 @@ namespace butl
     char buf_[4096];
   };
 
-  // File descriptor translation mode. It has the same semantics as the
-  // binary/text opening modes in std::fstream. Specifically, this is a
-  // noop for POSIX systems where the two modes are the same.
+  // File stream mode.
+  //
+  // The text/binary flags have the same semantics as those in std::fstream.
+  // Specifically, this is a noop for POSIX systems where the two modes are
+  // the same.
   //
-  enum class fdtranslate
+  // The skip flag instructs the stream to skip to the end before closing the
+  // file descriptor. This is primarily useful when working with pipes where
+  // you may want not to "offend" the other end by closing your end before
+  // reading all the data.
+  //
+  enum class fdstream_mode: std::uint16_t
   {
-    text,
-    binary
+    text   = 0x01,
+    binary = 0x02,
+    skip   = 0x04
   };
 
+  fdstream_mode operator& (fdstream_mode, fdstream_mode);
+  fdstream_mode operator| (fdstream_mode, fdstream_mode);
+  fdstream_mode operator&= (fdstream_mode&, fdstream_mode);
+  fdstream_mode operator|= (fdstream_mode&, fdstream_mode);
+
+  // Extended (compared to ios::openmode) file open flags.
+  //
+  enum class fdopen_mode: std::uint16_t
+  {
+    in         = 0x01, // Open for reading.
+    out        = 0x02, // Open for writing.
+    append     = 0x04, // Seek to the end of file before each write.
+    truncate   = 0x08, // Discard the file contents on open.
+    create     = 0x10, // Create a file if not exists.
+    exclusive  = 0x20, // Fail if the file exists and the create flag is set.
+    binary     = 0x40, // Set binary translation mode.
+    at_end     = 0x80, // Seek to the end of stream immediately after open.
+
+    none = 0           // Usefull when build the mode incrementally.
+  };
+
+  fdopen_mode operator& (fdopen_mode, fdopen_mode);
+  fdopen_mode operator| (fdopen_mode, fdopen_mode);
+  fdopen_mode operator&= (fdopen_mode&, fdopen_mode);
+  fdopen_mode operator|= (fdopen_mode&, fdopen_mode);
+
   class fdstream_base
   {
   protected:
     fdstream_base () = default;
     fdstream_base (int fd): buf_ (fd) {}
-    fdstream_base (int, fdtranslate);
+    fdstream_base (int, fdstream_mode);
 
   protected:
     fdbuf buf_;
   };
 
-  // Note that the destructor may throw.
+  // iofdstream constructors and open() functions that take openmode as an
+  // argument mimic the corresponding iofstream functions in terms of the
+  // openmode mask interpretation. They throw std::invalid_argument for an
+  // invalid combination of flags (as per the standard). Note that the in and
+  // out flags are always added implicitly for ifdstream and ofdstream,
+  // respectively.
+  //
+  // iofdstream constructors and open() functions that take fdopen_mode as an
+  // argument interpret the mask literally just ignoring some flags which are
+  // meaningless in the absense of others (read more on that in the comment
+  // for fdopen()). Note that the in and out flags are always added implicitly
+  // for ifdstream and ofdstream, respectively.
+  //
+  // iofdstream constructors and open() functions that take file path as a
+  // const std::string& or const char* may throw the invalid_path exception.
+  //
+  // Passing -1 as a file descriptor is valid and results in the creation of
+  // an unopened object.
+  //
+  // Also note that open() and close() functions can be successfully called
+  // for an opened and unopened objects respectively. That is in contrast with
+  // iofstream that sets failbit in such cases.
+  //
+  // @@ Need to make sure performance is on par with fstream on both
+  //    Linux and Windows.
+  //
+  // @@ Do we need to increase default buffer size? Make it customizable?
+  //    Wonder what it is in libstdc++ and MSVC?
+
+  // Note that ifdstream destructor will close an open file descriptor but
+  // will ignore any errors. To detect such errors, call close() explicitly.
   //
   class ifdstream: fdstream_base, public std::istream
   {
   public:
-    ifdstream (): std::istream (&buf_) {}
-    ifdstream (int fd): fdstream_base (fd), std::istream (&buf_) {}
-    ifdstream (int fd, fdtranslate m)
-        : fdstream_base (fd, m), std::istream (&buf_) {}
+    // Create an unopened object with iostate = badbit | failbit (we cannot
+    // have the iostate as an argument since it clashes with int fd) To create
+    // an unopened object with non-default exception mask one can do:
+    //
+    // ifdstream (-1, ...);
+    //
+    ifdstream ();
+
+    explicit
+    ifdstream (int fd, iostate e = badbit | failbit);
+    ifdstream (int fd, fdstream_mode m, iostate e = badbit | failbit);
+
+    explicit
+    ifdstream (const char*,
+               openmode = in,
+               iostate e = badbit | failbit);
+
+    explicit
+    ifdstream (const std::string&,
+               openmode = in,
+               iostate e = badbit | failbit);
+
+    explicit
+    ifdstream (const path&,
+               openmode = in,
+               iostate e = badbit | failbit);
+
+    ifdstream (const char*,
+               fdopen_mode,
+               iostate e = badbit | failbit);
+
+    ifdstream (const std::string&,
+               fdopen_mode,
+               iostate e = badbit | failbit);
+
+    ifdstream (const path&,
+               fdopen_mode,
+               iostate e = badbit | failbit);
+
+    ~ifdstream () override;
+
+    void
+    open (const char*, openmode = in);
+
+    void
+    open (const std::string&, openmode = in);
+
+    void
+    open (const path&, openmode = in);
+
+    void
+    open (const char*, fdopen_mode);
 
-    void close () {buf_.close ();}
-    void open (int fd) {buf_.open (fd);}
+    void
+    open (const std::string&, fdopen_mode);
+
+    void
+    open (const path&, fdopen_mode);
+
+    void
+    open (int fd) {buf_.open (fd); clear();}
+
+    void close ();
     bool is_open () const {return buf_.is_open ();}
+
+  private:
+    bool skip_ = false;
   };
 
-  // Note that the destructor flushes the stream and may throw.
+  // Note that ofdstream requires that you explicitly call close() before
+  // destroying it. Or, more specifically, the ofdstream object should not be
+  // in the opened state by the time its destructor is called, unless it is in
+  // the "not good" state (good() == false) or the destructor is being called
+  // during the stack unwinding due to an exception being thrown
+  // (std::uncaught_exception() == true). This is enforced with assert() in
+  // the ofdstream destructor.
   //
   class ofdstream: fdstream_base, public std::ostream
   {
   public:
-    ofdstream (): std::ostream (&buf_) {}
-    ofdstream (int fd): fdstream_base (fd), std::ostream (&buf_) {}
-    ofdstream (int fd, fdtranslate m)
-        : fdstream_base (fd, m), std::ostream (&buf_) {}
+    // Create an unopened object with iostate = badbit | failbit (we cannot
+    // have the iostate as an argument since it clashes with int fd). To create
+    // an unopened object with non-default exception mask one can do:
+    //
+    // ofdstream (-1, ...);
+    //
+    ofdstream ();
 
-    ~ofdstream () override {if (is_open () && good ()) buf_.sync ();}
+    explicit
+    ofdstream (int fd, iostate e = badbit | failbit);
+    ofdstream (int fd, fdstream_mode m, iostate e = badbit | failbit);
 
-    void close () {flush (); buf_.close ();}
-    void open (int fd) {buf_.open (fd);}
-    bool is_open () const {return buf_.is_open ();}
-  };
+    explicit
+    ofdstream (const char*,
+               openmode = out,
+               iostate e = badbit | failbit);
 
-  // File open flags.
-  //
-  enum class fdopen_mode: std::uint16_t
-  {
-    in         = 0x01, // Open for reading.
-    out        = 0x02, // Open for writing.
-    append     = 0x04, // Seek to the end of file before each write.
-    truncate   = 0x08, // Discard the file contents on open.
-    create     = 0x10, // Create a file if not exists.
-    exclusive  = 0x20, // Fail if the file exists and the create flag is set.
-    binary     = 0x40, // Set binary translation mode.
+    explicit
+    ofdstream (const std::string&,
+               openmode = out,
+               iostate e = badbit | failbit);
 
-    none = 0           // Usefull when build the mode incrementally.
+    explicit
+    ofdstream (const path&,
+               openmode = out,
+               iostate e = badbit | failbit);
+
+    ofdstream (const char*,
+               fdopen_mode,
+               iostate e = badbit | failbit);
+
+    ofdstream (const std::string&,
+               fdopen_mode,
+               iostate e = badbit | failbit);
+
+    ofdstream (const path&,
+               fdopen_mode,
+               iostate e = badbit | failbit);
+
+    ~ofdstream () override;
+
+    void
+    open (const char*, openmode = out);
+
+    void
+    open (const std::string&, openmode = out);
+
+    void
+    open (const path&, openmode = out);
+
+    void
+    open (const char*, fdopen_mode);
+
+    void
+    open (const std::string&, fdopen_mode);
+
+    void
+    open (const path&, fdopen_mode);
+
+    void
+    open (int fd) {buf_.open (fd); clear ();}
+
+    void close () {if (is_open ()) flush (); buf_.close ();}
+    bool is_open () const {return buf_.is_open ();}
   };
 
-  fdopen_mode operator& (fdopen_mode, fdopen_mode);
-  fdopen_mode operator| (fdopen_mode, fdopen_mode);
-  fdopen_mode operator&= (fdopen_mode&, fdopen_mode);
-  fdopen_mode operator|= (fdopen_mode&, fdopen_mode);
+  // The std::getline() replacement that provides a workaround for libstdc++'s
+  // ios::failure ABI fiasco (#66145) by throwing ios::failure, as it is
+  // defined at libbutl build time (new ABI on recent distributions) rather
+  // than libstdc++ build time (still old ABI on most distributions).
+  //
+  // Notes:
+  //
+  // - This relies of ADL so if the stream is used via the std::istream
+  //   interface, then std::getline() will still be used. To put it another
+  //   way, this is "the best we can do" until GCC folks get their act
+  //   together.
+  //
+  // - The fail and eof bits may be left cleared in the stream exception mask
+  //   when the function throws because of badbit.
+  //
+  ifdstream&
+  getline (ifdstream&, std::string&, char delim = '\n');
 
   // Open a file returning the file descriptor on success and throwing
-  // std::system_error otherwise.
+  // ios:failure otherwise.
   //
   // The mode argument should have at least one of the in or out flags set.
   // The append and truncate flags are meaningless in the absense of the out
@@ -170,6 +364,20 @@ namespace butl
   // Windows permissions other than ru and wu are unlikelly to have effect.
   //
   int
+  fdopen (const char*,
+          fdopen_mode,
+          permissions = permissions::ru | permissions::wu |
+                        permissions::rg | permissions::wg |
+                        permissions::ro | permissions::wo);
+
+  int
+  fdopen (const std::string&,
+          fdopen_mode,
+          permissions = permissions::ru | permissions::wu |
+                        permissions::rg | permissions::wg |
+                        permissions::ro | permissions::wo);
+
+  int
   fdopen (const path&,
           fdopen_mode,
           permissions = permissions::ru | permissions::wu |
@@ -177,17 +385,17 @@ namespace butl
                         permissions::ro | permissions::wo);
 
   // Set the translation mode for the file descriptor. Return the previous
-  // mode on success, throw std::system_error otherwise.
+  // mode on success, throw ios::failure otherwise.
   //
-  fdtranslate
-  fdmode (int, fdtranslate);
+  fdstream_mode
+  fdmode (int, fdstream_mode);
 
   // Convenience functions for setting the translation mode for standard
   // streams.
   //
-  fdtranslate stdin_fdmode  (fdtranslate);
-  fdtranslate stdout_fdmode (fdtranslate);
-  fdtranslate stderr_fdmode (fdtranslate);
+  fdstream_mode stdin_fdmode  (fdstream_mode);
+  fdstream_mode stdout_fdmode (fdstream_mode);
+  fdstream_mode stderr_fdmode (fdstream_mode);
 
   // Low-level, nothrow file descriptor API.
   //