rsocket

#pragma once
 
#include <randolf/rex>
#include <randolf/rline>
#include <randolf/rring>
#include <randolf/rring_bam>
#include <randolf/rsocket_io>
#include <randolf/rsocket_sni>
#include <randolf/rtools>
#include <randolf/sockaddr_dl.h>
 
#include <atomic>
#include <bit>                // std::endian
#include <cstdarg>            // std::va_list
#include <cstring>            // std::strlen
#include <ctime>              // std::strftime
#include <exception>          // std::exception
#include <filesystem>         // std::filesystem::temp_directory_path
#include <initializer_list>
#include <iostream>           // std::put_date
#include <map>                // std::map
#include <memory>             // std::shared_ptr
#include <mutex>              // std::mutex
#include <regex>
#include <set>
//#include <sstream>            // std::ostringstream
#include <unordered_map>      // std::unordered_map
#include <vector>
 
#include <ifaddrs.h>
#include <netdb.h>
#include <poll.h>
#include <string.h>           // strerror()
#include <unistd.h>
 
#include <arpa/inet.h>
 
#include <linux/fs.h>         // Flags for ioctl()
 
#include <net/if.h>           // ifreq structure used by bind()
 
#include <netinet/icmp6.h>
#include <netinet/in.h>
 
#include <netpacket/packet.h> // struct sockaddr_ll
 
#include <openssl/err.h>
#include <openssl/ossl_typ.h>
#include <openssl/ssl.h>
 
#include <sys/ioctl.h>
#include <sys/socket.h>
#include <sys/stat.h>         // fchmod()
#include <sys/time.h>         // TIMEVAL_TO_TIMESPEC macro
#include <sys/types.h>
#include <sys/un.h>
 
static_assert((sizeof(__time_t) * CHAR_BIT) >= 64, "__time_t of at least 64-bit is required");
 
namespace randolf {
 
  /*======================================================================*//**
  @brief
  This @ref rsocket class provides an easy-to-use and thoroughy-implemented
  object-oriented socket I/O interface for C++, intended to make socket I/O
  programming (with or without TLS encryption) easier and more enjoyable.
 
  Here's a short list of benefits that are helpful in developing high quality
  code that's consistent-and-reliable, and improves overall productivity:
 
     - eliminating the need to repeatedly write blocks of code that check for
       errors, by throwing exceptions instead (see @ref randolf::rex::rex class
       for details and the long list of exceptions that are supported)
     - eliminating the need to track socket descriptors
     - eliminating the need to handle encrypted I/O separately (most functions)
     - eliminating the need to manage memory for many common structures used to
       interface with socket options, etc.
     - eliminating the need to record socket I/O statistics with every call to
       underlying socket I/O functions (see @ref randolf::rsocket_io for
       details)
     - text-line reading/writing with an adapative approach (invented by
       Randolf Richardson in the 1980s for a custom BBS software project) to
       automatically detect EoL (End-of-Line) character sequences (unless the
       developer provides a specific sequence via an @ref eol method) that can
       determine whether an endpoint is sending Linux/UNIX (standard), MacOS,
       DOS CR/LF, or even broken LF/CR (reverse of DOS) EoL sequences
     - transparent support for encryption with many additional features,
       including STARTTLS, ingress/egress policy enforcement, and SNI
     - eliminating the complexity of handling events with poll(), select(), and
       related functions (see the @ref randolf::rsocket_mux class for details)
     - providing a variety of other useful features that make it easier to
       communicate with socket endpoints, such as receiving/sending an entire
       structure via a single call to the new-and-specialized @ref recv_struct
       or @ref send_struct methods, respectively
 
  An rsocket is either the endpoint that our underlying socket will connect to,
  or it's the server daemon that our underying socket will listen() to and
  accept() [inbound] connections from.
 
  @par Use case
 
  Using the C interface, the programming must check for errors by testing the
  response codes (most of which are consistent, with a few subtle outliers),
  which leads to a lot of additional error-checking code with the potential for
  unintended errors (a.k.a., bugs).  This style is necessary in C, but with C++
  the way to handle errors is with exceptions, so I created this rsocket class
  to handle all these tedious details behind-the-scenes and, for any socket
  errors, to generate exceptions so that source code can be greatly simplified
  (and, as a result, also easier to read and review).
 
  Pre-allocating buffers is also handled internally, which is particularly
  useful when making repeated calls to recv() and related methods.  These
  methods return std::shared_ptr<@c structure > (a C++ smart pointer that aids
  in the prevention of resource leaks) or std::vector<char> (resized to the
  actual number of bytes received) as appropriate which eliminates the need to
  track @c size_t separately.
 
  @par Conventions
  Lower-case letter "r" is regularly used in partial example code to represent
  an instantiated rsocket object.
 
  An ASCIIZ string is a C-string (char* array) that includes a terminating null
  (0) character at the end.
 
  The following custom qualifiers are incorporated into headings by Doxygen
  alongside method titles throughout the documentation:
     - @c POSIX denotes a method that is based on POSIX functions by the same
       name and don't deviate significantly from the POSIX function arguments
       (intended to be helpful to developers transitioning to/from rsocket or
       working on source code that utilizes @ref rsocket and POSIX functions)
     - @c TLS denotes that a method works properly with TLS-encrypted sockets
       (most of the POSIX functions have been made to work properly with TLS,
       but for the few rare cases of functions that can't be made to work with
       TLS an effort has also been made to mention this using Doxygen's
       "warning" sections in addition to omitting the TLS qualifier)
 
  @par Getting started with a few simple examples
 
  This is an example of connecting to an HTTP server, using the "GET" command
  to request the home page (using HTTP/1.0), then receiving-and-displaying the
  resulting web page's contents via STDOUT (or sending an error message to
  STDERR).  Finally, we exit with an EXIT_SUCCESS (or EXIT_FAILURE) code.
 
  @code{.cpp}
    #include <iostream> // std::cout, std::cerr, std::endl, etc.
    #include <randolf/rex>
    #include <randolf/rsocket>
 
    int main(int argc, char *argv[]) {
      try {
        randolf::rsocket r(AF_INET, SOCK_STREAM, IPPROTO_TCP);
        r.connect("www.example.com", 80);
        r.sendline("GET / HTTP/1.0");
        r.sendline("Host: www.example.com");
        r.sendline("Connection: close");
        r.send_eol();
        while (r.is_open()) {
          std::cout << r.recvline(0, MSG_WAITALL) << std::endl;
        } // -x- while data -x-
        r.close();
      } catch (const randolf::rex::xALL e) {
        std::cerr << "Socket exception: " << e.what() << std::endl;
        return EXIT_FAILURE;
      } catch (const std::exception e) {
        std::cerr << "Other exception: " << e.what() << std::endl;
        return EXIT_FAILURE;
      }
      return EXIT_SUCCESS;
    } // -x- int main -x-
  @endcode
 
  Parameter stacking is supported (with methods that return @c rsocket*); in
  this example, notice that semicolons (";") and "r." references are omittted
  (when compared with the above):
 
  @code{.cpp}
    #include <iostream> // std::cout, std::cerr, std::endl, etc.
    #include <randolf/rex>
    #include <randolf/rsocket>
 
    int main(int argc, char *argv[]) {
      try {
        randolf::rsocket r(AF_INET, SOCK_STREAM, IPPROTO_TCP);
        r.connect("www.example.com", 80)
        ->sendline("GET / HTTP/1.0")
        ->sendline("Host: www.example.com")
        ->sendline("Connection: close")
        ->send_eol();
        while (r.is_open()) {
          std::cout << r.recvline(0, MSG_WAITALL) << std::endl;
        } // -x- while data -x-
        r.close();
      } catch (const randolf::rex::xALL e) {
        std::cerr << "Socket exception: " << e.what() << std::endl;
        return EXIT_FAILURE;
      } catch (const std::exception e) {
        std::cerr << "Other exception: " << e.what() << std::endl;
        return EXIT_FAILURE;
      }
      return EXIT_SUCCESS;
    } // -x- int main -x-
  @endcode
 
  @par Features
 
  This is meant to be a comprehensive socket class for C++, which is intended
  to make socket I/O coding easier for developers with some key features:
 
     - easy conversion from C-style POSIX sockets due to API consistency
     - transparent TLS support (OpenSSL dependency)
        - keys and certificate chains can also be loaded from memory
        - SNI support (see the @ref rsocket_sni class for more information)
     - underlying socket handle is accessible (via the @ref socket_fd() method)
     - socket options are easier to get and to set
        - sensible support for future or unknown socket options
     - errors are presented as ~100 separate exception classes: @ref rex::rex
        - one parent exception class makes it easier to catch all socket errors
        - a few exceptions groups are also provided to catch groups of errors
     - new buffers are returned as std::shared_ptr's to eliminate memory leaks
     - constructors with sensible defaults help to simplify coding
     - documentation includes code samples (with @c \#include lines as needed)
     - debug output with helpful output (and option to set output file handle)
     - low-overhead is considered (this is why there's a bit more overloading)
     - thread-safety is noted where it is absolutely available (if any caution
       is warranted, it will also be noted)
     - can send ASCIIZ (C-strings) without needing to specify string length
     - can send @c std::string (which tracks its own string length)
     - each socket can optionally have a @ref name arbitrarily assigned (e.g.,
       by an algorithm, or even populated with the connecting user's name, or
       whatever purpose the development goals find it useful for)
 
  Additional features that are not part of the typical POSIX standard, but
  deserve special mention because they are needed so often:
 
     - easy access to internal I/O counters (see @ref rsocket_io for details)
        - your rsocket_io structure can be updated automatically by rsocket's
          destructor after underlying socket is closed (see @c net_io_final()
          method for details)
     - printf(), printfline(), vprintf(), vprintfline() // Formatted strings
        - with automatic EoL sequence substitution (and/or the addition of)
     - recv_asciiz(), send_asciiz() // ASCIIZ string I/O operations
     - recv_byte()  , send_byte()   // 8-bit byte operations (LSB/MSB is N/A)
     - recv_struct(), send_struct() // Multi-byte operations
     - recv_uint16(), send_uint16() // 16-bit operations with LSB/MSB variants
     - recv_uint32(), send_uint32() // 32-bit operations with LSB/MSB variants
     - recv_uint64(), send_uint64() // 64-bit operations with LSB/MSB variants
     - recvline(), recv_rline(), sendline() // ASCII text line I/O operations
        - class-wide configurable newline sequence (defaults to @e autodetect)
     - @ref rsocket_group class for grouping rsockets (and automatic inclusion
       by accept() and accept4() methods; this may be a different group from
       whichever group the parent rsocket is in, if it's even in one)
        - option to send data to all rsocket objects in the rsocket_group
        - with support from the rsocket_mux class (for multiplexing operations)
        - automatic naming policies (possibly like net_io() formatting style)
 
  Some advanced features are planned that exceed what the basic socket I/O
  functions provide, but are also needed:
 
     - recv_uint128()/send_uint128() // 128-bit operations w/ LSB/MSB variants
     - recv_uint(n)/send_uint(n) where "n" specifies the number of bits (which
       must be a multiple of 8), with LSB/MSB variants
     - auto-detection of inbound TLS connection (this is turned off by default)
        - This is not the same as STARTTLS (an application-level command, for
          which the @ref tls_do_handshake() method will likely be used)
     - simple timing tracking options using timing_start() and timing_stop()
       methods, the results of which can be retrieved with timing_get() or a
       similarly-named group of methods
 
  Other features that are not a high priority:
 
     - internal support for portability to Microsoft Windows, which is a major
       undertaking that I know will be time-consuming since Windows Sockets
       exhibit some nuanced behaviours and are not consistent with POSIX
       sockets APIs that are used by Linux, UNIX, MacOS, and pretty much all
       other Operating Systems.  Because of this, MS-Windows portability just
       isn't a high priority for me (without sufficient demand and sufficient
       funding so I can commit my time without missing mortgage payments,
       student loan payments {for my kids}, various living expenses, etc.).
 
  @par Requirements
  The @c __time_t structure must be 64-bit (or larger).  This becomes espcially
  important for the @ref recvline method, in addition to Year 2038 compliance.
 
  @par Notes
 
  I use the term "ASCIIZ string" to indicate an array of characters that's
  terminated by a 0 (a.k.a., null).  Although this is very much the same as a
  C-string, the difference is that in many API functions a C-string must often
  be accompanied by its length value.  When referring to an ASCIIZ string, I'm
  intentionally indicating that the length of the string is not needed because
  the string is null-terminated.  (This term was also commonly used in assembly
  language programming in the 1970s, 1980s, and 1990s, and as far as I know is
  still used by machine language programmers today.)
 
  UTF-8 works without any problems as it is backward-compatible to 8-bit ASCII,
  and because @c std::string uses 8-bit bytes to store strings internally.  Do
  keep in mind that the manipulation of UTF-8 substrings will require working
  with UTF-8 codepoints that may consume one or more bytes, which is beyond the
  scope of the impartial (to UTF-8 and ASCII) functionality that this rsocket
  class provides.
 
  UTF-8 newline codepoints NEL (c2 85), LS (e2 80 a8), and PS (e2 80 a9) garner
  no special handling at this time - unlike CR/LF (0d/0a) - and are merely
  treated as non-newline codepoints.  There is a possibility of adding support
  for this in the future, but additional research and planning is required to
  make sure this works properly.  What is most likely is that some UTF-8 flags
  will be added to support each of these (which will probably be disabled by
  default) that will be integrated into the readline() methods.  This also
  depends on how widely used these particular codepoints are, and pending
  further research to determine whether these really are supposed to be used
  functionally as newlines...
 
  So far, there are two UTF-8 codepoints that absolutely are not functional,
  yet which a small number of people have mistakenly assumed are:
    - <sup>C</sup><sub>R</sub> = superscript "C" with subscript "R" (e2 90 9d)
    - <sup>N</sup><sub>L</sub> = superscript "N" with subscript "L" (e2 90 a4)
 
  The special characters above are intended to represent the Carriage-Return
  and New-Line respectively in documentation such as ASCII character reference
  charts, which were used mostly by IBM in the 1970s and 1980s for instruction
  manuals (and in other documentation), and also on a few keyboard overlays.
 
  @par Background
 
  I created this class to make it easier to write internet server daemons.  I
  started out using C-style socket functions (because C++ doesn't come with a
  socket class), but I found that I didn't enjoy mixing something as important
  and detailed as socket I/O in a procedural way into the object-oriented
  paradigm that C++ provides.
 
  After looking for existing solutions (none of which served as comprehensive
  replacements for socket I/O), I embarked on creating the rsocket class, and
  then I began to understand why this probably hadn't been done -- it's a
  massive undertaking, primarily because there are a lot of functions that are
  needed to handle socket I/O.  Further, [at the time of this writing] the @c
  sockaddr_storage structure wasn't as widely used as it should be, and so
  information about it tended to be scarce, incomplete, or incorrect (further
  research, and diving down into some pretty deep "rabbit holes," was required
  to understand this properly, which was worthwhile because it resulted in
  having transparent support for IPv4 and IPv6 without breaking backward
  compatibility for code expecting specific structures).
 
  Moving error codes into exceptions is also a major effort because they are
  diverse and plentiful, and there are so many errors that can occur at various
  stages for many different reasons.  There are also a few outlier functions
  that require slightly different approaches to error handling due to subtly
  different rules for handling their errors, and so the exception-generation
  wasn't as straight-forward as one might optimistically expect, but this is
  one of the many benefits of the object-oriented programming pardigm because
  handling edge cases internally results in a consistent error-handling
  interface using exceptions that also simplifies the source code.  (Need to
  handle a specific set of conditions?  Catch the relevant exceptions for those
  cases in an inner set of exceptions, and just catch all the others in a more
  general way without the added complexity of repeatedly checking for errors
  every step along the way.)
 
  So, I dedicated time to make this work, and with the intention of making it
  an open source project once I got it into a state that's ready for the
  general public.  This required putting my other C++ projects on hold, which
  was fine because they didn't have strict deadlines and using this socket
  class in them will speed up development in the long-term anyway, so it's
  clearly worth the effort to me ... and I sincerely hope that my efforts will
  be helpful to others too.
 
  My background in programming began when I was a young child, teaching myself
  BASIC and then machine language (when I found BASIC to be too limited) before
  moving on to other languages like Perl and Java many years later.  Eventually
  I circled around to C (which I chose to learn the hard way by writing some
  PostgreSQL extensions) and then C++ a few years after that.  I have a lot of
  experience with socket communications, including fully-featured DNS resolver
  library code in machine language for Novell's NetWare that used C calling
  conventions and supported varargs, which worked well for the few developers
  who needed or wanted it.
 
  @par History
    - 2022-Nov-09 v1.00 Initial version
    - 2022-Nov-26 v1.00 Moved exception handling to a separate class
    - 2022-Nov-28 v1.00 Completed readline/send functionality
    - 2022-Dec-03 v1.00 Added endianness transparency
    - 2022-Dec-04 v1.00 Added printf() support
    - 2022-Dec-24 v1.00 Added socket MUXing
    - 2023-Feb-22 v1.00 Added TLS/SSL support
    - 2023-Mar-10 v1.00 Added TLS-SNI support
    - 2023-Apr-19 v1.00 Added TLS certificate loading from memory
    - 2023-May-24 v1.00 Added support for clang++ compilation
    - 2023-Jun-09 v1.00 Improvements to dynamic internal read buffering
    - 2023-Oct-31 v1.00 Improvements to various classes
    - 2024-Feb-21 v1.00 Added is_buffered() method
    - 2024-Mar-31 v1.00 Completed @ref recvline (implemented a work-around for
                        a subtle SSL_peek failure to extract additional data
                        when a user at an end-point is communicating with
                        "icanon" mode enabled)
    - 2024-May-24 v1.00 Changed source code to accomodate @c clang++ compiler
    - 2024-Jun-04 v1.00 Added @c POSIX and @c TLS qualifiers to all applicable
                        methods (Doxygen incorporates into the documentation)
    - 2024-Oct-23 v1.00 Various minor improvements to the documentation since
                        the previous update
    - 2024-Nov-05 v1.00 Added eol_consumed_seq() method
    - 2024-Nov-10 v1.00 Added discard() method
    - 2024-Nov-17 v1.00 Added recv_rline() method
    - 2024-Nov-19 v1.00 Added recv_as_string() method
    - 2024-Nov-22 v1.00 Added discard_line() method
    - 2024-Nov-28 v1.00 Switched internal ring buffer to a proper ring buffer
                        that's now available in the rring class (which was made
                        initially for this purpose)
    - 2024-Dec-08 v1.00 Improved shutdown() method to handle SSL shutdown fully
                        and added a parameter to prevent calling SSL_shutdown()
    - 2024-Dec-10 v1.00 Changed eos() method to use faster ioctl POSIX function
                        and OpenSSL's SSL_has_pending function (with TLS)
    - 2024-Dec-10 v1.00 Added RECVLINE_FLAGS enum to expand the functionality
                        of how the recvline() and recv_rline methods deal with
                        data in specific scenarios, which helps to satisify the
                        needs of specific advanced data processing scenarios
  @version 1.00
  @author Randolf Richardson
  *///=========================================================================
  class rsocket {
 
    // --------------------------------------------------------------------------
    // The rsocket_group class needs access to some of our internal variables.
    // --------------------------------------------------------------------------
    friend class                     rsocket_group;
 
    // --------------------------------------------------------------------------
    // Socket variables.
    // --------------------------------------------------------------------------
    int                              __socket_fd         = 0;
    int                              __socket_type       = 0;
    int                              __socket_protocol   = 0;
    struct sockaddr_storage          __socket_addr       = {}; // Initialize to all elements to their default values
    socklen_t                        __socket_addr_size  = sizeof(__socket_addr); // We need to point to this (and it might be modified)
    int                              __socket_backlog    = SOMAXCONN; // Default backlog is 4096 on Linux, and 128 on older systems
 
    // --------------------------------------------------------------------------
    // Socket flags (internal, but with get-methods to provide read-only access).
    // --------------------------------------------------------------------------
    std::atomic_bool                 __socket_open       = false; // Socket is open by way of socket() function
    std::atomic_bool                 __socket_connected  = false; // Socket is connected
 
    // --------------------------------------------------------------------------
    // TLS flags and variables.
    // --------------------------------------------------------------------------
    std::atomic_bool                 __tls               = false;   // Indicates whether socket I/O is encrypted with OpenSSL
    SSL_CTX*                         __tls_ctx           = nullptr; // TLS context (nullptr == no encryption initialized)
    rsocket_sni*                     __tls_sni           = nullptr; // SNI maps
    bool                             __tls_sni_match     = false;   // Set to TRUE only if SNI matched in the SNI callback
    SSL*                             __tls_fd            = nullptr; // TLS connection structure (nullptr == no connection)
    BIO*                             __tls_rbio          = nullptr; // TLS BIO input stream
    BIO*                             __tls_wbio          = nullptr; // TLS BIO output stream
    bool                             __tls_exclusive     = false;   // See enum TLS_FLAGS::TLS_EXCLUSIVE
    bool                             __tls_egress        = true;    // TRUE = permitted / see enum TLS_FLAGS::TLS_NO_EGRESS
    bool                             __tls_ingress       = true;    // TRUE = permitted / see enum TLS_FLAGS::TLS_NO_INGRESS
    bool                             __tls_server_mode   = true;    // See enum TLS_FLAGS::TLS_SERVER
    inline static std::atomic_int    __fn_counter        = 0;       // Used in generating unique-and-threadsafe temporary filenames
    rsocket*                         __tls_new_endpoint  = nullptr; // Weak pointer to newly-spawned endpoint's rsocket object
 
    // --------------------------------------------------------------------------
    // Keep track of test for whether this host stores integers using big endian.
    // --------------------------------------------------------------------------
    inline static const bool         __endian_is_msb     = htons(42) == 42; // TRUE==MSB / FALSE==LSB
 
    // --------------------------------------------------------------------------
    // General variables.  Atomic variables are used for variables as needed to
    // support operations in a thread-safe manner.
    //
    // Dynamic buffer expansion for extra-long lines resolves problems with the
    // default of 4,096 bytes for the read-ahead policy in Linux sockets.  These
    // are handled by the randolf::rring class, and echoed here.
    // --------------------------------------------------------------------------
    std::atomic_bool                 __debug             = false;
    std::atomic<std::FILE*>          __debug_fd          = stderr;
    std::string                      __debug_prefix      = "rsocket-debug";
    #define                          RSOCKET_BUFFER_SIZE   8192 // Hard-coded default buffer size
    size_t                           __buffer_size       = RSOCKET_BUFFER_SIZE; // Buffer size used by recv() when a buffer size isn't provided
    rring*                           __buffer            = nullptr;
    rring_bam*                       __buffer_bam        = nullptr; // Map of rring's memory blocks
    std::string                      __name; // Arbitrary name of this rsocket (used by some applications)
    std::string                      __name_sni; // SNI hostname (only used when tls_sni is configured)
 
    // --------------------------------------------------------------------------
    // EoL sequence variables.
    // --------------------------------------------------------------------------
    static const char                __CR                = (char)13; // CTRL-M / ASCII 13 (0Dh) / "\r" / Used by eol() methods
    static const char                __LF                = (char)10; // CTRL-J / ASCII 10 (0Ah) / "\n" / Used by eol() methods
    static constexpr const char*     __CRLF              = "\x0d\x0a";                                // Used by eol() methods
    std::string                      __eol;                          // Used by recvline() method; maintained by eol() methods
    std::string                      __eol_consumed_seq;             // The EoL sequence that was successfully received by the most recent use of the recvline() method
    bool                             __eol_adoption      = true;     // Whether to adopt the dynamically detected EoL sequence when __eol is empty (the default)
    std::string                      __eol_out           = std::string(__CRLF); // Used by sendline() method; maintained by eol() methods; also used by sendline() method
    bool                             __eol_fix_printf    = true;     // Whether to replace "\n" sequence in printf() methods to EoL sequence
 
    // --------------------------------------------------------------------------
    // Fine-tuning for __recvline().  This is used with nanosleep().
    //
    // To test, also use commands in canonical mode, like this:
    //    stty -icanon && openssl s_client host:port
    //    stty -icanon && netcat host port
    //    stty -icanon && telnet host port
    // --------------------------------------------------------------------------
    long                             __recvline_timeout  = 0; // Number of seconds (0 = unlimited; maximum for "long" equates to approximately 292 billion years since the UNIX/Linux epoch)
 
    // --------------------------------------------------------------------------
    // Statistical variables.
    // --------------------------------------------------------------------------
    rsocket_io*                      __io_final_addr     = nullptr; // Used by ~rsocket() destructor, net_io_final(), and net_io_update()
    std::atomic_ulong                __bytes_rx          = 0; // Total number of bytes received
    std::atomic_ulong                __bytes_tx          = 0; // Total number of bytes transmitted
    std::atomic_ulong                __crypt_rx          = 0; // Total number of encrypted bytes recevied
    std::atomic_ulong                __crypt_tx          = 0; // Total number of encrypted bytes transmitted
 
    public:
      /*======================================================================*//**
      @brief
      Optional flags used with rsocket's @ref recvline() and @ref recv_rline()
      methods to specify relevant text-line reading policies/semantics.
      @see recvline
      @see recv_rline
      *///=========================================================================
      enum RECVLINE_FLAGS: int {
 
        /*----------------------------------------------------------------------*//**
        The RECVLINE_DEFAULT flag isn't necessary, but it's included here for
        completeness as it accomodates programming styles that prefer to emphasize
        when defaults are being relied upon.
        *///-------------------------------------------------------------------------
        RECVLINE_DEFAULT = 0,
 
        /*----------------------------------------------------------------------*//**
        The RECVLINE_NO_DISCARD_ON_OVERFLOW flag prevents data from being discarded
        when an @ref randolf::rex::xEOVERFLOW exception is thrown (which is caused
        when a line of text exceeds the specified maximum line length).
 
        @note
        The @c MSG_PEEK flag also prevents the automatic discarding of data,
        regardless of whether the @ref randolf::rex::xEOVERFLOW is thrown, thus it
        differs from this flag in multiple ways that vary with how and why it's used.
 
        @warning
        Data will need to be consumed in a different way, such as by attempting to
        read into a larger buffer than what had been allocated, or by receiving
        portions or discarding some or all that remains.
 
        By default, when the @ref randolf::rex::xEOVERFLOW exception is thrown, all
        pending data (up to and including the upcoming EoL sequence, or the EoS,
        whichever comes first) is discarded.
        @see discard_line()
        *///-------------------------------------------------------------------------
        RECVLINE_KEEP_ON_OVERFLOW = 1,
 
        /*----------------------------------------------------------------------*//**
        The RECVLINE_PARTIAL flag receives an incomplete line of text and returns it
        instead of throwing the @ref randolf::rex::xEOVERFLOW exception, and causes
        the @ref eol_consumed_seq() method to return an empty string (which indicates
        that no EoL sequence was consumed).
        @see eol_consumed_seq()
        *///-------------------------------------------------------------------------
        RECVLINE_PARTIAL = 2,
 
      }; // -x- enum RECVLINE_FLAGS -x-
 
      /*======================================================================*//**
      @brief
      Optional flags used with various methods to determine whether they will throw
      an @ref randolf::rex::xETIMEDOUT exception or merely return a @c nullptr, an
      empty set, or a 0 (zero) when a timeout duration elapses.
 
      If you're not sure of whether to use @ref TIMEOUT_EMPTY, @ref TIMEOUT_NULL,
      or @ref TIMEOUT_ZERO in your code, then I suggest using @ref TIMEOUT_NULL
      since @c NULL will likely be the most recognizable in most code reviews.
 
      @note
      You'll know when this is an option because the method will support this.
      *///=========================================================================
      enum TIMEOUT_BEHAVIOUR: bool {
 
        /*----------------------------------------------------------------------*//**
        Indicate that an @ref randolf::rex::xETIMEDOUT exception should be thrown
        when the timeout duration elapses.
        *///-------------------------------------------------------------------------
        TIMEOUT_EXCEPTION = true,
 
        /*----------------------------------------------------------------------*//**
        Indicate that a @c nullptr, an empty set, or a 0 (zero) should be returned
        when the timeout duration elapses.
        *///-------------------------------------------------------------------------
        TIMEOUT_EMPTY = false,
 
        /*----------------------------------------------------------------------*//**
        Indicate that a @c nullptr, an empty set, or a 0 (zero) should be returned
        when the timeout duration elapses.
        *///-------------------------------------------------------------------------
        TIMEOUT_NULL = false,
 
        /*----------------------------------------------------------------------*//**
        Indicate that a @c nullptr, an empty set, or a 0 (zero) should be returned
        when the timeout duration elapses.
        *///-------------------------------------------------------------------------
        TIMEOUT_ZERO = false,
 
      }; // -x- enum TIMEOUT_BEHAVIOUR -x-
 
      /*======================================================================*//**
      @brief
      Optional flags used with rsocket's @ref tls() and @ref tls_ctx() methods to
      specify relevant policies/semantics.
      *///=========================================================================
      enum TLS_FLAGS: int {
 
        /*----------------------------------------------------------------------*//**
        The TLS_DEFAULT flag isn't necessary, but it's included here for completeness
        as it accomodates programming styles that prefer to emphasize when defaults
        are being relied upon.
        *///-------------------------------------------------------------------------
        TLS_DEFAULT = 0,
 
        /*----------------------------------------------------------------------*//**
        Only encrypted connections are permitted, initially, and all attempts to
        begin with unencrypted connections will consistently fail.
 
        Encrypted connections must begin with a cryptographic handshake packet, or
        else the connection will be rejected as due to being reasonably assumed to be
        "not encrypted."
        @post
        If this flag isn't set, an application-level mechanism can be used to upgrade
        to TLS encryption (this is common with connections that begin unencrypted,
        and issue a proprietary command {such as the @c STARTTLS command in SMTP} to
        upgrade to TLS later on {of which the @ref tls() method is used to affect an
        ingress; see the @ref TLS_NO_INGRESS flag for additional information}).
        @note
        Creating an exclusively @c unencrypted connection is accomplished by not
        initializing TLS.
        @see tls()
        @see TLS_NO_EGRESS to prevent support for application-level downgrades to
             unencrypted connections
        *///-------------------------------------------------------------------------
        TLS_EXCLUSIVE = 1,
 
        /*----------------------------------------------------------------------*//**
        Mid-stream upgrades to encrypted connections are not permitted (e.g., via
        application-level initiations like the @c STARTTLS command as seen in SMTP),
        which will also cause calls to the @ref tls() method to fail fast after plain
        non-encrypted data has already been sent or received.
        @pre
        This flag is not necessary when the @ref TLS_EXCLUSIVE flag is set.
        @see is_tls_ingress_okay()
        @see tls_do_handshake()
        @see TLS_NO_EGRESS
        *///-------------------------------------------------------------------------
        TLS_NO_INGRESS = 2,
 
        /*----------------------------------------------------------------------*//**
        Mid-stream downgrades to unencrypted connections are not permitted (e.g., via
        application-level initiations like a hypothetical @c STOPTLS command as seen
        in FTPS), which will also cause calls to the @ref tls() method to fail fast
        after encrypted data has already been sent or received.
        @pre
        This flag may be combined with the @ref TLS_EXCLUSIVE flag to prevent a
        connection from being downgraded programatically.
        @note
        Although egress to an unencrypted connection doesn't occur automatically
        (since egress can only be affected programatically to support commands at the
        application level), this flag is useful to prevent third-party code from
        downgrading an encrypted @ref rsocket to unencrypted.
        @warning
        Supporting unencrypted communications is strongly discouraged over public
        networks (e.g., the internet) because unencrypted streams are trivially
        susceptible to man-in-the-middle attacks that can alter the contents of the
        data in both directions (which is a particularly dangerous prospect for
        sending/receiving sensitive information).
        @see is_tls_egress_okay()
        @see TLS_NO_INGRESS
        *///-------------------------------------------------------------------------
        TLS_NO_EGRESS = 4,
 
        /*----------------------------------------------------------------------*//**
        This is a convenience flag that provides an option for developers to be more
        clear in their use of the @ref tls() and @ref tls_ctx() methods to indicate
        intent to rely on what is already the default.
        @see tls_do_handshake()
        @see TLS_SERVER
        *///-------------------------------------------------------------------------
        TLS_CLIENT = 0,
 
        /*----------------------------------------------------------------------*//**
        Indicates that this rsocket will be for a server daemon, and to initialize a
        new TLS context (when one isn't being provided) using OpenSSL's
        @c TLS_server_method() function instead of OpenSSL's @c TLS_client_method()
        function (the latter is the default because most code is anticipated to be
        client-oriented).
 
        @attention
        Setting the CLIENT/SERVER flag incorrectly will typically cause the following
        error that's difficult to track down, which is usually triggered by calling
        @ref accept, @ref accept4(), or @ref connect(), and so I hope that including
        this information here in this documentation will be helpful:
        @verbatim
        error:140C5042:SSL routines:ssl_undefined_function:called a function you should not call
        @endverbatim
 
        The absence of this flag has the same effect as specifying the @ref
        TLS_CLIENT flag.
        @see TLS_CLIENT
        *///-------------------------------------------------------------------------
        TLS_SERVER = 8,
 
      }; // -x- enum TLS_FLAGS -x-
 
    private:
      /*======================================================================*//**
      Return Code check, and throws an rsocket-specific exception if an error
      occurred, which is indicated by @c -1 (a lot of example code shows @c < @c 1
      comparisons, but we specifically test for @c -1 because the documentation
      clearly states @c -1.  This is important because a system that can support an
      extremely high number of socket handles might, in theory, assign handles with
      values that get interpreted as negative integers, and so less-than-zero tests
      would result in dropped packets or dropped sockets (any such socket code that
      allocates such handles obviously must not ever allocate @c -1 since this
      would definitely be misinterpreted as an error).
 
      If rc is not @c -1, then it is simply returned as is.
 
      If n is nonzero and rc is 0, then n will override errno.  (This option is
      provided to accomodate the few socket library functions that return values
      that are never errors, and expect the developer to rely on other means of
      detecting whether an error occurred.  This is an example of where Object
      Oriented Programming is helpful in making things better.)
      @returns Original value of @c rc (if no exceptions were thrown)
      *///=========================================================================
      const int __rc_check(
      /// Return code
      const int rc,
      /// Override @c errno (if not 0)
      const int n = 0,
      /// Exception handling flags (see @ref rex::REX_FLAGS for details)
      const int flags = rex::rex::REX_FLAGS::REX_DEFAULT) {
        if (rc == -1 || (rc == 0 && n != 0)) {
          const int socket_errno = n == 0 ? errno : n; // If "n" is not zero, use it instead
          if (__debug) debug("__rc_check(" + std::to_string(rc) + ", " + std::to_string(n) + ", " + std::to_string(flags) + ") throwing exception (errno=" + std::to_string(socket_errno) + ")"); // TODO: Remove this
          randolf::rex::mk_exception("", socket_errno, flags); // This function doesn't return (this code ends here)
        } // -x- if rc -x-
        return rc;
      }; // -x- int __rc_check -x-
 
      /*======================================================================*//**
      Similar to @ref __rc_check(), but specialized for handling OpenSSL return
      codes.
      *///=========================================================================
      const int __rc_check_tls(
      /// Return code (from OpenSSL's API functions)
      const int rc) {
        if (rc <= 0) {
          if (__debug) debug("__rc_check_tls(" + std::to_string(rc) + ") throwing exception"); // TODO: Remove this
          randolf::rex::mk_exception("", SSL_get_error(__tls_fd, rc), rex::rex::REX_FLAGS::REX_TLS); // This function doesn't return (this code ends here)
        } // -x- if rc -x-
        return rc;
      }; // -x- int __rc_check -x-
 
      /*======================================================================*//**
      Internal function that opens the socket.  This is used by the constructors
      and their accompanying socket() methods.
      
      Throws randolf::rex::xEALREADY exception if the socket is already open to
      prevent multiple calls to @c open, which can be particularly problematic if
      any of the additional function calls specify different parameters -- this
      helps developer(s) to avoid unexpected results if they're inadvertently using
      the same rsocket object when they intend to use different rsocket objects.
      *///=========================================================================
      void __socket(
      /// Communication domain; usually one of:@n
      /// AF_INET (IPv4)@n
      /// AF_INET6 (IPv6)@n
      /// AF_UNIX (UNIX domain sockets)
      const int family,
      /// Communication semantics; usually one of:@n
      /// SOCK_STREAM (common for TCP)@n
      /// SOCK_DGRAM (common for UDP)
      const int type,
      /// Network protocol; usually one of:@n
      /// IPPROTO_TCP@n
      /// IPPROTO_UDP@n
      /// IPPROTO_IP
      const int protocol) {
        if (__debug) debug("socket(" + std::to_string(family)
                         + ", " + std::to_string(type)
                         + ", " + std::to_string(protocol)
                         + ");");
 
        // --------------------------------------------------------------------------
        // Syntax checks.
        // --------------------------------------------------------------------------
        if (__socket_open)       throw randolf::rex::xEALREADY("EALREADY: Socket is already open"); // Socket has already been opened
        if (family == AF_UNSPEC) throw randolf::rex::xEAFNOSUPPORT("EAFNOSUPPORT: AF_UNSPEC family (SO_DOMAIN) is not supported by socket()");
 
        // --------------------------------------------------------------------------
        // Build minimum parts of __socket_addr structure.
        // --------------------------------------------------------------------------
        __socket_addr.ss_family             = family;
        __socket_type                       = type;
        __socket_protocol                   = protocol;
 
        // --------------------------------------------------------------------------
        // Create new socket handle, and save it, then set internal variable to
        // indicate that the socket is open.
        // --------------------------------------------------------------------------
        __socket_fd                         = __rc_check(::socket(__socket_addr.ss_family, __socket_type, __socket_protocol));
        __socket_open                       = true;
 
      }; // -x- void __socket -x-
 
    public:
      /*======================================================================*//**
      @brief
      Instantiate an empty rsocket without actually opening a socket, and therefore
      also without throwing any exceptions (useful in header-file definitions).
 
      @details
      Instantiating an empty rsocket is particularly useful for header-file
      definitions since exceptions can't be handled outside of subroutines, and
      it's also useful for enabling debug() mode @em before setting the socket's
      configuration with one of the socket() methods; for example:
      @code{.cpp}
        randolf::rsocket r; // Empty rsocket (empty / incomplete initialization)
        r.debug(true);      // Enable debug mode
        r.socket(...);      // Required to complete rsocket initialization
      @endcode
 
      @par Notes
 
      The built-in defaults, when not provided, are as follows ("family" is also
      known as the "communication domain"):
         - @c family   = AF_INET
         - @c type     = SOCK_STREAM
         - @c protocol = PF_UNSPEC
 
      You will need to use one of the socket(...) methods to specify socket details
      after defining rsocket objects with empty constructors so that you can catch
      runtime exceptions.  (This also provides you with an option to enable debug
      mode during runtime prior to attempting to open an rsocket.)
 
      @par Examples
 
      @code{.cpp}
        #include <iostream> // std::cout, std::cerr, std::endl, etc.
        #include <randolf/rex>
        #include <randolf/rsocket>
 
        randolf::rsocket r; //   <-- Empty rsocket initialization (no exceptions)
 
        int main(int argc, char *argv[]) {
          try {
            r.socket(AF_INET, SOCK_STREAM, IPPROTO_TCP); //   <-- Required to complete rsocket initialization
            r.setsockopt(SOL_SOCKET, SO_REUSEADDR, true);
            // ... other socket I/O operations
            r.close();
          } catch (const randolf::rex::xALL e) {
            std::cerr << "Socket exception: " << e.what() << std::endl;
            return EXIT_FAILURE;
          } catch (const std::exception e) {
            std::cerr << "Other exception: " << e.what() << std::endl;
            return EXIT_FAILURE;
          }
          return EXIT_SUCCESS;
        } // -x- int main -x-
      @endcode
      @see rsocket()
      @see socket()
      @see socket_family()
      @see socket_fd()
      @see socket_protocol()
      @see socket_type()
      @qualifier TLS
      *///=========================================================================
      rsocket() noexcept {}; // -x- constructor rsocket -x-
 
      /*======================================================================*//**
      @brief
      Instantiate an rsocket based on a minimal subset of the settings in the
      specified rsocket (using it as a template), without actually opening a
      socket, and therefore also without throwing any exceptions.
 
      @note
      This constructor does not suffice as a full clone()-like operation, and is
      minimal because it's used internally by the @ref accept() and @ref accept4()
      methods.
 
      Details that are absorbed from the template/source rsocket (which eliminates
      the need to assign, set, and configure various parameters (TLS and TLS SNI
      parameters will be copied in a passive way by default):
         - Socket family (SO_DOMAIN)
         - Socket type (SO_TYPE)
         - Socket protocol (SO_PROTOCOL)
         - TLS details (status, context {which includes loaded certificates},
           policies specified with @ref TLS_FLAGS, etc.)
         - EoL details
         - TLS context (you'll still need to call `tls_ctx(r->tls_ctx())`)
         - TLS SNI map (you'll still need to call `tls_sni(r->tls_sni())`)
 
      @post
      The TLS Context will not be initialized because it needs a real socket to
      draw from.  If using TLS, you'll need to use the @ref tls() method after
      the underlying socket has been initiated.
 
      When @c flag_create_socket is set to FALSE, no exceptions will be thrown.
 
      @see rsocket()
      @see socket()
      @see socket_family()
      @see socket_fd()
      @see socket_protocol()
      @see socket_type()
      @qualifier TLS
      *///=========================================================================
      rsocket(
      /// Source rsocket object to use as a template to absorb settings from
      const rsocket* rtemplate,
      /// TRUE = create a new socket handle (default)@n
      /// FALSE = don't create a new socket because a new one will be assigned or
      /// created later (all variants of the @ref accept() methods do this)
      const bool flag_create_socket = true) {
 
        // --------------------------------------------------------------------------
        // General socket variables.
        // --------------------------------------------------------------------------
        if (flag_create_socket) {
          __socket(rtemplate->__socket_addr.ss_family,
                   rtemplate->__socket_type,
                   rtemplate->__socket_protocol);
        } else { // !flag_create_socket
          __socket_addr.ss_family   = rtemplate->__socket_addr.ss_family;
          __socket_type             = rtemplate->__socket_type;
          __socket_protocol         = rtemplate->__socket_protocol;
        } // -x- if flag_create_socket -x-
        __name = rtemplate->__name;
 
        // --------------------------------------------------------------------------
        // TLS and SNI settings, but not whether TLS is enabled.
        // --------------------------------------------------------------------------
        __tls_ctx = rtemplate->__tls_ctx;
        __tls_sni = rtemplate->__tls_sni;
 
        // --------------------------------------------------------------------------
        // EoL variables.
        // --------------------------------------------------------------------------
        __eol.assign(                 rtemplate->__eol); // Copy source std::string's contents (not a reference)
        __eol_fix_printf            = rtemplate->__eol_fix_printf;
 
      }; // -x- constructor rsocket -x-
 
      /*======================================================================*//**
      @brief
      Instantiate an rsocket with IP/host address and [optional] port number.
 
      This is either the endpoint that our underlying socket will be connecting to,
      or it's the local address of the server daemon that our socket will listen()
      to and accept() inbound connections from.
 
      @par Notes
 
      The built-in defaults, when not provided, are as follows ("family" is also
      known as the "communication domain"):
         - @c family   = AF_INET
         - @c type     = SOCK_STREAM
         - @c protocol = PF_UNSPEC
 
      The socket() methods do the same work as the constructors with matching
      arguments, and are provided as convenience methods intended to augment
      empty rsocket constructors used in header files, but do require an address to
      be specified (for protocols that need port numbers, such as TCP or UDP, a
      "port" number also needs to be specified since the default port 0 will result
      in the dynamic allocation of a port number by the system).
 
      For UNIX domain sockets use family AF_UNIX, type SOCK_STREAM, and protocol
      IPPROTO_IP when instantiating or opening an rsocket.
 
      @par Examples
 
      @code{.cpp}
        #include <iostream> // std::cout, std::cerr, std::endl, etc.
        #include <randolf/rex>
        #include <randolf/rsocket>
 
        int main(int argc, char *argv[]) {
          try {
            randolf::rsocket r(AF_INET, SOCK_STREAM, IPPROTO_TCP); //   <-- Same as socket() method
            r.setsockopt(SOL_SOCKET, SO_REUSEADDR, true);
            r.bind("127.0.0.1", 32768);
            // ... other socket I/O operations
            r.close();
          } catch (const randolf::rex::xALL e) {
            std::cerr << "Socket exception: " << e.what() << std::endl;
            return EXIT_FAILURE;
          } catch (const std::exception e) {
            std::cerr << "Other exception: " << e.what() << std::endl;
            return EXIT_FAILURE;
          }
          return EXIT_SUCCESS;
        } // -x- int main -x-
      @endcode
 
      @throws randolf::rex::xEACCES Elevated access is needed to open this socket
      @throws randolf::rex::xEAFNOSUPPORT Address family not implemented/supported
      @throws randolf::rex::xEINVAL Protocal family invalid or not available
      @throws randolf::rex::xEINVAL Invalid flags in type
      @throws randolf::rex::xEMFILE Per-process maximum open files limit reached
      @throws randolf::rex::xENFILE System-wide maximum open files limit reached
      @throws randolf::rex::xENOBUFS Insufficient memory
      @throws randolf::rex::xENOMEM Insufficient memory
      @throws randolf::rex::xEPROTONOSUPPORT Specified `type` or `protocol` is not
              supported within the specified family (a.k.a., communication domain)
      @see rsocket()
      @see socket()
      @qualifier TLS
      *///=========================================================================
      rsocket(
      /// Communication domain; usually one of:@n
      /// AF_INET (IPv4)@n
      /// AF_INET6 (IPv6)@n
      /// AF_UNIX (UNIX domain sockets)
      const int family,
      /// Communication semantics; usually one of:@n
      /// SOCK_STREAM (common for TCP)@n
      /// SOCK_DGRAM (common for UDP)
      const int type = SOCK_STREAM,
      /// Network protocol; usually one of:@n
      /// IPPROTO_TCP@n
      /// IPPROTO_UDP@n
      /// IPPROTO_IP@n
      /// PF_UNSPEC (auto-detect)
      const int protocol = PF_UNSPEC) {
        __socket(family, type, protocol);
      }; // -x- constructor rsocket -x-
 
      /*======================================================================*//**
      @brief
      Destructor, which closes any underlying sockets, frees any TLS structures
      that were allocated by OpenSSL, and performs any other necessary clean-up
      before finally copying the I/O statistics to a designated structure (if one
      was specified with the @ref net_io_final() method).
      @attention
      Developers should take care to check that the @ref rsocket_io::is_final flag
      is set to @c TRUE prior to relying on the results of the @ref rsocket_io data
      since there's no guarantee that the destructor will necessarily be executed
      in a timely manner (this flag is set last, after all other statistics are
      copied into the structure while in a mutex-locked state).
      @see net_io_final()
      @qualifier TLS
      *///=========================================================================
      ~rsocket() noexcept {
 
        // --------------------------------------------------------------------------
        // Debug.
        // --------------------------------------------------------------------------
        if (__debug) {
          debug("destructor(socket{0x" + randolf::rtools::to_hex(__socket_fd) + "}"
              + ");");
          debug(false); // Disable debug mode (might trigger extra clean-up in future)
        } // -x- if _debug -x-
 
        // --------------------------------------------------------------------------
        // Free memory and resources and close handles that need to be freed/closed.
        // --------------------------------------------------------------------------
        if (__tls_fd        != nullptr)     SSL_free(__tls_fd);
//        if (__tls_sni       != nullptr)     tls_sni(nullptr); // Remove any SNI callbacks // WE DON'T NEED THIS
//        if (__tls_ctx       != nullptr) SSL_CTX_free(__tls_ctx); // TODO:  Research using SSL_up_ref(__tls_ctx)
        if (__socket_fd     !=       0)     ::close(__socket_fd); // POSIX close() is ensured with ::close()
        if (__buffer_bam    != nullptr)     free(__buffer_bam); // Release the rring_bam structure
        if (__buffer        != nullptr)     delete __buffer; // Release the rring buffer
 
        // --------------------------------------------------------------------------
        // Copy statistics to final location.  (We do this last in case there's an
        // issue with locking; there shouldn't be, but if there is then at least we
        // already we're not inadvertently hanging on to resources at this point that
        // need to be freed/closed anyway.)
        // --------------------------------------------------------------------------
        if (__io_final_addr != nullptr) {
          __io_final_addr->lock();
          __io_final_addr->bytes_rx = __bytes_rx;
          __io_final_addr->bytes_tx = __bytes_tx;
                      // ->bytes_xx = <bytes in buffer; these are lost bytes that should be subtracted from __bytes_rx>
          __io_final_addr->crypt_rx = __crypt_rx;
          __io_final_addr->crypt_tx = __crypt_tx;
                      // ->crypt_xx = <bytes in buffer; these are lost bytes that should be subtracted from __crypt_rx>
          __io_final_addr->is_final = true;
          __io_final_addr->unlock();
        } // -x- if __io_final_addr -x-
 
      }; // -x- destructor ~rsocket -x-
 
      /*======================================================================*//**
      @brief
      Accept new [inbound] socket connetions.  (This is typically used in a loop.)
 
      @pre
      The resulting rsocket object is created before the actual call to the @c
      accept() function.
 
      @note
      The @ref rsocket_mux class provides methods that support poll(), ppoll(),
      select(), and accept()/accept4() when using multiple sockets.
 
      @post
      To prevent resource leaks, the resulting rsocket needs to be deleted after
      it's no longer needed.
 
      @throws randolf::rex::xEBADF The underlying socket is not open
      @throws randolf::rex::xECONNABORTED The connection was aborted
      @throws randolf::rex::xEFAULT Address structure/memory is not in a writable
              part of the user address space
      @throws randolf::rex::xEHOSTDOWN Host is down or its network is disconnected
      @throws randolf::rex::xEHOSTUNREACH No route to host
      @throws randolf::rex::xEINTR Interrupted by a signal
      @throws randolf::rex::xEINVAL Socket is not in @ref listen() mode or the
              length of the address is invalid
      @throws randolf::rex::xEMFILE Per-process maximum open files limit reached
      @throws randolf::rex::xENETDOWN Network is disconnected or router is down
      @throws randolf::rex::xENETUNREACH No route to network
      @throws randolf::rex::xENFILE System-wide maximum open files limit reached
      @throws randolf::rex::xENOBUFS Insufficient memory
      @throws randolf::rex::xENOMEM Insufficient memory
      @throws randolf::rex::xENONET Requested host is not reachable on the network
      @throws randolf::rex::xENOPROTOOPT Either the level or the specified optname
              is not supported
      @throws randolf::rex::xENOSR System ran out of stream resources
      @throws randolf::rex::xENOTSOCK Underlying socket file descriptor (handle)
              doesn't refer to a socket
      @throws randolf::rex::xEOPNOTSUPP Underlying socket is no of type SOCK_STREAM
      @throws randolf::rex::xEPERM Connection forbidden/denied by firewall rules
      @throws randolf::rex::xEPROTO Protocol error
      @throws randolf::rex::xEPROTONOSUPPORT Specified `type` or `protocol` is not
              supported within the specified family (a.k.a., communication domain)
      @throws randolf::rex::xERESTARTSYS Used in back-end tracing to indicate that
              a system call is restartable and can be intercepted-and-redirected
              (there is no need to catch this exception unless you are an advanced
              developer, in which case you likely still won't need to catch it in
              code at this level)
      @throws randolf::rex::xESOCKTNOSUPPORT Specified socket `type` is not
              supported within the specified family (a.k.a., communication domain)
      @throws randolf::rex::xETIMEDOUT Timeout period elapsed
      @throws randolf::rex::xEWOULDBLOCK The underlying socket is non-blocking and
              no inbound connections are waiting
 
      @returns Newly-created rsocket object representing the connection received
      @see accept_sp()
      @see accept4()
      @see accept4_sp()
      @see listen
      @qualifier POSIX
      @qualifier TLS
      *///=========================================================================
      rsocket* accept() {
        if (__debug) debug("accept(socket{0x" + randolf::rtools::to_hex(__socket_fd) + "}"
                         + ");");
 
        // --------------------------------------------------------------------------
        // Pre-allocate new rsocket to reduce CPU-cycle consumption after accepting a
        // new incoming connection.
        // --------------------------------------------------------------------------
        __tls_new_endpoint = new rsocket(this, false);
 
        // --------------------------------------------------------------------------
        // Wait for incoming connection, and update internal flags in client rsocket.
        // --------------------------------------------------------------------------
        __tls_new_endpoint->__socket_fd        = ::accept(__socket_fd, (sockaddr*)&__tls_new_endpoint->__socket_addr, &__tls_new_endpoint->__socket_addr_size);
        if (__tls_new_endpoint->__socket_fd == -1) {
          delete __tls_new_endpoint; // Memory management
          //__tls_new_endpoint = nullptr;
          __rc_check(-1); // This part throws the exception
        } // -x- if rc -x-
        __tls_new_endpoint->__socket_open      = true;
        __tls_new_endpoint->__socket_connected = true;
 
        // --------------------------------------------------------------------------
        // Perform TLS accept() as well, but only if TLS is enabled.
        //
        // TODO:  Add TLS_AUTO_DETECT flag and implement it with this conditional:
        //    if (r->recv_char(MSG_PEEK) == (char)22) { ... enable TLS ... }
        // std::cout << "First byte: " << (int)(r->recv_char(MSG_PEEK)) << std::endl;
        // --------------------------------------------------------------------------
        if (__tls) {
          __tls_new_endpoint->tls_ctx(__tls_ctx, __tls_exclusive | __tls_ingress | __tls_egress); // | __tls_server_mode);
          __tls_new_endpoint->tls(true); // Make sure __tls_fd is configured correctly
          __rc_check_tls(SSL_accept(__tls_new_endpoint->__tls_fd));
        } // -x- if __tls -x-
 
        return __tls_new_endpoint;
      }; // -x- rsocket* accept -x-
 
      /*======================================================================*//**
      @brief
      Accept new [inbound] socket connetions.  (This is typically used in a loop.)
 
      @pre
      The resulting rsocket object is created before the actual call to the @c
      accept() function.
 
      @note
      The @ref rsocket_mux class provides methods that support poll(), ppoll(),
      select(), and accept()/accept4() when using multiple sockets.
 
      @post
      The resulting rsocket is wrapped in std::shared_ptr (a C++ smart pointer that
      aids in the prevention of resource leaks).
 
      @throws randolf::rex::xEBADF The underlying socket is not open
      @throws randolf::rex::xECONNABORTED The connection was aborted
      @throws randolf::rex::xEFAULT Address structure/memory is not in a writable
              part of the user address space
      @throws randolf::rex::xEHOSTDOWN Host is down or its network is disconnected
      @throws randolf::rex::xEHOSTUNREACH No route to host
      @throws randolf::rex::xEINTR Interrupted by a signal
      @throws randolf::rex::xEINVAL Socket is not in @ref listen() mode or the
              length of the address is invalid
      @throws randolf::rex::xEMFILE Per-process maximum open files limit reached
      @throws randolf::rex::xENETDOWN Network is disconnected or router is down
      @throws randolf::rex::xENETUNREACH No route to network
      @throws randolf::rex::xENFILE System-wide maximum open files limit reached
      @throws randolf::rex::xENOBUFS Insufficient memory
      @throws randolf::rex::xENOMEM Insufficient memory
      @throws randolf::rex::xENONET Requested host is not reachable on the network
      @throws randolf::rex::xENOPROTOOPT Either the level or the specified optname
              is not supported
      @throws randolf::rex::xENOSR System ran out of stream resources
      @throws randolf::rex::xENOTSOCK Underlying socket file descriptor (handle)
              doesn't refer to a socket
      @throws randolf::rex::xEOPNOTSUPP Underlying socket is no of type SOCK_STREAM
      @throws randolf::rex::xEPERM Connection forbidden/denied by firewall rules
      @throws randolf::rex::xEPROTO Protocol error
      @throws randolf::rex::xEPROTONOSUPPORT Specified `type` or `protocol` is not
              supported within the specified family (a.k.a., communication domain)
      @throws randolf::rex::xERESTARTSYS Used in back-end tracing to indicate that
              a system call is restartable and can be intercepted-and-redirected
              (there is no need to catch this exception unless you are an advanced
              developer, in which case you likely still won't need to catch it in
              code at this level)
      @throws randolf::rex::xESOCKTNOSUPPORT Specified socket `type` is not
              supported within the specified family (a.k.a., communication domain)
      @throws randolf::rex::xETIMEDOUT Timeout period elapsed
      @throws randolf::rex::xEWOULDBLOCK The underlying socket is non-blocking and
              no inbound connections are waiting
 
      @returns Newly-created rsocket object representing the connection received,
               wrapped in std::shared_ptr (a C++ smart pointer)
      @see accept()
      @see accept4()
      @see accept4_sp()
      @see listen
      @qualifier TLS
      *///=========================================================================
      std::shared_ptr<rsocket> accept_sp() {
        if (__debug) debug("accept_sp(socket{0x" + randolf::rtools::to_hex(__socket_fd) + "}"
                         + ");");
 
        // --------------------------------------------------------------------------
        // Pre-allocate new rsocket to reduce CPU-cycle consumption after accepting a
        // new incoming connection.
        // --------------------------------------------------------------------------
        std::shared_ptr<rsocket> r = std::make_shared<rsocket>(this, false);
        __tls_new_endpoint         = r.get(); // The SNI callback needs this
 
        // --------------------------------------------------------------------------
        // Wait for incoming connection, and update internal flags in client rsocket.
        // --------------------------------------------------------------------------
        r->__socket_fd        = __rc_check(::accept(__socket_fd, (sockaddr*)&r->__socket_addr, &r->__socket_addr_size));
        r->__socket_open      = true;
        r->__socket_connected = true;
 
        // --------------------------------------------------------------------------
        // Perform TLS accept() as well, but only if TLS is enabled.
        //
        // TODO:  Add TLS_AUTO_DETECT flag and implement it with this conditional:
        //    if (r->recv_char(MSG_PEEK) == (char)22) { ... enable TLS ... }
        // std::cout << "First byte: " << (int)(r->recv_char(MSG_PEEK)) << std::endl;
        // --------------------------------------------------------------------------
        if (__tls) { // Perform TLS accept() as well, but only if TLS is enabled
          r->tls_ctx(__tls_ctx, __tls_exclusive | __tls_ingress | __tls_egress); // | __tls_server_mode);
          r->tls(true); // Make sure __tls_fd is configured correctly
          __rc_check_tls(SSL_accept(r->__tls_fd));
        } // -x- if __tls -x-
 
        return r;
      }; // -x- std::shared_ptr<rsocket> accept_sp -x-
 
      /*======================================================================*//**
      @brief
      Accept new [inbound] socket connetions, with socket flags specified.  (This
      is typically used in a loop.)
 
      @pre
      The resulting rsocket object is created before the actual call to the @c
      accept4() function.
 
      @note
      The @ref rsocket_mux class provides methods that support poll(), ppoll(),
      select(), and accept()/accept4() when using multiple sockets.
 
      @post
      To prevent resource leaks, the resulting rsocket needs to be deleted after
      it's no longer needed.
 
      @throws randolf::rex::xEBADF The underlying socket is not open
      @throws randolf::rex::xECONNABORTED The connection was aborted
      @throws randolf::rex::xEFAULT Address structure/memory is not in a writable
              part of the user address space
      @throws randolf::rex::xEHOSTDOWN Host is down or its network is disconnected
      @throws randolf::rex::xEHOSTUNREACH No route to host
      @throws randolf::rex::xEINTR Interrupted by a signal
      @throws randolf::rex::xEINVAL Socket is not in @ref listen() mode or the
              length of the address is invalid
      @throws randolf::rex::xEINVAL Invalid value in flags
      @throws randolf::rex::xEMFILE Per-process maximum open files limit reached
      @throws randolf::rex::xENETDOWN Network is disconnected or router is down
      @throws randolf::rex::xENETUNREACH No route to network
      @throws randolf::rex::xENFILE System-wide maximum open files limit reached
      @throws randolf::rex::xENOBUFS Insufficient memory
      @throws randolf::rex::xENOMEM Insufficient memory
      @throws randolf::rex::xENONET Requested host is not reachable on the network
      @throws randolf::rex::xENOPROTOOPT Either the level or the specified optname
              is not supported
      @throws randolf::rex::xENOSR System ran out of stream resources
      @throws randolf::rex::xENOTSOCK Underlying socket file descriptor (handle)
              doesn't refer to a socket
      @throws randolf::rex::xEOPNOTSUPP Underlying socket is no of type SOCK_STREAM
      @throws randolf::rex::xEPERM Connection forbidden/denied by firewall rules
      @throws randolf::rex::xEPROTO Protocol error
      @throws randolf::rex::xEPROTONOSUPPORT Specified `type` or `protocol` is not
              supported within the specified family (a.k.a., communication domain)
      @throws randolf::rex::xERESTARTSYS Used in back-end tracing to indicate that
              a system call is restartable and can be intercepted-and-redirected
              (there is no need to catch this exception unless you are an advanced
              developer, in which case you likely still won't need to catch it in
              code at this level)
      @throws randolf::rex::xESOCKTNOSUPPORT Specified socket `type` is not
              supported within the specified family (a.k.a., communication domain)
      @throws randolf::rex::xETIMEDOUT Timeout period elapsed
      @throws randolf::rex::xEWOULDBLOCK The underlying socket is non-blocking and
              no inbound connections are waiting
 
      @returns Newly-created rsocket object representing the connection received
      @see accept()
      @see accept_sp()
      @see accept4_sp()
      @see listen
      @qualifier POSIX
      @qualifier TLS
      *///=========================================================================
      rsocket* accept4(
      /// SOCK_NONBLOCK@n SOCK_CLOEXEC
      const int posix_flags = 0) {
        if (__debug) debug("accept4(socket{0x" + randolf::rtools::to_hex(__socket_fd) + "}"
                         + ", " + std::to_string(posix_flags)
                         + ");");
 
        // --------------------------------------------------------------------------
        // Pre-allocate new rsocket to reduce CPU-cycle consumption after accepting a
        // new incoming connection.
        // --------------------------------------------------------------------------
        rsocket* __tls_new_endpoint = new rsocket(this, false);
 
        // --------------------------------------------------------------------------
        // Wait for incoming connection, and update internal flags in client rsocket.
        // --------------------------------------------------------------------------
        __tls_new_endpoint->__socket_fd        = ::accept4(__socket_fd, (sockaddr*)&__tls_new_endpoint->__socket_addr, &__tls_new_endpoint->__socket_addr_size, posix_flags);
        if (__tls_new_endpoint->__socket_fd == -1) {
          delete __tls_new_endpoint; // Memory management
          __rc_check(-1); // This part throws the exception
        } // -x- if rc -x-
        __tls_new_endpoint->__socket_open      = true;
        __tls_new_endpoint->__socket_connected = true;
 
        // --------------------------------------------------------------------------
        // Perform TLS accept() as well, but only if TLS is enabled.
        //
        // TODO:  Add TLS_AUTO_DETECT flag and implement it with this conditional:
        //    if (r->recv_char(MSG_PEEK) == (char)22) { ... enable TLS ... }
        // std::cout << "First byte: " << (int)(r->recv_char(MSG_PEEK)) << std::endl;
        // --------------------------------------------------------------------------
        if (__tls) { // Perform TLS accept() as well, but only if TLS is enabled
          __tls_new_endpoint->tls_ctx(__tls_ctx, __tls_exclusive | __tls_ingress | __tls_egress); // | __tls_server_mode);
          __tls_new_endpoint->tls(true); // Make sure __tls_fd is configured correctly
          __rc_check_tls(SSL_accept(__tls_new_endpoint->__tls_fd));
        } // -x- if __tls -x-
 
        return __tls_new_endpoint;
      }; // -x- rsocket* accept4 -x-
 
      /*======================================================================*//**
      @brief
      Accept new [inbound] socket connetions, with socket flags specified.  (This
      is typically used in a loop.)
 
      @pre
      The resulting rsocket object is created before the actual call to the @c
      accept4() function.
 
      @note
      The @ref rsocket_mux class provides methods that support poll(), ppoll(),
      select(), and accept()/accept4() when using multiple sockets.
 
      @post
      The resulting rsocket is wrapped in std::shared_ptr (a C++ smart pointer that
      aids in the prevention of resource leaks).
 
      @throws randolf::rex::xEBADF The underlying socket is not open
      @throws randolf::rex::xECONNABORTED The connection was aborted
      @throws randolf::rex::xEFAULT Address structure/memory is not in a writable
              part of the user address space
      @throws randolf::rex::xEHOSTDOWN Host is down or its network is disconnected
      @throws randolf::rex::xEHOSTUNREACH No route to host
      @throws randolf::rex::xEINTR Interrupted by a signal
      @throws randolf::rex::xEINVAL Socket is not in @ref listen() mode or the
              length of the address is invalid
      @throws randolf::rex::xEINVAL Invalid value in flags
      @throws randolf::rex::xEMFILE Per-process maximum open files limit reached
      @throws randolf::rex::xENETDOWN Network is disconnected or router is down
      @throws randolf::rex::xENETUNREACH No route to network
      @throws randolf::rex::xENFILE System-wide maximum open files limit reached
      @throws randolf::rex::xENOBUFS Insufficient memory
      @throws randolf::rex::xENOMEM Insufficient memory
      @throws randolf::rex::xENONET Requested host is not reachable on the network
      @throws randolf::rex::xENOPROTOOPT Either the level or the specified optname
              is not supported
      @throws randolf::rex::xENOSR System ran out of stream resources
      @throws randolf::rex::xENOTSOCK Underlying socket file descriptor (handle)
              doesn't refer to a socket
      @throws randolf::rex::xEOPNOTSUPP Underlying socket is no of type SOCK_STREAM
      @throws randolf::rex::xEPERM Connection forbidden/denied by firewall rules
      @throws randolf::rex::xEPROTO Protocol error
      @throws randolf::rex::xEPROTONOSUPPORT Specified `type` or `protocol` is not
              supported within the specified family (a.k.a., communication domain)
      @throws randolf::rex::xERESTARTSYS Used in back-end tracing to indicate that
              a system call is restartable and can be intercepted-and-redirected
              (there is no need to catch this exception unless you are an advanced
              developer, in which case you likely still won't need to catch it in
              code at this level)
      @throws randolf::rex::xESOCKTNOSUPPORT Specified socket `type` is not
              supported within the specified family (a.k.a., communication domain)
      @throws randolf::rex::xETIMEDOUT Timeout period elapsed
      @throws randolf::rex::xEWOULDBLOCK The underlying socket is non-blocking and
              no inbound connections are waiting
 
      @returns Newly-created rsocket object representing the connection received,
               wrapped in std::shared_ptr (a C++ smart pointer)
      @see accept()
      @see accept_sp()
      @see accept4()
      @see listen
      @qualifier TLS
      *///=========================================================================
      std::shared_ptr<rsocket> accept4_sp(
      /// SOCK_NONBLOCK@n SOCK_CLOEXEC
      const int posix_flags = 0) {
        if (__debug) debug("accept4_sp(socket{0x" + randolf::rtools::to_hex(__socket_fd) + "}"
                         + ", " + std::to_string(posix_flags)
                         + ");");
 
        // --------------------------------------------------------------------------
        // Pre-allocate new rsocket to reduce CPU-cycle consumption after accepting a
        // new incoming connection.
        // --------------------------------------------------------------------------
        std::shared_ptr<rsocket> r = std::make_shared<rsocket>(this, false);
        __tls_new_endpoint         = r.get(); // The SNI callback needs this
 
        // --------------------------------------------------------------------------
        // Wait for incoming connection, and update internal flags in client rsocket.
        // --------------------------------------------------------------------------
        r->__socket_fd        = __rc_check(::accept4(__socket_fd, (sockaddr*)&r->__socket_addr, &r->__socket_addr_size, posix_flags));
        r->__socket_open      = true;
        r->__socket_connected = true;
 
        // --------------------------------------------------------------------------
        // Perform TLS accept() as well, but only if TLS is enabled.
        //
        // TODO:  Add TLS_AUTO_DETECT flag and implement it with this conditional:
        //    if (r->recv_char(MSG_PEEK) == (char)22) { ... enable TLS ... }
        // std::cout << "First byte: " << (int)(r->recv_char(MSG_PEEK)) << std::endl;
        // --------------------------------------------------------------------------
        if (__tls) { // Perform TLS accept() as well, but only if TLS is enabled
          r->tls_ctx(__tls_ctx, __tls_exclusive | __tls_ingress | __tls_egress); // | __tls_server_mode);
          r->tls(true); // Make sure __tls_fd is configured correctly
          __rc_check_tls(SSL_accept(r->__tls_fd));
        } // -x- if __tls -x-
//        if (__tls_ctx != nullptr) { r->tls(true); r->__tls = (bool)__tls; } // Make sure __tls_fd is allocated appropriately
 
        return r;
      }; // -x- std::shared_ptr<rsocket> accept4_sp -x-
 
      /*======================================================================*//**
      @brief
      Override the default @ref listen backlog for this rsocket.
 
      @note
      The default backlog is SOMAXCONN (4096 on Linux, and 128 on older systems).
 
      @returns The same rsocket object so as to facilitate stacking
      @see listen
      @qualifier TLS
      *///=========================================================================
      rsocket* backlog(
      /// Backlog queue size (0 = use SOMAXCONN, which is the system default of
      /// 4096 on Linux, and 128 on older systems)
      int backlog = 0) noexcept {
        __socket_backlog = backlog == 0 ? SOMAXCONN : backlog;
        return this;
      }; // -x- rsocket* backlog -x-
 
      /*======================================================================*//**
      @brief
      Find out what this rsocket's default listen backlog is.
      @returns The default listen backlog
      @see listen
      @qualifier TLS
      *///=========================================================================
      int backlog() noexcept {
        return __socket_backlog;
      }; // -x- int backlog -x-
 
      /*======================================================================*//**
      @brief
      Bind this socket to the specified network address (and port number if the
      address family utilizes port numbers {e.g., TCP or UDP}).  This is mostly
      used for server deamons, but can also be used to control the address from
      which the local host will make an outbound connection via the @ref connect()
      method (this bound address is the address from which the endpoint will
      recieve your connection).
 
      @throws randolf::rex::xEACCES If the port number is below or equal to 1024
              (or 1023 on some Operating Systems that test only for below 1024) in
              the absence of elevated access or the absence of a capability flag
              having been set
      @throws randolf::rex::xEACCES If binding to an interface on systems that
              require elevated access for direct interface binding in absence of
              said elevated access
      @throws randolf::rex::xEADDRINUSE Address and/or port number already in use
      @throws randolf::rex::xEADDRNOTAVAIL The interface doesn't exist or the
              address is not available on any local interface
      @throws randolf::rex::xEBADF The underlying socket is not open
      @throws randolf::rex::xEFAULT Address structure/memory is not in a writable
              part of the user address space
      @throws randolf::rex::xEINVAL Socket is already bound
      @throws randolf::rex::xEINVAL Address length is incorrect, or address is not
              valid for this socket's family (a.k.a., communication domain)
      @throws randolf::rex::xENOMEM Insufficient memory
      @throws randolf::rex::xENOTSOCK Underlying socket file descriptor (handle)
              doesn't refer to a socket
      @n@n
      <b>The following exceptions are specific to AF_UNIX family sockets...</b>
      @throws randolf::rex::xEACCES Write permission or search permission denied
              on a component of the path prefix (@c AF_UNIX family)
      @throws randolf::rex::xELOOP Too many symbolic links encountered while
              resolving address (@c AF_UNIX family)
      @throws randolf::rex::xENAMETOOLONG Address is too long (@c AF_UNIX family)
      @throws randolf::rex::xENOENT One of the path's directory components doesn't
              exist (@c AF_UNIX family)
      @throws randolf::rex::xENOTDIR One of the path's diretory components is not a
              directory (@c AF_UNIX family)
      @throws randolf::rex::xEROFS Read-only file system (@c AF_UNIX family)
 
      @returns The same rsocket object so as to facilitate stacking
      @see bind(std::string, int)
      @see connect
      @see listen
      @qualifier POSIX
      @qualifier TLS
      *///=========================================================================
      rsocket* bind(
      /// Socket address structure
      const struct sockaddr* addr,
      /// Length of socket structure
      const socklen_t addrlen = sizeof(sockaddr)) {
        if (__debug) debug("bind(socket{0x" + randolf::rtools::to_hex(__socket_fd) + "}"
                         + ", <sockaddr*>"
                         + ", size=" + std::to_string(addrlen)
                         + ");");
        if (addrlen > sizeof(sockaddr_storage)) randolf::rex::mk_exception("addlen is too large for bind()", EINVAL);
        __rc_check(::bind(__socket_fd, addr, addrlen));
        std::memcpy(&__socket_addr, addr, addrlen); // No errors were returned by bind(), so now we'll copy addr to __socket_addr
        return this;
      } // -x- rsocket* bind -x-
 
      //===========================================================================
      //
      // TODO:  Document usage of IP_BIND_ADDRESS_NO_PORT to support connecting
      //        from a specific IP address without losing ephemeral port selection.
      //        Notes:  https://idea.popcount.org/2014-04-03-bind-before-connect/
      //
      // TODO:  Support AF_BLUETOOTH addresses
      //        Reference:
      //          https://man7.org/linux/man-pages/man7/address_families.7.html
      //
      // TODO:  Support AF_IPX addresses
      //        Reference:
      //          https://man7.org/linux/man-pages/man7/address_families.7.html
      //
      // TODO:  Support AF_APPLETALK addresses
      //        Reference:  https://man7.org/linux/man-pages/man7/ddp.7.html
      //
      // TODO:  Support AF_PACKET addresses
      //        Reference:  https://man7.org/linux/man-pages/man7/packet.7.html
      //
      // TODO:  Support AF_X25 addresses
      //        Reference:  https://man7.org/linux/man-pages/man7/x25.7.html
      //
      // TODO:  Support AF_NETLINK addresses
      //        Reference:  https://man7.org/linux/man-pages/man7/netlink.7.html
      //
      /*======================================================================*//**
      @brief
      Bind this socket to the specified network address (and port number if the
      address family utilizes port numbers {e.g., TCP or UDP}).  This is mostly
      used for server deamons, but can also be used to control the address from
      which the local host will make an outbound connection via the @ref connect()
      method (this bound address is address from which the endpoint will recieve
      your connection).
 
      In addition to the standard IPv4 (AF_INET family) and IPv6 (AF_INET6 family)
      support, rsocket also supports a few other binding options in a manner that
      makes it easy to utilize, without having to handle special implementation
      details (because they're handled behind-the-scenese by this rsocket class).
 
      The address string supports a number of different notations and formats,
      which are documented, hereunder, with examples:
         - IPv4 addresses
         - IPv6 addresses
         - Network interfaces
         - UNIX domain sockets
 
      <hr>
      @par IPv4 address notations (address family @c AF_INET)
      Takes the form of @c x.x.x.x where each "x" represents an octet in the range
      of @c 0 through @c 255 (e.g., @c 127.0.0.1).
 
      Under a proper implenetation of TCP/IP, an IPv4 address can be abbreviated
      to fewer octets.  The following examples demonstrate this (an unabbreviated
      IPv4 address is included for completeness):
         - @c 0.0.0.1 may be abbreviated to @c 1
         - @c 4.0.0.1 may be abbrevaited to @c 4.1
         - @c 4.3.0.1 may be abbreviated to @c 4.3.1
         - @c 4.3.2.1 is not abbreviated (this is the most common usage)
 
      @par Example of binding to IPv4 localhost
 
      @code{.cpp}
        #include <iostream> // std::cout, std::cerr, std::endl, etc.
        #include <randolf/rex>
        #include <randolf/rsocket>
 
        int main(int argc, char *argv[]) {
          try {
            randolf::rsocket r(AF_INET, SOCK_STREAM, IPPROTO_TCP);
            r.bind("127.0.0.1", 32768); //   <-- You are here
            // ... other socket I/O operations
            r.close();
          } catch (const randolf::rex::xEACCES e) {
            std::cerr << "Socket bind-access exception: " << e.what() << std::endl;
            return EXIT_FAILURE;
          } catch (const randolf::rex::xALL e) {
            std::cerr << "Socket exception: " << e.what() << std::endl;
            return EXIT_FAILURE;
          } catch (const std::exception e) {
            std::cerr << "Other exception: " << e.what() << std::endl;
            return EXIT_FAILURE;
          }
          return EXIT_SUCCESS;
        } // -x- int main -x-
      @endcode
 
      @note
      Specifying the IP address of @c 0.0.0.0 will bind to all IPv4 addresses that
      are assigned to all of the host machine's network interfaces with IPv4
      bindings.
      @n@n
      Specifying the IP address of @c 127.0.0.1 (localhost) is useful for serving
      only those applications that are running on the local host and use an IPv4
      socket to communicate.
 
      <hr>
      @par IPv6 address notations (address family @c AF_INET6)
      Takes the form of @c x:x:x:x:x:x:x:x where each "x" represents a segment in
      the range of @c 0 through @c ffff in hexadecimal (e.g., `0:0:0:0:0:0:0:1`),
      or `x:x:x:x:x:x:y.y.y.y` where `y.y.y.y` represents an [unabbreviated] IPv4
      address (which merely replaces the last two IPv6 segments).
 
      Under a proper implenetation of TCP/IP, an IPv6 address can be abbreviated
      to fewer segments by using a sequence of two colons (`::`) to indicate that
      the undefined segments are @c 0 (this abbreviation can only be used once,
      and may represent segments at the beginning or end, or anywhere in between).
      The following examples demonstrate this (an unabbreviated IPv6 address is
      included for completeness):
         - `0:0:0:0:0:0:0:1` may be abbreviated to `::1`
         - `0:0:0:0:0:0:2:1` may be abbreviated to `::2:1`
         - `8:0:0:0:0:0:2:1` may be abbreviated to `8::2:1`
         - `8:7:0:0:0:0:2:1` may be abbreviated to `8:7::2:1`
         - `8:7:0:0:0:0:0:0` may be abbreviated to `8:7::`
         - `8:0:0:0:0:0:0:0` may be abbreviated to `8::`
         - `8:7:6:5:4:3:2:1` is not abbreviated
 
      @par Example of binding to IPv6 localhost
 
      @code{.cpp}
        #include <iostream> // std::cout, std::cerr, std::endl, etc.
        #include <randolf/rex>
        #include <randolf/rsocket>
 
        int main(int argc, char *argv[]) {
          try {
            randolf::rsocket r(AF_INET6, SOCK_STREAM, IPPROTO_TCP);
            r.bind("::1", 32768); //   <-- You are here
            // ... other socket I/O operations
            r.close();
          } catch (const randolf::rex::xEACCES e) {
            std::cerr << "Socket bind-access exception: " << e.what() << std::endl;
            return EXIT_FAILURE;
          } catch (const randolf::rex::xALL e) {
            std::cerr << "Socket exception: " << e.what() << std::endl;
            return EXIT_FAILURE;
          } catch (const std::exception e) {
            std::cerr << "Other exception: " << e.what() << std::endl;
            return EXIT_FAILURE;
          }
          return EXIT_SUCCESS;
        } // -x- int main -x-
      @endcode
 
      @note
      Specifying the IP address of @c :: will bind to all IPv6 addresses that are
      assigned to all of the host machine's network interfaces with IPv6 bindings.
      @n@n
      Specifying the IP address of @c ::1 (localhost) is useful for serving only
      those applications that are running on the local host and use an IPv6 socket
      to communicate.
 
      <hr>
      @par Interface address notation (address families @c AF_INET and @c AF_INET6)
      Takes the form of @c if=name where "name" represents the name of a local
      network interface.
 
      Interface binding is useful when binding to interfaces that aren't configured
      with a static IP address because they were dymamically configured via the
      Dynamic Host Configuration Protocol (DHCP) or Stateless Address Configuration
      (SLAAC), or the configuration was changed manually by an administrator and
      you don't want your software to handle such changes gracefully, even if the
      new IP address is within the scope of an entirely different CIDR.  (Changing
      between the IPv4 and IPv6 addresses is not supported, however, due to the
      fundamental differences between these two address families that includes
      differences beyond that of IP address format, although under a proper
      implementation of TCP/IP the binding should survive such changes when the IP
      address is reverted to the initial IP address family of the bound interface.)
 
      Examples of interfaces include:
        - `if=lo` typical for localhost virtual network adapter
        - `if=bond0` typical for the first bonded virtual network adapter (used in
                     failover and load-balancing network configurations)
        - `if=br0` typical for the first bridge virtual network adapter
        - `if=eth0` typical for the first ethernet network adapter
        - `if=tap0` typical for the first virtual layer 2 ethernet switch (used by
                    VPNs to extend a remote network into the local network stack)
        - `if=tun0` typical for the first virtual layer 3 ethernet tunnel (used by
                    VPNs to provide access to a remote network)
        - `if=wlo1` typical for the first wireless network adapter
 
      @par Example of binding to interface localhost
 
      @code{.cpp}
        #include <iostream> // std::cout, std::cerr, std::endl, etc.
        #include <randolf/rex>
        #include <randolf/rsocket>
 
        int main(int argc, char *argv[]) {
          try {
            randolf::rsocket r(AF_INET, SOCK_STREAM, IPPROTO_TCP);
            r.bind("if=lo", 32768); //   <-- You are here
            // ... other socket I/O operations
            r.close();
          } catch (const randolf::rex::xEACCES e) {
            std::cerr << "Socket bind-access exception: " << e.what() << std::endl;
            return EXIT_FAILURE;
          } catch (const randolf::rex::xALL e) {
            std::cerr << "Socket exception: " << e.what() << std::endl;
            return EXIT_FAILURE;
          } catch (const std::exception e) {
            std::cerr << "Other exception: " << e.what() << std::endl;
            return EXIT_FAILURE;
          }
          return EXIT_SUCCESS;
        } // -x- int main -x-
      @endcode
 
      @note
      This is not a standard feature of the POSIX bind() function.  This rsocket
      class uses the setsockopt() function behind-the-scenes to configure (enable)
      the @c SO_BINDTODEVICE option, and then the bind() function is called with
      the IPv4 address @c 0.0.0.0 if the underlying socket was initialized to the
      @c AF_INET family, or the IPv6 address @c :: if the underlying socket was
      initialized to the @c AF_INET6 family.
      @n@n
      Specifying the interface address of `if=lo` (localhost) is useful for serving
      only those applications that are running on the local host and use an IPv4 or
      IPv6 socket to communicate.
 
      <hr>
      @par UNIX Domain Sockets address-notation (address family @c AF_UNIX)
      Takes the form of @c /path where "/path" represents an absolute path on the
      local file system (the path can also be relative, in which case it doesn't
      begin with a slash (`/`) character, but extra care is needed to ensure that
      the path will actually be at its expected location).
 
      @par Example of binding to UNIX domain sockets
 
      @code{.cpp}
        #include <iostream> // std::cout, std::cerr, std::endl, etc.
        #include <randolf/rex>
        #include <randolf/rsocket>
 
        int main(int argc, char *argv[]) {
          try {
            randolf::rsocket r(AF_UNIX, SOCK_STREAM);
            r.bind("/var/run/rsocket-test-socket.tmp"); //   <-- You are here
            // ... other socket I/O operations
            r.close();
          } catch (const randolf::rex::xEACCES e) {
            std::cerr << "Socket bind-access exception: " << e.what() << std::endl;
            return EXIT_FAILURE;
          } catch (const randolf::rex::xALL e) {
            std::cerr << "Socket exception: " << e.what() << std::endl;
            return EXIT_FAILURE;
          } catch (const std::exception e) {
            std::cerr << "Other exception: " << e.what() << std::endl;
            return EXIT_FAILURE;
          }
          return EXIT_SUCCESS;
        } // -x- int main -x-
      @endcode
 
      @note
      Normal socket I/O functionality is used to exchange data with another process
      that can open the same UNIX domain socket (normally on the same host,
      although it may not be outside the realm of possibility for future Linux
      kernels to support UNIX domain sockets on remote hosts).
 
      <hr>
      @throws randolf::rex::xEACCES If the port number is below or equal to 1024
              (or 1023 on some Operating Systems that test only for below 1024) in
              the absence of elevated access or the absence of a capability flag
              having been set
      @throws randolf::rex::xEACCES If binding to an interface on systems that
              require elevated access for direct interface binding in absence of
              said elevated access
      @throws randolf::rex::xEADDRINUSE Address and/or port number already in use
      @throws randolf::rex::xEADDRNOTAVAIL The interface doesn't exist or the
              address is not available on any local interface
      @throws randolf::rex::xEBADF The underlying socket is not open
      @throws randolf::rex::xEFAULT Address structure/memory is not in a writable
              part of the user address space
      @throws randolf::rex::xEINVAL Socket is already bound
      @throws randolf::rex::xEINVAL Address length is incorrect, or address is not
              valid for this socket's family (a.k.a., communication domain)
      @throws randolf::rex::xENOMEM Insufficient memory
      @throws randolf::rex::xENOTSOCK Underlying socket file descriptor (handle)
              doesn't refer to a socket
      @n@n
      <b>The following exceptions are specific to AF_UNIX family sockets...</b>
      @throws randolf::rex::xEACCES Write permission or search permission denied
              on a component of the path prefix (@c AF_UNIX family)
      @throws randolf::rex::xELOOP Too many symbolic links encountered while
              resolving address (@c AF_UNIX family)
      @throws randolf::rex::xENAMETOOLONG Address is too long (@c AF_UNIX family)
      @throws randolf::rex::xENOENT One of the path's directory components doesn't
              exist (@c AF_UNIX family)
      @throws randolf::rex::xENOTDIR One of the path's diretory components is not a
              directory (@c AF_UNIX family)
      @throws randolf::rex::xEROFS Read-only file system (@c AF_UNIX family)
 
      @returns The same rsocket object so as to facilitate stacking
      @see bind(const struct sockaddr*, const socklen_t)
      @see connect
      @see listen
      @qualifier TLS
      *///=========================================================================
      rsocket* bind(
      /// IPv4 address, IPv6 address, hostname, UNIX domain sockets path, or specialized variant (see notes, above)
      const std::string address,
      /// TCP or UDP port number ranging 1-65535 (0 = ephemeral port; a.k.a., automatic assignment)
      const int port = 0) {
        if (__debug) debug("bind(socket{0x" + randolf::rtools::to_hex(__socket_fd) + "}"
                         + ", " + address
                         + " port=" + std::to_string(port) + (port == 0 ? " (emphemeral or not-applicable)" : "")
                         + ", size=" + std::to_string(__socket_addr_size)
                         + ");");
 
//std::cout << "   address: " << address << std::endl;
          if (address.starts_with("if=")) { // Bind to interface
// TODO:  Use family() to simplify this section of code
            struct ifreq ifr{};
            if (address.size() - 3 >= sizeof(ifr.ifr_name)) {} // Throw exception because ASCIIZ name will be too long
            address.copy(ifr.ifr_name, address.size() - 3, 3); // Copy address, excluding the "if=" portion
            __rc_check(::setsockopt(__socket_fd, SOL_SOCKET, SO_BINDTODEVICE, &ifr, sizeof(ifr)));
            // TODO:  Figure out how to use INADDR_ANY instead of 0 or :: (assuming this is even possible)
            // TODO:  Test IPv6 more (telnet doesn't seem to be able to connect, and continues to work on IPv4 address)
            __socket_addr = *mk_sockaddr_storage(__socket_addr.ss_family == AF_INET6 ? "::" : "0", port, new addrinfo{0, __socket_addr.ss_family, __socket_type, __socket_protocol});
            __rc_check(::bind(__socket_fd, (sockaddr*)&__socket_addr, __socket_addr_size));
 
//          } else if (address.starts_with("if_cidr=")) { // Bind to interface based on matching CIDR
//            // REMINDER: Update static family() method as well
// getifaddrs: https://man7.org/linux/man-pages/man3/getifaddrs.3.html
//          } else if (address.starts_with("if_mac=")) { // Bind to interface based on its physical/hardware machine address
//            // REMINDER: Update static family() method as well
//            // Resolve interface name, and then just do what if= does (above)
 
          } else {
            __socket_addr = *mk_sockaddr_storage(address, port, new addrinfo{0, __socket_addr.ss_family, __socket_type, __socket_protocol});
            __rc_check(::bind(__socket_fd, (sockaddr*)&__socket_addr, __socket_addr_size));
//            __rc_check(::bind(__socket_fd, (sockaddr*)&(__socket_addr = *mk_sockaddr_storage(address, port)), __socket_addr_size));
          }
        return this;
      } // -x- rsocket* bind -x-
 
      /*======================================================================*//**
      @brief
      Find out what buffer size is used by the various recv() methods.
      @returns Buffer size (in bytes)
      @see buffer_size(const size_t nbytes)
      @see is_buffered
      @qualifier TLS
      *///=========================================================================
      const size_t buffer_size() noexcept { return __buffer->get_size(); }; // -x- size_t buffer_size -x-
 
      /*======================================================================*//**
      @brief
      Override the default buffer size (typically 8,192 bytes) used by the various
      recv() methods.
 
      If resetting to the compiled-in default, use the buffer_size_reset() method
      instead of setting the value directly.  This ensures that future versions,
      with a different compiled-in default, will be reset to the compiled-in value.
      @exception std::overflow_error If the new size exceeds the amount of data
                                     that's already present in the ring buffer
      @returns The same rsocket object so as to facilitate stacking
      @see buffer_size
      @see buffer_size_reset
      @qualifier TLS
      *///=========================================================================
      rsocket* buffer_size(
      /// Size of the new buffer (in bytes)
      const size_t nbytes) {
        __buffer_size = nbytes;
        if (__debug) debug("buffer_size(socket{0x" + randolf::rtools::to_hex(__socket_fd) + "}"
                         + " nbytes=" + std::to_string(nbytes)
                         + ");");
        if (__buffer != nullptr) __buffer->set_size(nbytes);
        return this;
      }; // -x- rsocket* buffer_size -x-
 
      /*======================================================================*//**
      @brief
      Reset the default buffer size (typically 1024) used by the various recv()
      methods.
 
      This method is preferred for resetting to the compiled-in default instead of
      setting the value directly.  This ensures that future versions, with a
      different compiled-in default, will be reset to the compiled-in value.
      @exception std::overflow_error If the new size exceeds the amount of data
                                     that's already present in the ring buffer
      @returns The same rsocket object so as to facilitate stacking
      @see buffer_size(const size_t nbytes)
      @qualifier TLS
      *///=========================================================================
      rsocket* buffer_size_reset() {
        __buffer_size = RSOCKET_BUFFER_SIZE;
        if (__debug) debug("buffer_size_reset(socket{0x" + randolf::rtools::to_hex(__socket_fd) + "}"
                         + " nbytes=" + std::to_string(RSOCKET_BUFFER_SIZE)
                         + ");");
        if (__buffer != nullptr) __buffer->set_size(__buffer_size);
        return this;
      }; // -x- rsocket* buffer_size_reset -x-
 
      //===========================================================================
      //
      // TODO:  If family is AF_UNIX then also unlink the domain socket file.
      //
      /*======================================================================*//**
      @brief
      Close this rsocket.  (If this rsocket was already closed, then calling this
      method additional times will have no effect, and will not cause exceptions to
      be thrown.)
      @warning
      This method may throw exceptions in some circumstances, which is extremely
      rare.  If you prefer to close without having to contend with any exceptions
      (e.g., while calling close() from within a destructor), the close_passive()
      method will return an integer indicating success/failure instead of throwing
      an exception, and then you'll have to handle errno manually (which is useful
      in destructors because any error can merely be handled procedurally).
 
      @throws randolf::rex::xEBADF The underlying socket is not open
      @throws randolf::rex::xEINTR Interrupted by a signal
      @throws randolf::rex::xEIO An I/O error occurred
 
      @returns The same rsocket object so as to facilitate stacking
      @see is_closed()
      @qualifier POSIX
      @qualifier TLS
      *///=========================================================================
      rsocket* close() {
        if (__socket_open) {
          __rc_check(::close(__socket_fd));
          __socket_open = false;
        } // -x- if __socket_open -x-
        return this;
      }; // -x- rsocket* close -x-
 
      /*======================================================================*//**
      @brief
      Close this rsocket without throwing any exceptions (an error code is returned
      instead, which is useful while calling close_passive() from within a
      destructor).
      @returns 0 = success
      @returns -1 = error (errno will be set accordingly)
      @see is_closed()
      @qualifier TLS
      *///=========================================================================
      int close_passive() noexcept {
        if (__socket_open) {
          int rc = ::close(__socket_fd);
          if (rc == 0) __socket_open = false;
          return rc;
        } // -x- if __socket_open -x-
        return 0; // Indicate success (because the socket was previously closed successfully)
      }; // -x- int close_passive -x-
 
      /*======================================================================*//**
      @brief
      Connect this socket to a specific endpoint (which may differ from this
      rsocket's address that was previously configured by the @ref bind() method).
 
      @throws randolf::rex::xEADDRINUSE Address and/or port number already in use
      @throws randolf::rex::xEADDRNOTAVAIL No ephemeral ports are available for
              assignment to unbound socket
      @throws randolf::rex::xEAFNOSUPPORT Address family not implemented/supported
      @throws randolf::rex::xEAGAIN Insufficient entries in the routing cache
      @throws randolf::rex::xEALREADY Previous connection attempt not completed on
              nonblocking socket
      @throws randolf::rex::xEBADF The underlying socket is not open
      @throws randolf::rex::xECONNREFUSED Remote address is not listening for new
              connections
      @throws randolf::rex::xEFAULT Address structure/memory is not in a writable
              part of the user address space
      @throws randolf::rex::xEINPROGRESS Connection cannot be completed immediately
              on nonblocking socket (@c AF_UNIX family fails with xEAGAIN instead)
      @throws randolf::rex::xEINTR Interrupted by a signal
      @throws randolf::rex::xEISCONN Socket is already connected
      @throws randolf::rex::xENETUNREACH No route to network
      @throws randolf::rex::xENOTSOCK Underlying socket file descriptor (handle)
              doesn't refer to a socket
      @throws randolf::rex::xEPERM Connection forbidden/denied by firewall rules
      @throws randolf::rex::xEPERM Can't connect to a broadcast address when the
              socket's broadcast flag isn't enabled
      @throws randolf::rex::xEPROTOTYPE Socket type doesn't support the requested
              communications protocol (e.g., connecting a UNIX domain socket of
              type @c SOCK_STREAM to an endpoint expecting type @c SOCK_DGRAM)
      @throws randolf::rex::xETIMEDOUT Timeout period elapsed
      @n@n
      <b>The following exceptions are specific to AF_UNIX family sockets...</b>
      @throws randolf::rex::xEACCES Write permission or search permission denied
              on a component of the path prefix (@c AF_UNIX family)
      @throws randolf::rex::xEAGAIN Connection cannot be completed immediately on
              nonblocking socket (@c AF_UNIX family)
 
      @returns The same rsocket object so as to facilitate stacking
      @see tls_do_handshake()
      @qualifier POSIX
      @qualifier TLS
      *///=========================================================================
      rsocket* connect(
      /// IPv4 address, IPv6 address, hostname, or UNIX domain sockets path
      const std::string address,
      /// TCP or UDP port number ranging 1-65535 (0 = ephemeral port; a.k.a., automatic assignment)
      const int port = 0) {
        if (__debug) debug("connect(socket{0x" + randolf::rtools::to_hex(__socket_fd) + "}"
                         + ", " + address
                         + " (port=" + std::to_string(port) + ")"
                         + ", " + std::to_string(__socket_addr_size)
                         + ");");
 
        __socket_addr = *mk_sockaddr_storage(address, port, new addrinfo{0, __socket_addr.ss_family, __socket_type, __socket_protocol});
        __rc_check(::connect(__socket_fd, (sockaddr*)&__socket_addr, __socket_addr_size), 0, rex::rex::REX_FLAGS::REX_ALT_EAGAIN);
 
//        __rc_check(::connect(__socket_fd, (sockaddr*)&(__socket_addr = *mk_sockaddr_storage(address, port)), __socket_addr_size));
        __socket_connected = true;
 
        // --------------------------------------------------------------------------
        // TLS.
        // --------------------------------------------------------------------------
        if (__tls) {
          if (__debug) debug("tls_connect(socket{0x" + randolf::rtools::to_hex(__socket_fd) + "}"
                           + ");");
          __rc_check_tls(SSL_connect(__tls_fd));
        } // -x- if __tls -x-
 
        return this;
      }; // -x- rsocket* connect -x-
 
      /*======================================================================*//**
      @brief
      Find out whether debug mode is enabled.
 
      @par Threads
      This method is threadsafe.
      @returns TRUE = enabled
      @returns FALSE = not enabled
      @qualifier TLS
      *///=========================================================================
      const bool debug() noexcept { return __debug; };
 
      /*======================================================================*//**
      @brief
      Debug mode.  When debug mode is enabled, output is sent to stderr by default,
      unless a second parameter specifies a different file handle (e.g., stdout, or
      even a socket).
 
      debug(...) returns -1 if fd can't be written to (errno will be set in
      accordance with std::fprintf's behaviour since std::fprintf is used for
      writing debug output).  Normally we'd throw an exception for such errors, but
      with debug is a special case because debugging needs to be as quick and
      convenient as possible for developers.
 
      debug(...) returns -2 if writing to stderr failed when attempting to announce
      that fd can't be written to (as described above).
 
      debug(...) returns -3 if some other error occurs (e.g., internal formatting
      error {which should not happen} or memory allocation failed, in which case
      there's a more serious problem that will be causing other problems elsewhere
      anyway).
 
      Developers may add their own debug messages by using debug(std::string),
      which will only be written out if debug mode is enabled.  This same method is
      used internally, so messages will be indistinguishable from developer's
      messages.
 
      @par Threads
      This method is thread-safe.
      @returns 0 = success
      @returns -1 = error writing to stream (errno will be set accordingly)
      @returns -2 = error writing to stderr (errno will be set accordingly)
      @returns -3 = error (errno will be set accordingly)
      @qualifier TLS
      *///=========================================================================
      const int debug(
      /// TRUE = enable debug mode@n
      /// FALSE = disable debug mode (does not close any file handles)
      const bool debug_flag,
      /// File descriptor/handle to use for debug output
      std::FILE* fd = stderr) noexcept {
 
        int rc = debug_fd(fd); // Attempt to change debug handle
        if (rc != 0) return rc; // Return error id new debug handle failed
        time_t tm = std::time(nullptr);
        std::string dt(27, 0);
        dt.resize(std::strftime(dt.data(), dt.size(), "%Y-%b-%d %T %z", std::localtime(&tm)));
        try {
          if (debug_flag || __debug) std::fprintf(__debug_fd,
                       "[%s] %s: Debug mode is %s\n",
                       dt.c_str(),
                       __debug_prefix.c_str(),
                       debug_flag ? "ON" : "OFF");
        } catch (const std::system_error& e) { // Error writing to fd
          try {
            std::fprintf(stderr,
                         "[%s] %s: error writing to stream\n",
                         dt.c_str(),
                         __debug_prefix.c_str());
          } catch (const std::exception& e) {
            return -2;
          }
          return -1;
        } catch (const std::exception& e) {
          return -3;
        }
        __debug = debug_flag; // Save debug flag
 
        return 0; // Indicate success (no errors)
      }; // -x- int debug -x-
 
      /*======================================================================*//**
      @brief
      Send the specified message as debug output (as long as debug mode is enabled;
      if disabled, no debug output will be sent).
      @returns 0 = success
      @returns -1 = error writing to stream (errno will be set accordingly)
      @returns -2 = error writing to stderr (errno will be set accordingly)
      @returns -3 = error (errno will be set accordingly)
      @qualifier TLS
      *///=========================================================================
      const int debug(
      /// Debug message as an ASCIIZ string
      const char* msg) noexcept {
        return __debug ? __debug_out(std::string(msg)) : 0;
      }; // -x- int debug -x-
 
      /*======================================================================*//**
      @copydoc debug(const char*)
      @qualifier TLS
      *///=========================================================================
      const int debug(
      /// Debug message as an std::string object
      const std::string msg) noexcept {
        return __debug ? __debug_out(msg) : 0;
      }; // -x- int debug -x-
 
      /*======================================================================*//**
      @brief
      Find out which file descriptor/handle is used for debug output.
      @returns file handle/descriptor currently used for debug output
      *///=========================================================================
      const std::FILE* debug_fd() noexcept { return __debug_fd; }; // Get debug-output file handle
 
      /*======================================================================*//**
      @brief
      Specify a different file descriptor/handle to use for debug output
      @returns 0 = success
      @returns -1 = error writing to stream (errno will be set accordingly)
      @returns -2 = error writing to stderr (errno will be set accordingly)
      @returns -3 = error (errno will be set accordingly)
      *///=========================================================================
      const int debug_fd(
      /// File descriptor/handle to use for debug output
      std::FILE* fd) noexcept {          // Set debug-output file handle
        if (__debug_fd != fd) {
          debug("Current debug-output file handle unset"); // For this message, we only want to send this out if debug mode is enabled
          __debug_fd = fd; // Save new debug-output file handle
          return debug("New debug-output file handle set"); // For this message, we only want to send this out if debug mode is enabled
        } // -x- if ~fd -x-
        return 0; // Indicate success (no errors)
      }; // -x- int debug_fd -x-
 
      /*======================================================================*//**
      @brief
      Find out what the current prefix is set to that's used in debug output.
 
      This may be set at any time, including before or after enabling or disabling
      debug mode.
      @returns debug prefix string
      @qualifier TLS
      *///=========================================================================
      const std::string debug_prefix() noexcept { return __debug_prefix; }; // -x- std::string debug_prefix -x-
 
      /*======================================================================*//**
      @brief
      Change the prefix used in debug output.
      @returns The same rsocket object so as to facilitate stacking
      @qualifier TLS
      *///=========================================================================
      rsocket* debug_prefix(
      /// New debug prefix string
      const std::string prefix) noexcept {
        __debug_prefix = prefix;
        return this;
      }; // -x- std::string debug_prefix -x-
 
    private:
      /*----------------------------------------------------------------------*//**
      @brief
      Internal debug-output function.  This doesn't check __debug flag because it's
      expected that the normal debug() methods are taking care of this.
      @returns 0 = success
      @returns -1 = error writing to stream (errno will be set accordingly)
      @returns -2 = error writing to stderr (errno will be set accordingly)
      @returns -3 = error (errno will be set accordingly)
      *///-------------------------------------------------------------------------
      const int __debug_out(
      /// Debugging message
      const std::string msg) noexcept {
 
        time_t tm = std::time(nullptr);
        std::string dt(27, 0);
        dt.resize(std::strftime(dt.data(), dt.size(), "%Y-%b-%d %T %z", std::localtime(&tm)));
        try {
          std::fprintf(__debug_fd,
                       "[%s] %s: %s\n",
                       dt.c_str(),
                       __debug_prefix.c_str(),
                       msg.c_str());
        } catch (const std::system_error& e) { // Error writing to fd
          try {
            std::fprintf(stderr,
                         "[%s] %s: error writing to stream\n",
                         dt.c_str(),
                         __debug_prefix.c_str());
          } catch (const std::exception& e) {
            return -2;
          }
          return -1;
        } catch (const std::exception& e) {
          return -3;
        }
 
        return 0; // Indicate success (no errors)
      }; // -x- int __debug_out -x-
 
      // --------------------------------------------------------------------------
      // These are specialized internal debug output methods for presenting socket
      // options when they are get or set.  These methods are marked as "private"
      // because they are really aren't useful outside of internal-use contexts.
      //
      // @par Threads
      // Some of these methods are thread-safe.
      //
      // These methods are thread-safe when they don't reference structures (e.g.,
      // integer {int}, unsigned integer {u_int}, and unsigned character {u_char}).
      //
      // These methods are not necessarily thread-safe if they reference structures
      // unless those structures are defined with std::atomic, or they were
      // constructed on-the-fly as anonymous parameters.
      // --------------------------------------------------------------------------
      const int __debug_sockopt(
      /// Name of function or method
      const std::string func,
      /// The level at which the option resides; typically @c SOL_SOCKET
      const int level,
      /// The name of the option, such as @c SO_REUSEADDR, @c SO_LINGER, etc. 
      const int option,
      /// The structure that this socket option will be set to
      const int value) {
        return debug(func + randolf::rtools::to_hex(__socket_fd) + "}"
                  + ", " + std::to_string(level)
                  + ", " + std::to_string(option)
                  + ", " + std::to_string(value)
                  + ", size=" + std::to_string(sizeof(value))
                  + ");");
      }; // -x- int __debug_sockopt -x-
      const int __debug_sockopt(
      /// Name of function or method
      const std::string func,
      /// The level at which the option resides; typically @c SOL_SOCKET
      const int level,
      /// The name of the option, such as @c SO_REUSEADDR, @c SO_LINGER, etc. 
      const int option,
      /// The structure that this socket option will be set to
      const u_int value) {
        return debug(func + randolf::rtools::to_hex(__socket_fd) + "}"
                   + ", " + std::to_string(level)
                   + ", " + std::to_string(option)
                   + ", u_int{" + std::to_string(value) + "}"
                   + ", size=" + std::to_string(sizeof(value))
                   + ");");
      }; // -x- int __debug_sockopt -x-
      const int __debug_sockopt(
      /// Name of function or method
      const std::string func,
      /// The level at which the option resides; typically @c SOL_SOCKET
      const int level,
      /// The name of the option, such as @c SO_REUSEADDR, @c SO_LINGER, etc. 
      const int option,
      /// The structure that this socket option will be set to
      const u_char value) {
        return debug(func + randolf::rtools::to_hex(__socket_fd) + "}"
                   + ", " + std::to_string(level)
                   + ", " + std::to_string(option)
                   + ", u_char{" + std::to_string(value) + "}"
                   + ", size=" + std::to_string(sizeof(value))
                   + ");");
      }; // -x- int __debug_sockopt -x-
      const int __debug_sockopt(
      /// Name of function or method
      const std::string func,
      /// The level at which the option resides; typically @c SOL_SOCKET
      const int level,
      /// The name of the option, such as @c SO_REUSEADDR, @c SO_LINGER, etc. 
      const int option,
      /// The structure that this socket option will be set to
      const linger* value) {
        return debug(func + randolf::rtools::to_hex(__socket_fd) + "}"
                   + ", " + std::to_string(level)
                   + ", " + std::to_string(option)
                   + ", linger{l_onoff="  + std::to_string(value->l_onoff)
                          + ", l_linger=" + std::to_string(value->l_linger) + "}"
                   + ", " + std::to_string(sizeof(value))
                   + ");");
      }; // -x- int __debug_sockopt -x-
      const int __debug_sockopt(
      /// Name of function or method
      const std::string func,
      /// The level at which the option resides; typically @c SOL_SOCKET
      const int level,
      /// The name of the option, such as @c SO_REUSEADDR, @c SO_LINGER, etc. 
      const int option,
      /// The structure that this socket option will be set to
      const timeval* value) {
        return debug(func + randolf::rtools::to_hex(__socket_fd) + "}"
                   + ", " + std::to_string(level)
                   + ", " + std::to_string(option)
                   + ", timeval{tv_sec=" + std::to_string(value->tv_sec)
                          + ", tv_usec=" + std::to_string(value->tv_usec) + "}"
                   + ", " + std::to_string(sizeof(value))
                   + ");");
      }; // -x- int __debug_sockopt -x-
      const int __debug_sockopt(
      /// Name of function or method
      const std::string func,
      /// The level at which the option resides; typically @c SOL_SOCKET
      const int level,
      /// The name of the option, such as @c SO_REUSEADDR, @c SO_LINGER, etc. 
      const int option,
      /// The structure that this socket option will be set to
      const in_addr* value) {
        return debug(func + randolf::rtools::to_hex(__socket_fd) + "}"
                   + ", " + std::to_string(level)
                   + ", " + std::to_string(option)
                   + ", in_addr{" + std::to_string(value->s_addr) + "}"
                   + ", " + std::to_string(sizeof(value))
                   + ");");
      }; // -x- int __debug_sockopt -x-
      const int __debug_sockopt(
      /// Name of function or method
      const std::string func,
      /// The level at which the option resides; typically @c SOL_SOCKET
      const int level,
      /// The name of the option, such as @c SO_REUSEADDR, @c SO_LINGER, etc. 
      const int option,
      /// The structure that this socket option will be set to
      const ip_mreq* value) {
        return debug(func + randolf::rtools::to_hex(__socket_fd) + "}"
                   + ", " + std::to_string(level)
                   + ", " + std::to_string(option)
                   + ", ip_mreq{addr=" + std::to_string(value->imr_multiaddr.s_addr)
                          + ", iface=" + std::to_string(value->imr_interface.s_addr) + "}"
                   + ", " + std::to_string(sizeof(value))
                   + ");");
      }; // -x- int __debug_sockopt -x-
      const int __debug_sockopt(
      /// Name of function or method
      const std::string func,
      /// The level at which the option resides; typically @c SOL_SOCKET
      const int level,
      /// The name of the option, such as @c SO_REUSEADDR, @c SO_LINGER, etc. 
      const int option,
      /// The structure that this socket option will be set to
      const ip_mreq_source* value) {
        return debug(func + randolf::rtools::to_hex(__socket_fd) + "}"
                   + ", " + std::to_string(level)
                   + ", " + std::to_string(option)
                   + ", ip_mreq_source{addr=" + std::to_string(value->imr_multiaddr.s_addr)
                                + ", source=" + std::to_string(value->imr_sourceaddr.s_addr)
                                 + ", iface=" + std::to_string(value->imr_interface.s_addr) + "}"
                   + ", " + std::to_string(sizeof(value))
                   + ");");
      }; // -x- int __debug_sockopt -x-
      const int __debug_sockopt(
      /// Name of function or method
      const std::string func,
      /// The level at which the option resides; typically @c SOL_SOCKET
      const int level,
      /// The name of the option, such as @c SO_REUSEADDR, @c SO_LINGER, etc. 
      const int option,
      /// The structure that this socket option will be set to
      const icmp6_filter* value) {
        return debug(func + randolf::rtools::to_hex(__socket_fd) + "}"
                   + ", " + std::to_string(level)
                   + ", " + std::to_string(option)
                   + ", icmp6_filter{[0]=" + std::to_string(value->icmp6_filt[0])
                                + ", [1]=" + std::to_string(value->icmp6_filt[1])
                                + ", [2]=" + std::to_string(value->icmp6_filt[2])
                                + ", [3]=" + std::to_string(value->icmp6_filt[3])
                                + ", [4]=" + std::to_string(value->icmp6_filt[4])
                                + ", [5]=" + std::to_string(value->icmp6_filt[5])
                                + ", [6]=" + std::to_string(value->icmp6_filt[6])
                                + ", [7]=" + std::to_string(value->icmp6_filt[7]) + "}"
                   + ", " + std::to_string(sizeof(value))
                   + ");");
      }; // -x- int __debug_sockopt -x-
      const int __debug_sockopt(
      /// Name of function or method
      const std::string func,
      /// The level at which the option resides; typically @c SOL_SOCKET
      const int level,
      /// The name of the option, such as @c SO_REUSEADDR, @c SO_LINGER, etc. 
      const int option,
      /// The structure that this socket option will be set to
      const sockaddr_in6* value) {
        return debug(func + randolf::rtools::to_hex(__socket_fd) + "}"
                   + ", " + std::to_string(level)
                   + ", " + std::to_string(option)
                   + ", sockaddr_in6{family=" + std::to_string(value->sin6_family)
                                  + ", port=" + std::to_string(value->sin6_port)
                              + ", flowinfo=" + std::to_string(value->sin6_flowinfo)
                                  + ", addr=" + randolf::rtools::to_hex(value->sin6_addr.__in6_u.__u6_addr16[0])
                                        + ":" + randolf::rtools::to_hex(value->sin6_addr.__in6_u.__u6_addr16[1])
                                        + ":" + randolf::rtools::to_hex(value->sin6_addr.__in6_u.__u6_addr16[2])
                                        + ":" + randolf::rtools::to_hex(value->sin6_addr.__in6_u.__u6_addr16[3])
                                        + ":" + randolf::rtools::to_hex(value->sin6_addr.__in6_u.__u6_addr16[4])
                                        + ":" + randolf::rtools::to_hex(value->sin6_addr.__in6_u.__u6_addr16[5])
                                        + ":" + randolf::rtools::to_hex(value->sin6_addr.__in6_u.__u6_addr16[6])
                                        + ":" + randolf::rtools::to_hex(value->sin6_addr.__in6_u.__u6_addr16[7])
                              + ", scope_id=" + std::to_string(value->sin6_scope_id) + "}"
                   + ", " + std::to_string(sizeof(value))
                   + ");");
      }; // -x- int __debug_sockopt -x-
      const int __debug_sockopt(
      /// Name of function or method
      const std::string func,
      /// The level at which the option resides; typically @c SOL_SOCKET
      const int level,
      /// The name of the option, such as @c SO_REUSEADDR, @c SO_LINGER, etc. 
      const int option,
      /// The structure that this socket option will be set to
      const ip6_mtuinfo* value) {
        return debug(func + randolf::rtools::to_hex(__socket_fd) + "}"
                   + ", " + std::to_string(level)
                   + ", " + std::to_string(option)
                   + ", ip6_mtuinfo{addr=" + randolf::rtools::to_hex(value->ip6m_addr.sin6_addr.__in6_u.__u6_addr16[0])
                                     + ":" + randolf::rtools::to_hex(value->ip6m_addr.sin6_addr.__in6_u.__u6_addr16[1])
                                     + ":" + randolf::rtools::to_hex(value->ip6m_addr.sin6_addr.__in6_u.__u6_addr16[2])
                                     + ":" + randolf::rtools::to_hex(value->ip6m_addr.sin6_addr.__in6_u.__u6_addr16[3])
                                     + ":" + randolf::rtools::to_hex(value->ip6m_addr.sin6_addr.__in6_u.__u6_addr16[4])
                                     + ":" + randolf::rtools::to_hex(value->ip6m_addr.sin6_addr.__in6_u.__u6_addr16[5])
                                     + ":" + randolf::rtools::to_hex(value->ip6m_addr.sin6_addr.__in6_u.__u6_addr16[6])
                                     + ":" + randolf::rtools::to_hex(value->ip6m_addr.sin6_addr.__in6_u.__u6_addr16[7])
                                + ", mtu=" + std::to_string(value->ip6m_mtu) + "}"
                   + ", " + std::to_string(sizeof(value))
                   + ");");
      }; // -x- int __debug_sockopt -x-
      const int __debug_sockopt(
      /// Name of function or method
      const std::string func,
      /// The level at which the option resides; typically @c SOL_SOCKET
      const int level,
      /// The name of the option, such as @c SO_REUSEADDR, @c SO_LINGER, etc. 
      const int option,
      /// The structure that this socket option will be set to
      const ipv6_mreq* value) {
        return debug(func + randolf::rtools::to_hex(__socket_fd) + "}"
                   + ", " + std::to_string(level)
                   + ", " + std::to_string(option)
                   + ", ipv6_mreq{addr=" + randolf::rtools::to_hex(value->ipv6mr_multiaddr.__in6_u.__u6_addr16[0])
                                   + ":" + randolf::rtools::to_hex(value->ipv6mr_multiaddr.__in6_u.__u6_addr16[1])
                                   + ":" + randolf::rtools::to_hex(value->ipv6mr_multiaddr.__in6_u.__u6_addr16[2])
                                   + ":" + randolf::rtools::to_hex(value->ipv6mr_multiaddr.__in6_u.__u6_addr16[3])
                                   + ":" + randolf::rtools::to_hex(value->ipv6mr_multiaddr.__in6_u.__u6_addr16[4])
                                   + ":" + randolf::rtools::to_hex(value->ipv6mr_multiaddr.__in6_u.__u6_addr16[5])
                                   + ":" + randolf::rtools::to_hex(value->ipv6mr_multiaddr.__in6_u.__u6_addr16[6])
                                   + ":" + randolf::rtools::to_hex(value->ipv6mr_multiaddr.__in6_u.__u6_addr16[7])
                          + ", iface=" + std::to_string(value->ipv6mr_interface) + "}"
                   + ", " + std::to_string(sizeof(value))
                   + ");");
      }; // -x- int __debug_sockopt -x-
      const int __debug_sockopt(
      /// Name of function or method
      const std::string func,
      /// The level at which the option resides; typically @c SOL_SOCKET
      const int level,
      /// The name of the option, such as @c SO_REUSEADDR, @c SO_LINGER, etc. 
      const int option,
      /// The structure that this socket option will be set to
      const group_req* value) {
        return debug(func + randolf::rtools::to_hex(__socket_fd) + "}"
                   + ", " + std::to_string(level)
                   + ", " + std::to_string(option)
                   + ", group_req{iface=" + std::to_string(value->gr_interface)
                             + ", <group_req>}"
                   + ", " + std::to_string(sizeof(value))
                   + ");");
      }; // -x- int __debug_sockopt -x-
      const int __debug_sockopt(
      /// Name of function or method
      const std::string func,
      /// The level at which the option resides; typically @c SOL_SOCKET
      const int level,
      /// The name of the option, such as @c SO_REUSEADDR, @c SO_LINGER, etc. 
      const int option,
      /// The structure that this socket option will be set to
      const group_source_req* value) {
        return debug(func + randolf::rtools::to_hex(__socket_fd) + "}"
                   + ", " + std::to_string(level)
                   + ", " + std::to_string(option)
                   + ", group_source_req{iface=" + std::to_string(value->gsr_interface)
                                    + ", <group_source_req>}"
                   + ", " + std::to_string(sizeof(value))
                   + ");");
      }; // -x- int __debug_sockopt -x-
      const int __debug_sockopt_other(
      /// Name of function or method
      const std::string func,
      /// The level at which the option resides; typically @c SOL_SOCKET
      const int level,
      /// The name of the option, such as @c SO_REUSEADDR, @c SO_LINGER, etc. 
      const int option,
      /// The structure that this socket option will be set to
      const socklen_t size) {
        return debug(func + randolf::rtools::to_hex(__socket_fd) + "}"
                   + ", " + std::to_string(level)
                   + ", " + std::to_string(option)
                   + ", other=?"
                   + ", " + std::to_string(size)
                   + ");");
      }; // -x- int __debug_sockopt_other -x-
 
    public:
      /*======================================================================*//**
      @brief
      Discards the specified number of 8-bit bytes efficiently, and without closing
      the stream, and without consuming excessive quantities of memory.
      @exception randolf::rex::xERANGE An invalid value was specified for either
                 the @c nbytes or @c memory_size parameter (e.g., a negative value,
                 except for -1 with the @c nbytes parameter)
      @returns Number of bytes that were successfully discarded
      @see buffer_size
      @see recv
      @qualifier TLS
      *///=========================================================================
      int discard(
      /// Number of bytes to discard@n
      /// 0 = use internal @ref buffer_size() @n
      /// -1 = all remaining data waiting to be received (in other words, this
      /// method will repeatedly consume all data until encountering @ref eos)
      int nbytes,
      /// MSG_OOB@n
      /// MSG_PEEK (ignored, to prevent an endless loop)@n
      /// MSG_WAITALL@n
      /// MSG_DONTWAIT@n
      /// MSG_CMSG_CLOEXEC
      int posix_flags = 0,
      /// Maximum internal read size@n
      /// 0 = default to @ref buffer_size (when @c nbytes is larger than this size,
      /// multiple reads into this buffer will be utilized behind-the-scenes to
      /// consume the quantity of data specified by the @c nbytes parameter)
      const size_t memory_size = 0) {
        int buf_size = memory_size != 0 ? memory_size : __buffer_size;
        if (__debug) debug("discard(socket{0x" + randolf::rtools::to_hex(__socket_fd) + "}"
                         + ", " + std::to_string(nbytes)
                         + ", " + std::to_string(posix_flags)
                         + ", " + std::to_string(buf_size)
                         + ");");
 
        // --------------------------------------------------------------------------
        // Syntax checks.
        // --------------------------------------------------------------------------
             if (nbytes == 0) nbytes = __buffer_size;
        else if (nbytes < -1) throw randolf::rex::xERANGE(     "nbytes parameter of " + std::to_string(nbytes)      + " is below -1");
        if (memory_size <  0) throw randolf::rex::xERANGE("memory_size parameter of " + std::to_string(memory_size) + " is below 0");
 
        // --------------------------------------------------------------------------
        // The MSG_PEEK flag is incompatible with this method, so we're turning it
        // off to prevent an endless loop.  We're providing a debug message for this
        // in case someone's trying to track something down where they're using the
        // MSG_PEEK flag with a misunderstanding of the purpose of this method.
        // --------------------------------------------------------------------------
        if (posix_flags & MSG_PEEK) {
          posix_flags &= (~MSG_PEEK); // Remove MSG_PEEK flag if it was enabled
          if (__debug) debug("discard(socket{0x" + randolf::rtools::to_hex(__socket_fd) + "}"
                           + " ignoring incompatible MSG_PEEK flag"
                           + ");");
        } // -x- if MSG_PEEK -x-
 
        // --------------------------------------------------------------------------
        // Internal variables.
        // --------------------------------------------------------------------------
        int discarded = 0; // Total number of bytes discarded
        std::vector<char> buf(buf_size);
        buf.reserve(buf_size); // Pre-allocate underlying array to prevent memory corruption when __recv writes directly into it
 
        // --------------------------------------------------------------------------
        // Discard loop.  We are intentionally handling nbytes in two different ways
        // hear with a little bit more code to benefit from the trade-off of faster
        // overall performance.
        // --------------------------------------------------------------------------
        try {
 
          // --------------------------------------------------------------------------
          // Discard all remaining data waiting to be received.
          // --------------------------------------------------------------------------
          if (nbytes < 0) {
            int n = 0;
            while (!eos()) {
              n = __recv(buf.data(), buf_size, posix_flags);
              discarded += n;
            }; // -x- while n -x-
 
          // --------------------------------------------------------------------------
          // Discard specific amount of data waiting to be received.
          // --------------------------------------------------------------------------
          } else {
            int n = 0;
            int inbytes = nbytes;
            while (inbytes > 0 && !eos()) {
              int n = __recv(buf.data(), std::min(inbytes, buf_size), posix_flags);
              inbytes   -= n;
              discarded += n;
            } // -x- while nbytes -x-
          } // -x- if nbytes -x-
 
        // --------------------------------------------------------------------------
        // Ignore exception so that we can simply indicate how many bytes were
        // successfully received and discarded.
        // --------------------------------------------------------------------------
        } catch(const rex::xALL e) {}
 
        // --------------------------------------------------------------------------
        // Erase all data to prevent data from being unexpectedly leaked to any other
        // memory allocations later that use some or all of the same memory.
        // --------------------------------------------------------------------------
        for (int i = nbytes <= 0 ? buf_size : std::min(nbytes, buf_size); i > 0; i--) {
          buf[i] = '\0';
        } // -x- for i -x-
 
        return discarded;
      }; // -x- int discard -x-
 
      /*======================================================================*//**
      @brief
      Discards the specified number of 8-bit bytes efficiently, but stops upon
      encountering an EoL sequence (which will also be discarded; to find out which
      EoL sequence was consumed, use the @ref eol_consumed_seq method which will
      also return an empty string if no EoL sequence was consumed), and without
      closing the stream, and without consuming excessive quantities of memory.
 
      This method is particularly useful for discarding lines that are too long,
      which, for example, makes it possible to ignore lines that are too long (and
      optionally present or log an error) and continue reading the next line(s)
      that follow.
 
      @exception randolf::rex::xERANGE An invalid value was specified for either
                 the @c nbytes or @c memory_size parameter (e.g., a negative value,
                 except for -1 with the @c nbytes parameter)
      @returns Number of bytes that were successfully discarded
      @see buffer_size
      @see recv
      @qualifier TLS
      *///=========================================================================
      int discard_line(
      /// Number of bytes to discard@n
      /// 0 = use internal @ref buffer_size() @n 
      /// -1 = all remaining data waiting to be received (in other words, this
      /// method will repeatedly consume all data until encountering @ref eos)
      int nbytes = -1,
      /// MSG_OOB@n
      /// MSG_PEEK (ignored, to prevent an endless loop)@n
      /// MSG_WAITALL@n
      /// MSG_DONTWAIT@n
      /// MSG_CMSG_CLOEXEC
      int posix_flags = 0,
      /// Line timeout (in seconds)@n
      /// 0 = no timeout (default), unless it was configured by way of the
      ///     @ref timeout_recvline(long) method
      long timeout = 0,
      /// Maximum internal read size@n
      /// 0 = default to @ref buffer_size (when @c nbytes is larger than this size,
      /// multiple reads into this buffer will be utilized behind-the-scenes to
      /// consume the quantity of data specified by the @c nbytes parameter)
      const size_t memory_size = 0) {
        int buf_size = memory_size != 0 ? memory_size : __buffer_size;
        if (__debug) debug("discard_line(socket{0x" + randolf::rtools::to_hex(__socket_fd) + "}"
                         + ", " + std::to_string(nbytes)
                         + ", " + std::to_string(posix_flags)
                         + ", " + std::to_string(buf_size)
                         + ");");
 
        // --------------------------------------------------------------------------
        // Syntax checks.
        // --------------------------------------------------------------------------
        bool infinite = nbytes == -1; // Keep track of whether nbytes was -1 before changing its value
             if (nbytes ==  0) nbytes = __buffer_size;
        else if (nbytes == -1) nbytes = INT_MAX;
        else if (nbytes <  -1) throw randolf::rex::xERANGE(     "nbytes parameter of " + std::to_string(nbytes)      + " is below -1");
        if (memory_size <   0) throw randolf::rex::xERANGE("memory_size parameter of " + std::to_string(memory_size) + " is below 0");
 
        // --------------------------------------------------------------------------
        // Syntax checks as part of preparation of timeout variable for faster
        // comparisons within line-reading loop.
        // --------------------------------------------------------------------------
        if (timeout <  0) throw randolf::rex::xERANGE("timeout parameter of " + std::to_string(timeout) + " is below 0");
        if (timeout == 0) timeout = __recvline_timeout;
        timeout = timeout == 0 ? LONG_MAX : timeout + time(0);
 
        // --------------------------------------------------------------------------
        // The MSG_PEEK flag is incompatible with this method, so we're turning it
        // off to prevent an endless loop.  We're providing a debug message for this
        // in case someone's trying to track something down where they're using the
        // MSG_PEEK flag with a misunderstanding of the purpose of this method.
        // --------------------------------------------------------------------------
        if (posix_flags & MSG_PEEK) {
          posix_flags &= (~MSG_PEEK); // Remove MSG_PEEK flag if it was enabled
          if (__debug) debug("discard(socket{0x" + randolf::rtools::to_hex(__socket_fd) + "}"
                           + " ignoring incompatible MSG_PEEK flag"
                           + ");");
        } // -x- if MSG_PEEK -x-
 
        // --------------------------------------------------------------------------
        // Internal variables.
        // --------------------------------------------------------------------------
        int discarded = 0; // Total number of bytes discarded
        std::string buf;
        int buf_size_eol = buf_size + 1;
        buf.reserve(buf_size_eol); // Pre-allocate underlying array to prevent memory corruption when __recv writes directly into it, with +1 for straddled EoL
//        char straddle_eol = 0;
 
        // --------------------------------------------------------------------------
        // Discard loop.  We are intentionally handling nbytes in two different ways
        // hear with a little bit more code to benefit from the trade-off of faster
        // overall performance.
        // --------------------------------------------------------------------------
        try {
 
          // --------------------------------------------------------------------------
          // Discard all remaining data waiting to be received.
          // --------------------------------------------------------------------------
          if (infinite) {
            int n = 0;
            while (!eos()) {
              n = __recv(buf.data(), buf_size_eol, posix_flags | MSG_PEEK);
 
              // --------------------------------------------------------------------------
              // Affect an actual discard of the correct amount of data.  If "len" is -1,
              // then just discard everything because it means that we didn't encounter an
              // EoL sequence in this iteration.
              // --------------------------------------------------------------------------
              int len_with_eol = 0;
              int len = eol_index(buf, &len_with_eol); // Measure length of string with EoL (-1 = no EoL found)
std::cout << "/////   n=" << n << " len=" << len << " len_with_eol=" << len_with_eol << " buf_size_eol=" << buf_size_eol << std::endl;
              n = __recv(buf.data(), len > 0 ? len : n, posix_flags); // Consume data
std::cout << "        n=" << n << std::endl;
              discarded += n;
            } // -x- while n -x-
 
          // --------------------------------------------------------------------------
          // Discard specific amount of data waiting to be received.
          // --------------------------------------------------------------------------
          } else {
            int n = 0;
            int inbytes = nbytes;
            while (inbytes > 0 && !eos()) {
              n = __recv(buf.data(), std::min(inbytes + 1, buf_size_eol), posix_flags | MSG_PEEK);
 
              // --------------------------------------------------------------------------
              // Affect an actual discard of the correct amount of data.  If "len" is -1,
              // then just discard everything because it means that we didn't encounter an
              // EoL sequence in this iteration.
              // --------------------------------------------------------------------------
              int len_with_eol = 0;
              int len = eol_index(buf, &len_with_eol); // Measure length of string with EoL (-1 = no EoL found)
std::cout << "|||||   n=" << n << " len=" << len << " len_with_eol=" << len_with_eol << " buf_size_eol=" << buf_size_eol << std::endl;
              n = __recv(buf.data(), len >= 0 ? len : n, posix_flags); // Consume data
std::cout << "        n=" << n << std::endl;
              inbytes   -= n;
              discarded += n;
            } // -x- while nbytes -x-
          } // -x- if nbytes -x-
 
        // --------------------------------------------------------------------------
        // Ignore exception so that we can simply indicate how many bytes were
        // successfully received and discarded.
        // --------------------------------------------------------------------------
        } catch(const rex::xALL e) {
std::cout << "Exception: " << e.what() << std::endl;
        }
 
std::cout << "discarded=" << discarded << std::endl;
 
        // --------------------------------------------------------------------------
        // Erase all data to prevent data from being unexpectedly leaked to any other
        // memory allocations later that use some or all of the same memory.
        //
        // Note:  The +1 in the buffer size calcuation is to include a straddled EoL.
        // --------------------------------------------------------------------------
        for (int i = infinite ? buf_size : std::min(nbytes + 1, buf_size_eol); i > 0; i--) {
          buf[i] = '\0';
        } // -x- for i -x-
 
        return discarded;
      }; // -x- int discard_line -x-
 
      /*======================================================================*//**
      @brief
      Find out what the current EoL (End of Line) sequence is set to.
      @warning
      To send an EoL sequence do not use `send(r.eol())` because it may not be
      initialized yet and the endpoint you're sending to may seem unresponsive or
      other unexpected behaviour may occur.@n
      @n
      To send an EoL sequence properly, use @ref sendline(); although specifying no
      parameters is more efficient than specifying an empty string (@c ""), the
      specialized @ref send_eol() method is the most efficient option for sending
      an EoL sequence separately.
      @note
      An empty EoL sequence means that CRLF will be sent by @ref sendline(), and
      that @ref recvline(), and @ref recv_rline() will automatically detect from
      one of @c CR, @c CRLF, @c LF, and @c LFCR.
      @returns Current EoL sequence
      @see eol_adoption
      @see eol_fix_printf
      @see printfline
      @see recvline
      @see recv_rline
      @see sendline
      @see send_eol
      @see vprintfline
      @qualifier TLS
      *///=========================================================================
      const std::string eol() noexcept { return __eol; }; // -x- std::string eol -x-
 
      /*======================================================================*//**
      @brief
      Set EoL (End of Line) sequence.  This sequence is used by recvline(),
      recv_rline(), sendline(), and related functions, and it defaults to an empty
      string which results in the EoL sequence being detected automatically
      on-the-fly.
 
         - @c "" (empty string) = automatically detect on-the-fly (default)
         - @c \\r\\n (CRLF) = Carriage Return + Linefeed (typical for DOS)
         - @c \\r (CR) = Carriage Return (typical for MacOS)
         - @c \\n (LF) = Linefeed (typical for UNIX/Linux)
 
      @note
      CRLF (@c \\r\\n) is used by most internet protocols (e.g., HTTP, SMTP, POP3,
      IMAP4, FINGER, NICNAME/WHOIS, etc.).
      @returns The same rsocket object so as to facilitate stacking
      @see eol_adoption
      @see eol_fix_printf
      @see printfline
      @see vprintfline
      @see recv_rline
      @see recvline
      @see sendline
      @see send_eol
      @qualifier TLS
      *///=========================================================================
      rsocket* eol(
      /// EoL sequence as an ASCIIZ string
      const char* eol) noexcept {
        __eol = std::string(eol);
        __eol_out = __eol.empty() ? __CRLF : __eol;
        return this;
      }; // -x- rsocket* eol -x-
 
      /*======================================================================*//**
      @brief
      Set EoL (End of Line) sequence.  This sequence is used by recvline(),
      recv_rline(), sendline(), and related functions, and it defaults to an empty
      string which results in the EoL sequence being detected automatically
      on-the-fly.
 
         - @c "" (empty string) = automatically detect on-the-fly (default)
         - @c \\r\\n (CRLF) = Carriage Return + Linefeed (typical for DOS)
         - @c \\r (CR) = Carriage Return (typical for MacOS)
         - @c \\n (LF) = Linefeed (typical for UNIX/Linux)
 
      @note
      CRLF (@c \\r\\n) is used by most internet protocols (e.g., HTTP, SMTP, POP3,
      IMAP4, FINGER, NICNAME/WHOIS, etc.).
      @returns The same rsocket object so as to facilitate stacking
      @see eol_fix_printf
      @see printfline
      @see vprintfline
      @see recv_rline
      @see recvline
      @see sendline
      @see send_eol
      @qualifier TLS
      *///=========================================================================
      rsocket* eol(
      /// EoL sequence as an std::string object
      const std::string eol) noexcept {
        __eol = eol;
        return this;
      }; // -x- rsocket* eol -x-
 
      /*======================================================================*//**
      @brief
      Configure EoL adoption policy for the @ref recvline() and @ref recv_rline()
      methods.  By default, @ref rsocket is configured with the EoL adoption policy
      enabled alongside an empty @ref eol() sequence, which results in the default
      operation being that the EoL sequence automatically gets detected and updated
      internally upon the first use of either the @ref recvline() or
      @ref recv_rline method.
 
      The EoL adoption policy is only effective when the @ref eol() sequence is not
      defined (which is indicated by an empty EoL sequence string).
 
      The EoL sequence is updated only when the EoL sequence string is empty, and
      when this EoL adoption policy is enabled.
      @returns The same rsocket object so as to facilitate stacking
      @see eol
      @see eol_index
      @see is_eol_adoption
      @see recv_rline
      @see recvline
      @see sendline
      @see send_eol
      @qualifier TLS
      *///=========================================================================
      rsocket* eol_adoption(
      /// TRUE = enable EoL adoption (default)@n
      /// FALSE = disable EoL adoption
      const bool flag) noexcept {
        __eol_adoption = flag;
        return this;
      }; // -x- rsocket* eol_adoption -x-
 
      /*======================================================================*//**
      @brief
      Returns a String containing the EoL character sequence that was consumed by
      the most recent successful call to the @ref recvline() or @ref recv_rline
      method ("successful" in this context means that the received line was
      terminated by a valid EoL character sequence; otherwise the
      previous/unmodified value is returned).
      @warning
      This method must not be used to determine whether the @ref recvline() method
      successfully consumed an EoL character sequence.&nbsp; The reason for this is
      that @ref recvline() doesn't update this string when it doesn't consume an
      EoL character sequence, hence interpreting its results can (and likely will)
      lead to false positives.
      @returns EoL character sequence
      @see eol
      @see eol_adoption
      @see recv_rline
      @see recvline
      @qualifier TLS
      *///=========================================================================
      const std::string eol_consumed_seq() noexcept { return __eol_consumed_seq; }; // -x- std::string eol_consumed_seq -x-
 
      /*======================================================================*//**
      @brief
      Configure EoL substitution policy for the @ref printf(), @ref printfline(),
      @ref vprintf(), and @ref vprintfline() methods.  By default, @ref rsocket
      substitutes printf's @c \\n sequence with the EoL sequence (if defined), but
      this method can be used to disable this behaviour.
      @note
      The @c \\n sequence used in the printf format string normally coincides with
      the local Operating System's newline standard, which is very likely different
      from the @ref rsocket endpoint's newline standard, and/or the newline
      standard of the protocol being implemented.  This policy setting makes it
      possible to control whether to use the configured EoL sequence when sending a
      formatted string to the endpoint.
      @returns The same rsocket object so as to facilitate stacking
      @see eol
      @see is_eol_fix_printf
      @see printf
      @see printfline
      @see vprintf
      @see vprintfline
      @qualifier TLS
      *///=========================================================================
      rsocket* eol_fix_printf(
      /// TRUE = enable EoL substitution (default)@n
      /// FALSE = disable EoL substitution
      const bool flag) noexcept {
        __eol_fix_printf = flag;
        return this;
      }; // -x- rsocket* eol_fix_printf -x-
 
      /*======================================================================*//**
      @brief
      Finds the first instance of the EoL sequence and returns its offset (which is
      effectively the same as the size of the text, not including the characters
      that the EoL sequence is comprised of).
 
      @note
      This method is specialized primarily for internal use by the @ref recvline()
      and @ref recv_rline() methods, but is made available here in case there's a
      need to check in-memory text using this rsocket's EoL detection policy.
      @returns Size of EoL sequence
      @returns -1 if EoL sequence wasn't found
      @see eol
      @see eol_adoption
      @qualifier TLS
      *///=========================================================================
      const int eol_index(
      /// Buffer that probably contains at least one EoL sequence
      const std::string buffer,
      /// Size of string with EoL character sequence included (will be updated by this method)
      int* with_eol_size) noexcept {
 
        // --------------------------------------------------------------------------
        // An EoL character sequence was specified, a simple search will suffice.
        // --------------------------------------------------------------------------
        if (!__eol.empty()) {
//std::cout << "!__eol.empty() ------------------------------ " << randolf::rtools::to_hex(__eol) << std::endl;
          int pos = buffer.find(__eol);
          if (pos >= 0) {
            *with_eol_size = pos + __eol.size(); // Update size of EoL sequence
//std::cout << "------0------ pos=" << pos << " with_eol_size=" << *with_eol_size << " __eol.size()=" << __eol.size() << std::endl;
            //return pos;
          } // -x- if pos -x-
//std::cout << "------1------ pos=" << pos << " with_eol_size=" << *with_eol_size << " __eol.size()=" << __eol.size() << std::endl;
          if (!__eol_adoption) return pos; // Return the -1 error if we're not adopting different EoF sequences on-the-fly
        } // -x- if !__eol.empty() -x-
//std::cout << "__eol.empty() ------------------------------ String is empty" << std::endl;
 
        // --------------------------------------------------------------------------
        // Automatic detection of EoL sequence, so a more flexible approach will be
        // required.
        //
        // Search for all four possible EoL sequences (as indicated by an empty EoL
        // character sequence string):
        //
        // CRLF:  Common for text lines with internet protocols such as SMTP, POP3,
        //        IMAP4, HTTP, FINGER, WHOIS, etc.  Also:  DOS and OS/2 EoL sequence.
        //
        // CR:  MacOS EoL character.
        //
        // LF:  UNIX/Linux EoL character.
        //
        // LFCR:  Extremely rare, but I've encountered multiple instances where the
        //        intended CRLF was reversed to LFCR, possibly due to a programming
        //        error or an artifact of inappropriate/unintended endian conversion.
        // --------------------------------------------------------------------------
        int pos  = buffer.find(__CR); // CR or CRLF
//std::cout << "------2------ <CR> pos=" << pos << " with_eol_size=" << *with_eol_size << " __eol.size()=" << __eol.size() << std::endl;
        if (pos == (buffer.size() - 1)) { // EoL sequence not found (this handles a specific empty-buffer edge case caused by SSL background chatter that's very rare but causes problems that are nearly impossible to debug when they do occur)
          *with_eol_size = pos;// + 1;
//          *with_eol_size = 1;
//std::cout << "------3------ <!CR> pos=" << pos << " with_eol_size=" << *with_eol_size << " __eol.size()=" << __eol.size() << std::endl;
          return pos;
        } else if (pos >= 0) { // EoL sequence found
          *with_eol_size = pos + (buffer[pos + 1] == __LF ? 2 : 1); // 2=CRLF, 1=CR
//          *with_eol_size = buffer[pos + 1] == __LF ? 2 : 1; // 2=CRLF, 1=CR
          if (__eol_adoption) {
            __eol = buffer.substr(pos, *with_eol_size - pos); // Adopt EoL sequence
            __eol.resize(*with_eol_size - pos); // Truncate extra characters
          } // -x- if __eol_adoption -x-
//std::cout << "------4------ <CR/CRLF-adopted> pos=" << pos << " with_eol_size=" << *with_eol_size << " __eol.size()=" << __eol.size() << std::endl;
          return pos; // Either way, we're done
        } // -x- if pos -x-
 
        pos = buffer.find(__LF); // LF or LFCR
        if (pos == (buffer.size() - 1)) { // EoL sequence not found (this handles a specific empty-buffer edge case caused by SSL background chatter that's very rare but causes problems that are nearly impossible to debug when they do occur)
          *with_eol_size = pos;// + 1;
//          *with_eol_size = 1;
//std::cout << "------5------ <LF> pos=" << pos << " with_eol_size=" << *with_eol_size << " __eol.size()=" << __eol.size() << std::endl;
          return pos;
        } else if (pos >= 0) { // EoL sequence found
          *with_eol_size = pos + (buffer[pos + 1] == __CR ? 2 : 1); // 2=LFCR, 1=LF
//          *with_eol_size = buffer[pos + 1] == __CR ? 2 : 1; // 2=LFCR, 1=LF
          if (__eol_adoption) {
            __eol = buffer.substr(pos, *with_eol_size - pos); // Adopt EoL sequence
            __eol.resize(*with_eol_size - pos); // Truncate extra characters
          } // -x- if __eol_adoption -x-
//std::cout << "------6------ <LF/LFCR-adopted> pos=" << pos << " with_eol_size=" << *with_eol_size << " __eol.size()=" << __eol.size() << std::endl;
          return pos; // Either way, we're done
        } // -x- if pos -x-
 
//std::cout << "------7------ <LF> pos=" << pos << " with_eol_size=" << *with_eol_size << " __eol.size()=" << __eol.size() << std::endl;
        return pos;
      }; // -x- int eol_index -x-
 
      /*======================================================================*//**
      @brief
      Find out if the stream is at its end and that this @ref rsocket's internal
      buffer (if one had been set up by the @ref recvline() method) is empty.  This
      doesn't necessarily mean that the stream is closed; but rather that the
      endpoint just hasn't sent any more data (yet).
 
      If the stream isn't open, then this method will always return @c true to
      implicitly indicate that there's no data pending to be received.
 
      @pre
      You can optionally specify a timeout with the timeout parameter, which will
      cause this method to wait for the specified period of time for pending data.
 
      It's better (more efficient) to use this method instead of the @c MSG_PEEK
      flag (with the various @c recv methods) to determine whether any data is
      waiting on the stream (e.g., data that's received by the sockets, but not by
      any @c recv methods yet) because this method is specialized in handling this
      particular condition and responds with an easy-to-use boolean flag.
 
      @note
      EoS is an acronym for:  End of Stream
 
      @throws randolf::rex::xEBADF The underlying socket is not open
      @throws randolf::rex::xEFAULT Address structure/memory is not in a writable
              part of the user address space
      @throws randolf::rex::xEINTR Interrupted by a signal
      @throws randolf::rex::xENOMEM Insufficient memory
      @throws randolf::rex::xENOTSOCK Underlying socket file descriptor (handle)
              doesn't refer to a socket
      @throws randolf::rex::xETIMEDOUT Timeout period elapsed (even if the @c
              TIMEOUT_BEHAVIOUR flag is @em not set to @c TIMEOUT_EXCEPTION, there
              is a highly improbable chance that a timeout could still occur if the
              data is read by another thread before the `recv(..., MSG_PEEK)` call)
      @throws randolf::rex::xEWOULDBLOCK The underlying socket is non-blocking and
              there's no new data
 
      @returns TRUE = End of Stream (no buffered data, the stream @ref is_closed(),
                      or there's no pending data, checked in this order)
      @returns FALSE = Pending data available
      @see is_closed
      @see is_open
      @see recv
      @qualifier TLS
      *///=========================================================================
      const bool eos(
      /// Number of milliseconds to wait
      const int timeout = 0) {
 
        // --------------------------------------------------------------------------
        // Check internal buffer first, if there is one, and return immediately if
        // the buffer is not empty.
        // --------------------------------------------------------------------------
        if (__buffer != nullptr && !__buffer->empty()) return false;
 
        // --------------------------------------------------------------------------
        // If socket is closed, then just indicate EoS to be done with it.  No need
        // to fall through to timeouts as this is not applicable.
        // --------------------------------------------------------------------------
        if (!__socket_open) return true;
 
        // --------------------------------------------------------------------------
        // Start by checking whether OpenSSL has pending data, and if it doesn't (or
        // there's an error, which is also indicated by 0) then fall through to
        // checking the underlying socket using ioctl's FIONREAD...
        //
        // Use ioctl's FIONREAD to determine if any data is waiting to be read.  If
        // ioctl returns non-zero, then an error occurred which always equates to
        // EoS (otherwise the FIONREAD operation would have been successful).
        // --------------------------------------------------------------------------
        if (__tls && SSL_has_pending(__tls_fd) == 1) return false;
        int n = 0; // Number of bytes waiting (default to 0 in case of ioctl error)
        ioctl(__socket_fd, FIONREAD, &n); // Ignore return code because "n" will be zero if there's an error
        if (n > 0) return false; // 0 bytes remaining means EoS
 
        // --------------------------------------------------------------------------
        // Timeout polling (if a timeout was specified).
        // --------------------------------------------------------------------------
        if (timeout != 0) {
          try {
            poll(POLLIN, timeout);
            return false; // EoS, because the "poll" method was triggered by new data
          } catch (const randolf::rex::xETIMEDOUT e) {
            return true; // EoS, because the "poll" method timed out while waiting for new data
          } // This is a specialized catch situation -- the ::recv function could still return an ETIMEDOUT error
        } // -x- if timeout -x-
 
        return true; // EoS, because new data was not detected
      }; // -x- bool eos -x-
 
      /*======================================================================*//**
      @brief
      Find out what the specified IP address string's family (@c SO_DOMAIN) is.
      @throws randolf::rex::xEADDRNOTAVAIL The interface doesn't exist or the
              address is not available on any local interface
      @throws randolf::rex::xEAI_NONAME If @c address is an empty string
      @returns @c AF_UNSPEC (if family couldn't be determined)
      @returns @c AF_INET (IPv4 address)
      @returns @c AF_INET6 (IPv6 address)
      @returns @c AF_UNIX (UNIX Domain address)
      @returns ...or other family as applicable
      @qualifier TLS
      *///=========================================================================
      int static family(
      /// Address, similar to @ref bind() addressing, including non-standard "if="
      /// variant that names a network interface
      const std::string address,
      /// Preferred family to return first (used only with interface mode where the
      /// network interface is specified after the "if=" prefix); the default value
      /// of @c AF_UNSPEC will return the first family interface found
      const int preferred_family = AF_UNSPEC) {
 
        // --------------------------------------------------------------------------
        // Simple checks first.
        // --------------------------------------------------------------------------
        if (address.size()  == 0)   randolf::rex::mk_exception("", EAI_NONAME);
        if (address.front() == '/') return AF_UNIX;
 
        // --------------------------------------------------------------------------
        // if=<interface-name>:  Same "interface" option that we support in bind()
        // --------------------------------------------------------------------------
        if (address.starts_with("if=")) {
          //std::cout << "address=" << address.substr(3).c_str() << std::endl; // Debug
          struct ifaddrs *ifaddr; // Chained interface addresses structure
          if (::getifaddrs(&ifaddr) == -1) { // Error occurred, so we're done here
            freeifaddrs(ifaddr); // Memory management
            randolf::rex::mk_exception("getifaddrs() error (prequisite to searching for " + address + ")", 0, rex::rex::REX_FLAGS::REX_FIND_ERRNO);
          } // -x- if getifaddrs -x
 
          // --------------------------------------------------------------------------
          // Iterate through interface addresses.  Each address should have a different
          // address family/domain, and is never AF_UNSPEC (this should never happen
          // because it wouldn't make sense, but if the network implementation was
          // broken and including an AF_UNSPEC family/domain, it would be useless for
          // the purposes of calling the ::socket() function so our code will just
          // ignore it anyway.
          // --------------------------------------------------------------------------
          int first_family = AF_UNSPEC; // We're using AF_UNSPEC (0) to indicate that there isn't a family/domain
          for (struct ifaddrs *ifa = ifaddr; ifa != nullptr; ifa = ifa->ifa_next) {
            if (ifa->ifa_addr == nullptr) continue; // No address structure, so this isn't useful to us at all
            if (ifa->ifa_addr->sa_family == AF_UNSPEC) continue; // Skip AF_UNSPEC family/domain, as we can't use this
            if (address.compare(3, -1, ifa->ifa_name) != 0) continue; // Not the interface name we're looking for
 
            // --------------------------------------------------------------------------
            // Return current address's family if preferred_family is not specified (if
            // it's set to AF_UNSPEC {0}), or if it matches the current address.
            // --------------------------------------------------------------------------
            //std::cout << "if=" << ifa->ifa_name << " family=" << ifa->ifa_addr->sa_family << std::endl; // Debug
            if (preferred_family == AF_UNSPEC || preferred_family == ifa->ifa_addr->sa_family) {
              first_family = ifa->ifa_addr->sa_family; // Arbitrarily re-using first_family variable
              freeifaddrs(ifaddr); // Memory management
              return first_family; // Return current family/domain (re-used first_family variable)
            } // -x- if preferred_family -x-
 
            // --------------------------------------------------------------------------
            // Keep track of only the first_family/domain that we found; if we can't find
            // the preferred_family, then we'll be able to return the first one we found.
            // --------------------------------------------------------------------------
            if (first_family == AF_UNSPEC && ifa->ifa_addr->sa_family != AF_UNSPEC) first_family = ifa->ifa_addr->sa_family;
            //std::cout << "   first_family=" << first_family << std::endl; // Debug
          } // -x- for *ifa -x-
 
          // --------------------------------------------------------------------------
          // Return first_family/domain, if there was one; otherwise, throw exception.
          // --------------------------------------------------------------------------
          freeifaddrs(ifaddr); // Memory management
          if (first_family != AF_UNSPEC) return first_family;
          randolf::rex::mk_exception("Interface (" + address.substr(3) + ") doesn't exist" + (preferred_family == AF_UNSPEC ? "" : " or the preferred family/domain (" + std::to_string(preferred_family) + ") is not supported"), EADDRNOTAVAIL);
        } // -x- if /^if=/ -x-
 
        // --------------------------------------------------------------------------
        // Attempt to detect IPv4 or IPv6 using a simple shortcut with ::inet_pton(),
        // which requires some additional memory allocation (that the simple checks
        // from earlier don't need).
        // --------------------------------------------------------------------------
        char buf[sizeof(struct in6_addr)]; // Binary address storage
        if (::inet_pton(AF_INET,  address.c_str(), buf) == 1) return AF_INET;
        if (::inet_pton(AF_INET6, address.c_str(), buf) == 1) return AF_INET6;
 
        // --------------------------------------------------------------------------
        // Throw xEAI_FAMILY exception because no family/domain was found.
        // --------------------------------------------------------------------------
        randolf::rex::mk_exception("No family/domain available for: " + address, EAI_FAMILY);
      }; // -x- int family -x-
 
      /*======================================================================*//**
      @brief
      Get peer name returns the address of the socket as a sockaddr_storage
      structure.
 
      The resulting structure is wrapped in std::shared_ptr (a C++ smart pointer
      that aids in the prevention of resource leaks).
 
      @throws randolf::rex::xEBADF The underlying socket is not open
      @throws randolf::rex::xEFAULT Address structure/memory is not in a writable
              part of the user address space
      @throws randolf::rex::xEINVAL Address length is incorrect, or address is not
              valid for this socket's family (a.k.a., communication domain)
      @throws randolf::rex::xENOBUFS Insufficient memory
      @throws randolf::rex::xENOTCONN Underlying socket is not connected
      @throws randolf::rex::xENOTSOCK Underlying socket file descriptor (handle)
              doesn't refer to a socket
 
      @returns sockaddr_storage structure
      @qualifier POSIX
      @qualifier TLS
      *///=========================================================================
      const std::shared_ptr<sockaddr_storage> getpeername() {
        std::shared_ptr sa = std::make_shared<sockaddr_storage>();
        socklen_t len = sizeof(sockaddr_storage);
        __rc_check(::getpeername(__socket_fd, (struct sockaddr*)sa.get(), &len));
        return sa;
      }; // -x- std::shared_ptr<sockaddr_storage> getpeername -x-
 
      /*======================================================================*//**
      @brief
      Get peer name returns the address of the socket as a std::string object.
 
      @throws randolf::rex::xEAI_ADDRFAMILY if the address can't be determined
              (e.g., because the @c family doesn't utilize or support an address
              {or the format isn't known}
      @throws randolf::rex::xEAFNOSUPPORT Address family not implemented/supported
      @throws randolf::rex::xEBADF The underlying socket is not open
      @throws randolf::rex::xEFAULT Address structure/memory is not in a writable
              part of the user address space
      @throws randolf::rex::xEINVAL Address length is incorrect, or address is not
              valid for this socket's family (a.k.a., communication domain)
      @throws randolf::rex::xENOBUFS Insufficient memory
      @throws randolf::rex::xENOSPC Resulting address string exceeds maximum size
      @throws randolf::rex::xENOTCONN Underlying socket is not connected
      @throws randolf::rex::xENOTSOCK Underlying socket file descriptor (handle)
              doesn't refer to a socket
 
      @returns string representation of peer name
      @qualifier TLS
      *///=========================================================================
      const std::string getpeername_ntop() {
        sockaddr_storage sa;
        socklen_t len = sizeof(sockaddr_storage);
        __rc_check(::getpeername(__socket_fd, (sockaddr*)&sa, &len));
        return inet_ntop(&sa);
      }; // -x- std::string getpeername_ntop -x-
 
      /*======================================================================*//**
      @brief
      Get specified "sockaddr_storage" structure's address as a "sockaddr"
      structure, for sockets in one of the supported families:
 
         - AF_INET (IPv4)
         - AF_INET6 (IPv6)
         - AF_UNIX (Domain socket path)
         - AF_PACKET (Ethernet node/mac. address)
 
      @throws randolf::rex::xEAI_ADDRFAMILY if the address can't be determined
              (e.g., because the @c family doesn't utilize or support an address
              {or the format isn't known}
 
      @returns pointer to sockaddr structure within provided sockaddr_storage
      @see bind
      @see mk_sockaddr_storage
      @see recvfrom
      @see sendto
      @see sendzto
      @qualifier POSIX
      @qualifier TLS
      *///=========================================================================
      static sockaddr* getsockaddr(
      /// The @c sockaddr_storage structure wherein @c sockaddr will be referenced from
      const sockaddr_storage* sa) {
        switch (sa->ss_family) {
          case AF_INET: // IPv4 address
            return (sockaddr*)&(((struct sockaddr_in*)sa)->sin_addr);//->sin_addr);
          case AF_INET6: // IPv6 address
            return (sockaddr*)&(((struct sockaddr_in6*)sa)->sin6_addr);//->sin6_addr);
          case AF_UNIX: // UNIX (path) domain socket
            return (sockaddr*)&(((struct sockaddr_un*)sa)->sun_path);//->sun_path);
          // AF_LINK is not supported at this time due to lack of clarity on obtaining and presenting the address
          // case /*AF_LINK* /18: // Link layer interface (arp)
          //  break;
          case AF_PACKET: // Packet (ethernet) address (packet capturing)
            return (sockaddr*)&(((struct sockaddr_ll*)sa)->sll_addr);//->sll_addr);
        } // -x- switch family -x-
        throw randolf::rex::xEAI_ADDRFAMILY("EAI_ADDRFAMILY"); // Everything else
      }; // -x- sockaddr* getsockaddr -x-
 
      /*======================================================================*//**
      @brief
      Get socket name returns the address of the socket as a "sockaddr_storage"
      structure.
 
      The resulting structure is wrapped in std::shared_ptr (a C++ smart pointer
      that aids in the prevention of resource leaks).
 
      @throws randolf::rex::xEBADF The underlying socket is not open
      @throws randolf::rex::xEFAULT Address structure/memory is not in a writable
              part of the user address space
      @throws randolf::rex::xEINVAL Address length is incorrect, or address is not
              valid for this socket's family (a.k.a., communication domain)
      @throws randolf::rex::xENOBUFS Insufficient memory
      @throws randolf::rex::xENOTSOCK Underlying socket file descriptor (handle)
              doesn't refer to a socket
 
      @returns sockaddr_storage structure
      @qualifier POSIX
      @qualifier TLS
      *///=========================================================================
      const std::shared_ptr<sockaddr_storage> getsockname() {
        std::shared_ptr sa = std::make_shared<sockaddr_storage>();
        socklen_t len = sizeof(sockaddr_storage);
        __rc_check(::getsockname(__socket_fd, (struct sockaddr*)sa.get(), &len));
        return sa;
      }; // -x- std::string getsockname -x-
 
      /*======================================================================*//**
      @brief
      Get socket name returns the name of the socket as a std::string object.
 
      @throws randolf::rex::xEAI_ADDRFAMILY if the address can't be determined
              (e.g., because the @c family doesn't utilize or support an address
              {or the format isn't known}
      @throws randolf::rex::xEAFNOSUPPORT Address family not implemented/supported
      @throws randolf::rex::xEBADF The underlying socket is not open
      @throws randolf::rex::xEFAULT Address structure/memory is not in a writable
              part of the user address space
      @throws randolf::rex::xEINVAL Address length is incorrect, or address is not
              valid for this socket's family (a.k.a., communication domain)
      @throws randolf::rex::xENOBUFS Insufficient memory
      @throws randolf::rex::xENOSPC Resulting address string exceeds maximum size
      @throws randolf::rex::xENOTSOCK Underlying socket file descriptor (handle)
              doesn't refer to a socket
 
      @returns string representation of socket name
      @qualifier TLS
      *///=========================================================================
      const std::string getsockname_ntop() {
        sockaddr_storage sa;
        socklen_t len = sizeof(sockaddr_storage);
        __rc_check(::getsockname(__socket_fd, (sockaddr*)&sa, &len));
        return inet_ntop(&sa);
      }; // -x- std::string getsockname_ntop -x-
 
      /*======================================================================*//**
      @brief
      Get socket option details in the form of an integer.
 
      Most options return an integer, with the remaining options returning a
      pointer to a structure wrapped in a std::shared_ptr (a C++ smart pointer that
      aids in the prevention of resource leaks); the primitive types int, u_int,
      and u_char are not wrapped in C++ smart pointers because returning them by
      value is more efficient since allocating memory for an entire structure isn't
      needed.
 
      @post
      It is up to the developer to know which return type is needed according to
      the socket option, otherwise an exception will likely be thrown -- in some
      cases where the wrong type will seem to work, this is due to the wrong type
      providing a minimally sufficient amount of memory for the storage of the
      resulting structure.
 
      @par Notes
      The returned values/structures are not marked as "const" because they may
      need to be modified for unforseen purposes.  Modifying the returend values or
      structures is fine because they are intended to be independent and are
      expected to have no direct impact on the rsocket's internal variables and
      structures.
 
      Templates in C++ aren't used here because they don't work properly for our
      needs due to neccesity to handle both fundamental types and structures; it
      turns out that mixing these is impossible when using the same function name,
      so this just doesn't work as well as we'd like it to.  (We may try to work on
      this again in the future as time permits to provide an additional method for
      obtaining socket options, but with the intention of never removing this
      current set of methods so as to ensure backward compatibility in the future.)
 
      @throws randolf::rex::xEBADF The underlying socket is not open
      @throws randolf::rex::xEFAULT Address structure/memory is not in a writable
              part of the user address space
      @throws randolf::rex::xEINVAL Address length is incorrect, or address is not
              valid for this socket's family (a.k.a., communication domain)
      @throws randolf::rex::xENOPROTOOPT Either the level or the specified optname
              is not supported
      @throws randolf::rex::xENOTSOCK Underlying socket file descriptor (handle)
              doesn't refer to a socket
 
      @returns socket option value
      @qualifier TLS
      *///=========================================================================
      int getsockopt_int(
      /// The level at which the option resides; typically @c SOL_SOCKET
      const int level,
      /// The name of the option, such as @c SO_REUSEADDR, @c SO_LINGER, etc.
      const int option) {
        int value = 0;
        __rc_check(::getsockopt(__socket_fd, level, option, &value, new socklen_t(sizeof(value))));
        if (__debug) __debug_sockopt("getsockopt(socket{0x", level, option, value);
        return value;
      }; // -x- int getsockopt_int -x-
 
      /*======================================================================*//**
      @brief
      Get socket option details in the form of an unsigned integer.
      @copydetails getsockopt_int(const int, const int)
      @returns socket option value
      @qualifier TLS
      *///=========================================================================
      u_int getsockopt_u_int(
      /// The level at which the option resides; typically @c SOL_SOCKET
      const int level,
      /// The name of the option, such as @c SO_REUSEADDR, @c SO_LINGER, etc.
      const int option) {
        u_int value = 0;
        __rc_check(::getsockopt(__socket_fd, level, option, &value, new socklen_t(sizeof(value))));
        if (__debug) __debug_sockopt("getsockopt(socket{0x", level, option, value);
        return value;
      }; // -x- u_int getsockopt_u_int -x-
 
      /*======================================================================*//**
      @brief
      Get socket option details in the form of an unsigned character.
      @copydetails getsockopt_int(const int, const int)
      @returns socket option value
      @qualifier TLS
      *///=========================================================================
      u_char getsockopt_u_char(
      /// The level at which the option resides; typically @c SOL_SOCKET
      const int level,
      /// The name of the option, such as @c SO_REUSEADDR, @c SO_LINGER, etc.
      const int option) {
        u_char value = 0;
        __rc_check(::getsockopt(__socket_fd, level, option, &value, new socklen_t(sizeof(value))));
        if (__debug) __debug_sockopt("getsockopt(socket{0x", level, option, value);
        return value;
      }; // -x- u_char getsockopt_u_char -x-
 
      /*======================================================================*//**
      @brief
      Get socket option details in the form of a structure.
      @copydetails getsockopt_int(const int, const int);
      @returns socket option structure wrapped in std::shared_ptr
      @qualifier TLS
      *///=========================================================================
      std::shared_ptr<linger> getsockopt_linger(
      /// The level at which the option resides; typically @c SOL_SOCKET
      const int level,
      /// The name of the option, such as @c SO_REUSEADDR, @c SO_LINGER, etc.
      const int option) {
        std::shared_ptr value = std::make_shared<linger>();
        __rc_check(::getsockopt(__socket_fd, level, option, value.get(), new socklen_t(sizeof(value))));
        if (__debug) __debug_sockopt("getsockopt(socket{0x", level, option, value.get());
        return value;
      }; // -x- linger getsockopt_linger -x-
 
      /*======================================================================*//**
      @copydoc getsockopt_linger(const int, const int)
      @qualifier TLS
      *///=========================================================================
      std::shared_ptr<timeval> getsockopt_timeval(
      /// The level at which the option resides; typically @c SOL_SOCKET
      const int level,
      /// The name of the option, such as @c SO_REUSEADDR, @c SO_LINGER, etc.
      const int option) {
        std::shared_ptr value = std::make_shared<timeval>();
        __rc_check(::getsockopt(__socket_fd, level, option, value.get(), new socklen_t(sizeof(value))));
        if (__debug) __debug_sockopt("getsockopt(socket{0x", level, option, value.get());
        return value;
      }; // -x- timeval getsockopt_timeval -x-
 
      /*======================================================================*//**
      @copydoc getsockopt_linger(const int, const int)
      @qualifier TLS
      *///=========================================================================
      std::shared_ptr<in_addr> getsockopt_in_addr(
      /// The level at which the option resides; typically @c SOL_SOCKET
      const int level,
      /// The name of the option, such as @c SO_REUSEADDR, @c SO_LINGER, etc.
      const int option) {
        std::shared_ptr value = std::make_shared<in_addr>();
        __rc_check(::getsockopt(__socket_fd, level, option, value.get(), new socklen_t(sizeof(value))));
        if (__debug) __debug_sockopt("getsockopt(socket{0x", level, option, value.get());
        return value;
      }; // -x- in_addr getsockopt_in_addr -x-
 
      /*======================================================================*//**
      @copydoc getsockopt_linger(const int, const int)
      @qualifier TLS
      *///=========================================================================
      std::shared_ptr<ip_mreq> getsockopt_ip_mreq(
      /// The level at which the option resides; typically @c SOL_SOCKET
      const int level,
      /// The name of the option, such as @c SO_REUSEADDR, @c SO_LINGER, etc.
      const int option) {
        std::shared_ptr value = std::make_shared<ip_mreq>();
        __rc_check(::getsockopt(__socket_fd, level, option, value.get(), new socklen_t(sizeof(value))));
        if (__debug) __debug_sockopt("getsockopt(socket{0x", level, option, value.get());
        return value;
      }; // -x- ip_mreq getsockopt_ip_mreq -x-
 
      /*======================================================================*//**
      @copydoc getsockopt_linger(const int, const int)
      @qualifier TLS
      *///=========================================================================
      std::shared_ptr<ip_mreq_source> getsockopt_ip_mreq_source(
      /// The level at which the option resides; typically @c SOL_SOCKET
      const int level,
      /// The name of the option, such as @c SO_REUSEADDR, @c SO_LINGER, etc.
      const int option) {
        std::shared_ptr value = std::make_shared<ip_mreq_source>();
        __rc_check(::getsockopt(__socket_fd, level, option, value.get(), new socklen_t(sizeof(value))));
        if (__debug) __debug_sockopt("getsockopt(socket{0x", level, option, value.get());
        return value;
      }; // -x- ip_mreq_source getsockopt_ip_mreq_source -x-
 
      /*======================================================================*//**
      @copydoc getsockopt_linger(const int, const int)
      @qualifier TLS
      *///=========================================================================
      std::shared_ptr<icmp6_filter> getsockopt_icmp6_filter(
      /// The level at which the option resides; typically @c SOL_SOCKET
      const int level,
      /// The name of the option, such as @c SO_REUSEADDR, @c SO_LINGER, etc.
      const int option) {
        std::shared_ptr value = std::make_shared<icmp6_filter>();
        __rc_check(::getsockopt(__socket_fd, level, option, value.get(), new socklen_t(sizeof(value))));
        if (__debug) __debug_sockopt("getsockopt(socket{0x", level, option, value.get());
        return value;
      }; // -x- icmp6_filter getsockopt_icmp6_filter -x-
 
      /*======================================================================*//**
      @copydoc getsockopt_linger(const int, const int)
      @qualifier TLS
      *///=========================================================================
      std::shared_ptr<sockaddr_in6> getsockopt_sockaddr_in6(
      /// The level at which the option resides; typically @c SOL_SOCKET
      const int level,
      /// The name of the option, such as @c SO_REUSEADDR, @c SO_LINGER, etc.
      const int option) {
        std::shared_ptr value = std::make_shared<sockaddr_in6>();
        __rc_check(::getsockopt(__socket_fd, level, option, value.get(), new socklen_t(sizeof(value))));
        if (__debug) __debug_sockopt("getsockopt(socket{0x", level, option, value.get());
        return value;
      }; // -x- sockaddr_in6 getsockopt_sockaddr_in6 -x-
 
      /*======================================================================*//**
      @copydoc getsockopt_linger(const int, const int)
      @qualifier TLS
      *///=========================================================================
      std::shared_ptr<ip6_mtuinfo> getsockopt_ip6_mtuinfo(
      /// The level at which the option resides; typically @c SOL_SOCKET
      const int level,
      /// The name of the option, such as @c SO_REUSEADDR, @c SO_LINGER, etc.
      const int option) {
        std::shared_ptr value = std::make_shared<ip6_mtuinfo>();
        __rc_check(::getsockopt(__socket_fd, level, option, value.get(), new socklen_t(sizeof(value))));
        if (__debug) __debug_sockopt("getsockopt(socket{0x", level, option, value.get());
        return value;
      }; // -x- ip6_mtuinfo getsockopt_ip6_mtuinfo -x-
 
      /*======================================================================*//**
      @copydoc getsockopt_linger(const int, const int)
      @qualifier TLS
      *///=========================================================================
      std::shared_ptr<ipv6_mreq> getsockopt_ipv6_mreq(
      /// The level at which the option resides; typically @c SOL_SOCKET
      const int level,
      /// The name of the option, such as @c SO_REUSEADDR, @c SO_LINGER, etc.
      const int option) {
        std::shared_ptr value = std::make_shared<ipv6_mreq>();
        __rc_check(::getsockopt(__socket_fd, level, option, value.get(), new socklen_t(sizeof(value))));
        if (__debug) __debug_sockopt("getsockopt(socket{0x", level, option, value.get());
        return value;
      }; // -x- ipv6_mreq getsockopt_ipv6_mreq -x-
 
      /*======================================================================*//**
      @copydoc getsockopt_linger(const int, const int)
      @qualifier TLS
      *///=========================================================================
      std::shared_ptr<group_req> getsockopt_group_req(
      /// The level at which the option resides; typically @c SOL_SOCKET
      const int level,
      /// The name of the option, such as @c SO_REUSEADDR, @c SO_LINGER, etc.
      const int option) {
        std::shared_ptr value = std::make_shared<group_req>();
        __rc_check(::getsockopt(__socket_fd, level, option, value.get(), new socklen_t(sizeof(value))));
        if (__debug) __debug_sockopt("getsockopt(socket{0x", level, option, value.get());
        return value;
      }; // -x- group_req getsockopt_group_req -x-
 
      /*======================================================================*//**
      @copydoc getsockopt_linger(const int, const int)
      @qualifier TLS
      *///=========================================================================
      std::shared_ptr<group_source_req> getsockopt_group_source_req(
      /// The level at which the option resides; typically @c SOL_SOCKET
      const int level,
      /// The name of the option, such as @c SO_REUSEADDR, @c SO_LINGER, etc.
      const int option) {
        std::shared_ptr value = std::make_shared<group_source_req>();
        __rc_check(::getsockopt(__socket_fd, level, option, value.get(), new socklen_t(sizeof(value))));
        if (__debug) __debug_sockopt("getsockopt(socket{0x", level, option, value.get());
        return value;
      }; // -x- group_source_req getsockopt_group_source_req -x-
 
      /*======================================================================*//**
      @copydoc getsockopt_linger(const int, const int)
      @qualifier TLS
      *///=========================================================================
      template<class T> std::shared_ptr<T> getsockopt_other(
      /// The level at which the option resides; typically @c SOL_SOCKET
      const int level,
      /// The name of the option, such as @c SO_REUSEADDR, @c SO_LINGER, etc.
      const int option) {
        std::shared_ptr value = std::make_shared<T>();
        __rc_check(::getsockopt(__socket_fd, level, option, value.get(), new socklen_t(sizeof(value))));
        if (__debug) __debug_sockopt_other("getsockopt_other(socket{0x", level, option, socklen_t(sizeof(value)));
        return value;
      }; // -x- T getsockopt_other -x-
 
      /*======================================================================*//**
      @brief
      Get underlying socket's address as a std::string, for sockets in one of the
      supported families:
 
         - AF_INET (IPv4)
         - AF_INET6 (IPv6)
         - AF_UNIX (Domain socket path)
         - AF_PACKET (Ethernet node/mac. address)
 
      @throws randolf::rex::xEAI_ADDRFAMILY if the address can't be determined
              (e.g., because the @c family doesn't utilize or support an address
              {or the format isn't known}
      @throws randolf::rex::xEAFNOSUPPORT Address family not implemented/supported
      @throws randolf::rex::xENOSPC Resulting address string exceeds maximum size
 
      @returns string representation of underlying socket's address
      @see inet_ntop(sockaddr_storage*) static method
      @qualifier POSIX
      @qualifier TLS
      *///=========================================================================
      const std::string inet_ntop() { return inet_ntop((sockaddr_storage*)&__socket_addr); } // -x- std::string inet_ntop -x-
 
      /*======================================================================*//**
      @brief
      Get specified "sockaddr_storage" structure's address as a std::string, for
      sockets in one of the supported families:
 
         - AF_INET (IPv4)
         - AF_INET6 (IPv6)
         - AF_UNIX (Domain socket path)
         - AF_PACKET (Ethernet node/mac. address)
 
      @throws randolf::rex::xEAI_ADDRFAMILY if the address can't be determined
              (e.g., because the @c family doesn't utilize or support an address
              {or the format isn't known}
      @throws randolf::rex::xEAFNOSUPPORT Address family not implemented/supported
      @throws randolf::rex::xENOSPC Resulting address string exceeds maximum size
 
      @returns string representation of underlying socket's address
      @see inet_ntop() non-static method
      @qualifier POSIX
      @qualifier TLS
      *///=========================================================================
      static const std::string inet_ntop(
      /// Source structure that [should] contain address data
      sockaddr_storage* sa) {
        std::string str;
        switch (sa->ss_family) {
          case AF_INET: // IPv4 address
            {
              char ntop[sizeof(sockaddr_in)]{0};
              const char* rc = ::inet_ntop(AF_INET, &(((struct sockaddr_in *)sa)->sin_addr), ntop, sizeof(ntop));
              str = std::string(ntop);
            }
            break;
          case AF_INET6: // IPv6 address
            { // Debug
              char ntop[sizeof(sockaddr_in6)]{0};
              const char* rc = ::inet_ntop(AF_INET6, &(((struct sockaddr_in6 *)sa)->sin6_addr), ntop, sizeof(ntop));
              str = std::string(ntop);
            }
            break;
          case AF_UNIX: // UNIX (path) domain socket
            str = std::string(((struct sockaddr_un *)sa)->sun_path);
            break;
          // AF_LINK is not supported at this time due to lack of clarity on obtaining and presenting the address
          // case /*AF_LINK* /18: // Link layer interface (arp)
          //  break;
          case AF_PACKET: // Packet (ethernet) address (packet capturing)
            str = to_mac(((struct sockaddr_ll *)sa)->sll_addr);
            break;
          default: // Everything else
            throw randolf::rex::xEAI_ADDRFAMILY("EAI_ADDRFAMILY");
        } // -x- switch family -x-
        return str;
      }; // -x- std::string inet_ntop -x-
 
      /*======================================================================*//**
      @brief
      Find out whether an internal read buffer was allocated (this is most likely
      triggered by an attempt to read a line of text).
      @note
      The buffer_size() methods report on how much memory was allocated for the
      internal read buffer or to set its size (in bytes).
      @returns TRUE = an internal read buffer was allocated
      @returns FALSE = an internal read buffer was not allocated
      @see buffer_size
      @see buffer_size(const size_t nbytes)
      @qualifier TLS
      *///=========================================================================
      const bool is_buffered() noexcept { return __buffer != nullptr; }; // -x- bool is_buffered -x-
 
      /*======================================================================*//**
      @brief
      Find out whether the underlying socket is not open (which may not be the same
      as specifically "closed" since a newly instantiated empty socket begins in a
      "not open" state despite the underlying socket not explicitly having been
      closed).
      @returns TRUE = not open
      @returns FALSE = open
      @see is_open()
      @qualifier TLS
      *///=========================================================================
      const bool is_closed() noexcept { return !__socket_open; }; // -x- bool is_closed -x-
 
      /*======================================================================*//**
      @brief
      Find out whether the underlying socket is connected with/to an endpoint.
      @returns TRUE = open
      @returns FALSE = not open
      @qualifier TLS
      *///=========================================================================
      const bool is_connected() noexcept { return __socket_connected; }; // -x- bool is_connected -x-
 
      /*======================================================================*//**
      @brief
      Find out whether the default byte order for this host is LSB (small endian).
      @note
      If you're trying to choose which endian type to use when designing a new
      internet protocol, then big endian is normally the better option.  However,
      if your new protocol will only be used by hardware that all share the same
      endianness, then that endianness is probably the more optimal option since it
      will translate to an overall lesser consumption of CPU cycles by reducing or
      eliminating endianness conversions.
      @returns TRUE = LSB (little endian)
      @returns FALSE = MSB (big endian / network byte order)
      @qualifier TLS
      *///=========================================================================
      const bool is_endian_lsb() noexcept { return !__endian_is_msb; }; // -x- bool is_endian_lsb -x-
 
      /*======================================================================*//**
      @brief
      Find out whether the default byte order for this host is MSB (big endian).
      @note
      Big endian is the standard known as "network byte order" that's also used in
      various header fields in internet packets.
      @n@n
      If you're trying to choose which endian type to use when designing a new
      internet protocol, then big endian is normally the better option.  However,
      if your new protocol will only be used by hardware that all share the same
      endianness, then that endianness is probably the more optimal option since it
      will translate to an overall lesser consumption of CPU cycles by reducing or
      eliminating endianness conversions.
      @returns TRUE = MSB (big endian / network byte order)
      @returns FALSE = LSB (little endian)
      @qualifier TLS
      *///=========================================================================
      const bool is_endian_msb() noexcept { return __endian_is_msb; }; // -x- bool is_endian_msb -x-
 
      /*======================================================================*//**
      @brief
      Find out if the EoL adoption policy is enabled for the @ref recvline() method
      (see the @ref eol_adoption method to find out how the dynamically-detected
      EoL sequence gets adopted, and under what conditions).
      @returns TRUE = EoL adoption is enabled
      @returns FALSE = EoL adoption is disabled
      @see eol
      @see eol_adoption
      @see eol_index
      @see recvline
      @see sendline
      @see send_eol
      @qualifier TLS
      *///=========================================================================
      const bool is_eol_adoption() noexcept {
        return __eol_adoption;
      }; // -x- bool is_eol_adoption -x-
 
      /*======================================================================*//**
      @brief
      Find out if the EoL substitution policy is enabled for the @ref printf(),
      @ref printfline(), @ref vprintf(), and @ref vprintfline() methods.
      @returns TRUE = EoL substitution is enabled
      @returns FALSE = EoL substitution is disabled
      @see eol
      @see eol_fix_printf
      @see printf
      @see printfline
      @see sendline
      @see send_eol
      @see vprintf
      @see vprintfline
      @qualifier TLS
      *///=========================================================================
      const bool is_eol_fix_printf() noexcept {
        return __eol_fix_printf;
      }; // -x- bool is_eol_fix_printf -x-
 
      /*======================================================================*//**
      @brief
      Find out whether the underlying socket is open.
      @returns TRUE = open
      @returns FALSE = not open
      @see is_closed()
      @qualifier TLS
      *///=========================================================================
      const bool is_open() noexcept { return __socket_open; }; // -x- bool is_open -x-
 
      /*======================================================================*//**
      @brief
      Find out whether encrypted communications is enabled or disabled.
      @returns TRUE = encrypted communications is enabled
      @returns FALSE = encrypted communications is disabled
      @see tls(bool, TLS_FLAGS)
      @qualifier TLS
      *///=========================================================================
      const bool is_tls() noexcept { return __tls; }; // -x- bool is_tls -x-
 
      /*======================================================================*//**
      @brief
      Find out whether TLS context is in TLS_CLIENT mode.
      @returns TRUE = TLS context is in TLS_CLIENT mode
      @returns FALSE = TLS context is in TLS_SERVER mode
      @see TLS_CLIENT
      @see tls()
      @qualifier TLS
      *///=========================================================================
      const bool is_tls_client_mode() noexcept { return !__tls_server_mode; }; // -x- bool is_tls_client_mode -x-
 
      /*======================================================================*//**
      @brief
      Find out whether egress from encryption (to unencrypted mode) is allowed.
      @returns TRUE = egress from encrypted communications is allowed
      @returns FALSE = egress from encrypted communications is not allowed
      @see TLS_NO_EGRESS
      @see tls()
      @qualifier TLS
      *///=========================================================================
      const bool is_tls_egress_okay() noexcept { return __tls_egress; }; // -x- bool is_tls_egress_okay -x-
 
      /*======================================================================*//**
      @brief
      Find out whether encrypted communications is exclusive.
      @returns TRUE = encrypted communications is exclusive
      @returns FALSE = encrypted communications is not exclusive
      @see tls()
      @qualifier TLS
      *///=========================================================================
      const bool is_tls_exclusive() noexcept { return __tls_exclusive; }; // -x- bool is_tls_exclusive -x-
 
      /*======================================================================*//**
      @brief
      Find out whether ingress to encryption (from unencrypted mode) is allowed.
      @returns TRUE = ingress to encrypted communications is allowed
      @returns FALSE = ingress to encrypted communications is not allowed
      @see TLS_NO_INGRESS
      @see tls()
      @qualifier TLS
      *///=========================================================================
      const bool is_tls_ingress_okay() noexcept { return __tls_ingress; }; // -x- bool is_tls_ingress_okay -x-
 
      /*======================================================================*//**
      @brief
      Find out whether TLS context is in TLS_SERVER mode.
      @returns TRUE = TLS context is in TLS_SERVER mode
      @returns FALSE = TLS context is in TLS_CLIENT mode
      @see TLS_SERVER
      @see tls()
      @qualifier TLS
      *///=========================================================================
      const bool is_tls_server_mode() noexcept { return __tls_server_mode; }; // -x- bool is_tls_server_mode -x-
 
      /*======================================================================*//**
      @brief
      Find out whether SNI (Server Name Identifier) is enabled (configured, which
      implies that an internal callback function was also set up).
      @returns TRUE = SNI is enabled
      @returns FALSE = SNI is disabled
      @see tls_sni()
      @qualifier TLS
      *///=========================================================================
      const bool is_tls_sni() noexcept { return __tls_sni != nullptr; }; // -x- bool is_tls_sni -x-
 
      /*======================================================================*//**
      @brief
      Find out whether SNI (Server Name Identifier) was matched, which means that
      we're using one of the supplementary TLS certificates that are included in
      the associated @ref rsocket_sni object as separate TLS contexts.
 
      When this method returns @c TRUE, it means the @c OpenSSL callback (which
      occurs during the TLS handshake process) completed the TLS handshake with one
      of the TLS certificates that's included in this @c rsocket's @ref rsocket_sni
      object instead of the primary TLS certificate assigned to this @c rsocket,
      and this @c rsocket is using the respective TLS context instead of the
      primary (default) one.
      @returns TRUE = SNI was matched
      @returns FALSE = SNI wasn't matched
      @see name_sni
      @see tls_sni
      @qualifier TLS
      *///=========================================================================
      const bool is_tls_sni_match() noexcept { return __tls_sni_match; }; // -x- bool is_tls_sni_match -x-
 
      /*======================================================================*//**
      @brief
      Enable listening mode for this rsocket to prepare it to accept() new inbound
      connections.
 
      The backlog defaults to SOMAXCONN (4096 on Linux, and 128 on older systems),
      which is common on most systems.  If a higher value is supplied that exceeds
      @c kern.somaxconn, the kernel will automatically override the backlog with
      the value stored in @c kern.somaxconn without generating any errors or
      warnings.
 
      @throws randolf::rex::xEADDRINUSE Address and/or port number already in use
      @throws randolf::rex::xEADDRINUSE No ephemeral ports are available for
              assignment to unbound socket (should be randolf::rex::xEADDRNOTAVAIL,
              but it really isn't)
      @throws randolf::rex::xEBADF The underlying socket is not open
      @throws randolf::rex::xENOTSOCK Underlying socket file descriptor (handle)
              doesn't refer to a socket
      @throws randolf::rex::xEOPNOTSUPP Underlying socket is no of type SOCK_STREAM
      @returns The same rsocket object so as to facilitate stacking
      @see accept()
      @see accept_sp()
      @see accept4()
      @see accept4_sp()
      @see backlog()
      @see bind()
      @qualifier POSIX
      @qualifier TLS
      *///=========================================================================
      rsocket* listen(
      /// Backlog queue size (0 = uses rsocket's default; see @ref backlog for more
      /// details about this); specifying a non-zero backlog also updates rocket's
      /// internal default (SOMAXCONN is 4096 on Linux, and 128 on older systems)
      int backlog = 0) {
        if (__debug) debug("listen(socket{0x" + randolf::rtools::to_hex(__socket_fd) + "}"
                         + ", " + std::to_string(backlog)
                         + ");");
 
        // --------------------------------------------------------------------------
        // Use rsocket's default backlog if not specified, otherwise update it
        // with the new value specified here.
        // --------------------------------------------------------------------------
        if (backlog = 0) backlog = __socket_backlog;
        else __socket_backlog = backlog;
 
        // --------------------------------------------------------------------------
        // Configure underlying socket to queue up to "backlog" inbound connections.
        // --------------------------------------------------------------------------
        __rc_check(::listen(__socket_fd, backlog));
 
        return this;
      }; // -x- rsocket* listen -x-
 
      /*======================================================================*//**
      @brief
      Convert an IPv4 address, IPv6 address, ethernet packet, or UNIX domain
      socket to a sockaddr_storage structure.
 
      If service_name is an absolute path (that begins with a "/" charcter) and the
      family is set to AF_UNSPEC (the default), then the resulting family will be
      set to AF_UNIX.
 
      @par Notes    
      This method utilizes the results of getaddrinfo().
 
      Other families like AF_LINK and AF_PACKET should work, but haven't been
      tested thoroughly.  The additional support we provide for IPv4 and IPv6
      addresses is to copy the port number into the resulting structure (as a
      convenience).
 
      @post
      The resulting sockaddr_storage structure is wrapped in std::shared_ptr (a C++
      smart pointer that aids in the prevention of resource leaks).
 
      @par Threads
      This method is thread-safe.
 
      @throws randolf::rex::xEAI_ADDRFAMILY If specified network host doesn't have
              any addresses in the specified address family
      @throws randolf::rex::xEAI_AGAIN Temporary failure code from DNS server (try
              again later)
      @throws randolf::rex::xEAI_BADFLAGS Invalid flags in @c hints.ai_flags (or
              `hints.ai_flags` included @c AI_CANONNAME with @c nullptr as @c name)
      @throws randolf::rex::xEAI_FAIL Permanent failure code from DNS server
      @throws randolf::rex::xEAI_FAMILY The specified family is not supported
      @throws randolf::rex::xEAI_MEMORY Out of memory
      @throws randolf::rex::xEAI_NONAME If node_name is nullptr or an empty string
      @throws randolf::rex::xEAI_SERVICE The specified service is not available
              for the specified socket type
      @throws randolf::rex::xEAI_SOCKTYPE The specified socket type is not
              supported
      @throws randolf::rex::xEAI_SYSTEM Other system error (use errno to determine
              what the error is, then run use @ref randolf::rex::rex::mk_exception
              to throw the correct exception)
 
      @returns sockaddr_storage structure
      @see getsockaddr
      *///=========================================================================
      static std::shared_ptr<sockaddr_storage> mk_sockaddr_storage(
      /// IP address or UNIX domain socket address to convert
      const char* node_name,
      /// Port number (or service name used by some other families)
      const char* service_name = nullptr,
      /// Optional pointer to a helpful addrinfo structure
      const addrinfo* hints = nullptr) {
 
        // --------------------------------------------------------------------------
        // Initial sanity checks.
        // --------------------------------------------------------------------------
        if (node_name == nullptr) randolf::rex::mk_exception("", EAI_NONAME); // if (node_name == nullptr && service_name == nullptr) randolf::rex::mk_exception("", EAI_NONAME);
 
        // --------------------------------------------------------------------------
        // Handle any special cases.
        // --------------------------------------------------------------------------
        switch (hints == nullptr ? AF_UNSPEC : hints->ai_family) { // Default to AF_UNSPEC in the absence of hints
          case AF_UNSPEC:
            if (node_name[0] != '/') break;
            // Next entry MUST be "case AF_UNIX" for this fall-through to work
          case AF_UNIX:
            {
              // For some unknown reason, clang++ can't compile this line that
              // g++ has absolutely no trouble with at all:
              //    std::shared_ptr sa = std::make_shared<sockaddr_storage>(AF_UNIX);
              // So, after wasting more than a year trying to figure out what the
              // hundreds of lines of cryptic errors meant, I eventually gave up
              // on clang++ for being such a dumbfuck, and used this work-around:
              std::shared_ptr sa = std::make_shared<sockaddr_storage>();
                              sa->ss_family = AF_UNIX;
              std::strcpy(((struct sockaddr_un *)sa.get())->sun_path, node_name); // Copy path
              return sa;
            }
            break;
        } // -x- switch hints->family -x-
 
        // --------------------------------------------------------------------------
        // Acquire addrinfo[] linked-list array.
        // --------------------------------------------------------------------------
        addrinfo* __addr_result; // This is temporary
//std::cout << "   Making socket structure... node_name=" << node_name << " ...hints: ai_family=" << hints->ai_family << " ai_socktype=" << hints->ai_socktype << " ai_flags=" << hints->ai_flags << std::endl;
        randolf::rex::mk_exception("", getaddrinfo(node_name,
                                                   service_name,
                                                   hints,
                                                   &__addr_result));
 
        // --------------------------------------------------------------------------
        // Find first valid addrinfo[] array by trying to open a socket with it.
        // --------------------------------------------------------------------------
        for (addrinfo* ar = __addr_result; ar != nullptr; ar = ar->ai_next) {
//std::cout << "   ... ai_family=" << ar->ai_family << " ai_socktype=" << ar->ai_socktype << " ai_flags=" << ar->ai_flags << std::endl; // *******************
// ***************************** TODO:  Make sure this loop is working properly
        } // -x- for ar -x-
//std::cout << "   !!! ai_family=" << __addr_result->ai_family << std::endl; // *******************
 
        // --------------------------------------------------------------------------
        // Copy the address to "sa" and return it.  The "addr" data for IPv4 and IPv6
        // addresses include the TCP/UDP port number (service) in first two bytes as
        // as an unsigned integer (u_int16), followed immediately by the IP address.
        //
        // We're taking the first record only.  We assume that hints{} is defined on
        // an as-needed basis.
        //
        // Note: AF_LINK and AF_PACKET are not widely supported, but we've made an
        //       effort to accomodate their usage.
        // --------------------------------------------------------------------------
        std::shared_ptr sa = std::make_shared<sockaddr_storage>();
        switch (__addr_result->ai_family) {
          case AF_INET: // IPv4 address
            std::memcpy(sa.get(), __addr_result->ai_addr, sizeof(sockaddr_in));
            break;
          case AF_INET6: // IPv6 address
            std::memcpy(sa.get(), __addr_result->ai_addr, sizeof(sockaddr_in6));
            break;
          /* // We're handling this earlier as a special case: TODO: Move special handling to here
          case AF_UNIX: // UNIX (path) domain socket
            std::memcpy(sa.get(), __addr_result->ai_addr, sizeof(sockaddr_un));
            break;
          */
          case /*AF_LINK*/18: // Link layer interface (arp)
            std::memcpy(sa.get(), __addr_result->ai_addr, sizeof(sockaddr_dl));
            break;
          case AF_PACKET: // Packet (ethernet) address (packet capturing)
            std::memcpy(sa.get(), __addr_result->ai_addr, sizeof(sockaddr_ll));
            break;
          default: // Everything else
            std::memcpy(sa.get(), __addr_result->ai_addr, sizeof(sockaddr_storage));
        } // -x- switch family -x-
        freeaddrinfo(__addr_result); // We don't need this anymore
        return sa;
      }; // -x- sockaddr_storage* mk_sockaddr_storage -x-
 
      /*======================================================================*//**
      @copydoc mk_sockaddr_storage(const char*, const char*, const addrinfo*)
      *///=========================================================================
      static std::shared_ptr<sockaddr_storage> mk_sockaddr_storage(
      /// IP address or UNIX domain socket address to convert
      const char* node_name,
      /// Port number
      const u_int16_t service_name,
      /// Optional pointer to a helpful addrinfo structure
      const addrinfo* hints = nullptr) {
        std::string port = std::to_string(service_name);
        return mk_sockaddr_storage(node_name, port.c_str(), hints);
      }; // -x- sockaddr_storage* mk_sockaddr_storage -x-
 
      /*======================================================================*//**
      @copydoc mk_sockaddr_storage(const char*, const char*, const addrinfo*)
      *///=========================================================================
      static std::shared_ptr<sockaddr_storage> mk_sockaddr_storage(
      /// IP address or UNIX domain socket address to convert
      const std::string node_name,
      /// Port number
      const u_int16_t service_name,
      /// Optional pointer to a helpful addrinfo structure
      const addrinfo* hints = nullptr) {
        std::string port = std::to_string(service_name);
        return mk_sockaddr_storage(node_name.c_str(), port.c_str(), hints);
      }; // -x- sockaddr_storage* mk_sockaddr_storage -x-
 
      /*======================================================================*//**
      @copydoc mk_sockaddr_storage(const char*, const char*, const addrinfo*)
      *///=========================================================================
      static std::shared_ptr<sockaddr_storage> mk_sockaddr_storage(
      /// IP address or UNIX domain socket address to convert
      const std::string node_name,
      /// Port number (or server name used by some other families)
      const std::string service_name,
      /// Optional pointer to a helpful addrinfo structure
      const addrinfo* hints = nullptr) {
        return mk_sockaddr_storage(node_name.c_str(), service_name.c_str(), hints);
      }; // -x- sockaddr_storage* mk_sockaddr_storage -x-
 
      /*======================================================================*//**
      @brief
      Specify a name for this rsocket.
 
      This is an arbitrary name that is entirely optional, and should be regarded
      as similar to the naming of threads.
      @returns The same rsocket object so as to facilitate stacking
      *///=========================================================================
      rsocket* name(
      /// Name to assign to this @c rsocket
      const std::string name) noexcept {
  //      const std::lock_guard<std::mutex> lock(__name);
        __name = name;
        return this;
      }; // -x- rsocket* name -x-
 
      /*======================================================================*//**
      @brief
      Find out what this rsocket's name is.
 
      The built-in SNI mechanism will overwrite this data to indicate the hostname
      that was specified by the TLS-encrypted endpoint that triggered an internal
      SNI callback -- use the @ref name_sni() method to find out which hostname is
      actually being used by TLS.
      @returns The name of this rsocket (or an empty @c std::string if this rsocket
               doesn't have a name)
      @see name_sni
      @see tls_sni
      *///=========================================================================
      std::string name() noexcept {
  //      const std::lock_guard<std::mutex> lock(__name);
        return __name;
      }; // -x- std::string name -x-
 
      /*======================================================================*//**
      @brief
      Find out what this rsocket's actual TLS SNI hostname is.
 
      This is the exact - or closest-matching (in the case of wildcards) - hostname
      associated with an actual TLS certificate that was provided in the configured
      @ref rsocket_sni object.
      @returns The hostname associated with the TLS certificate selected by SNI
      @see name
      @see tls_sni
      @qualifier TLS
      *///=========================================================================
      std::string name_sni() noexcept {
        return __name_sni;
      }; // -x- std::string name_sni -x-
 
      /*======================================================================*//**
      @brief
      Get socket I/O statistics from internally-tracked socket I/O counters.
 
      The number of bytes transmitted and received is tracked internally, so that
      the information can be used later in logging.  These statistics are available
      at all times, but for logging purposes it makes the most sense to copy this
      information after the rsocket is closed, at which time the final statistics
      will continue to be available until the rsocket's destructor takes over.
 
      @par Threads
      This method is threadsafe.
      @returns rsocket_io wrapped in a std::shared_ptr object to help ease memory
               management efforts
      @see net_io_final
      @see net_io_update
      @see printf
      @qualifier TLS
      *///=========================================================================
      std::shared_ptr<rsocket_io> net_io() noexcept {
        std::shared_ptr stats = std::make_shared<rsocket_io>();
        stats->bytes_rx = __bytes_rx;
        stats->bytes_tx = __bytes_tx;
        stats->crypt_rx = __crypt_rx;
        stats->crypt_tx = __crypt_tx;
        stats->is_final = false;
        return stats;
      }; // -x- std::shared_ptr<rsocket_io> net_io -x-
 
      /*======================================================================*//**
      @brief
      Get socket I/O statistics from internally-tracked socket I/O counters as a
      pre-formatted std::string object.
 
      The number of bytes transmitted and received is tracked internally, so that
      the information can be used later in logging.  These statistics are available
      at all times, but for logging purposes it makes the most sense to copy this
      information after the rsocket is closed, at which time the final statistics
      will continue to be available until the rsocket's destructor takes over.
 
      @par Formatting
      The format string may contain any characters, with only instances of the
      following case-sensitive command sequences to be interpolated accordingly
      (invalid commands will be ignored and will remain in place, unmodified):
 
      <table cellpadding=8 cellspacing=0 border=1>
        <tr><th>Command</th><th>Replacement text</th><th>Data source (@ref rsocket_io)</th></tr>
        <tr><td>$$</td><td>One dollar sign ("$")</td><td>@e N/A</td></tr>
        <tr><td>$aR</td><td>Total (all) bytes received</td><td>bytes_rx @c + crypt_rx</td></tr>
        <tr><td>$aT</td><td>Total (all) bytes transmitted</td><td>bytes_tx @c + crypt_tx</td></tr>
        <tr><td>$bR</td><td>Unencrypted bytes received</td><td>bytes_rx</td></tr>
        <tr><td>$bT</td><td>Unencrypted bytes transmitted</td><td>bytes_tx</td></tr>
        <tr><td>$cR</td><td>Encrypted bytes recevied</td><td>crypt_rx</td></tr>
        <tr><td>$cT</td><td>Encrypted bytes transmitted</td><td>crypt_tx</td></tr>
        <tr><th>Command</th><th>Replacement text</th><th>Data source (@ref rsocket_io)</th></tr>
      </table>
 
      Why do we use dollar signs instead of percent symbols, like other formatting
      functions like printf() does?  So that the format string won't be in conflict
      with any percent-prefixed commands in printf() and similar funcions.  This
      means that a printf() format string can be put through a first pass here to
      get the needed statistics interpolated into the needed positions.
 
      @par Threads
      This method is threadsafe.
      @returns An interpolated format string as an std::string object.
      @see net_io_final
      @see net_io_update
      @see printf
      @qualifier TLS
      *///=========================================================================
      std::string net_io(
      /// Format string
      const char* format,
      /// Length of format string (in bytes), or 0 to auto-detect length if format string is an ASCIIZ string
      size_t len = 0,
      /// Pointer to an @ref rsocket_io structure to read the statistics from (nullptr = use internal copy of current statistics)
      // TODO:  Convert this to a static method and create a new method without the "len" parameter that just calls the static method with the pointer to the internal "addr" buffer (this will make it easier to call this method in a static fashion later without incurring any of the overhead of instantiation)
      rsocket_io* addr = nullptr) noexcept {
 
        // --------------------------------------------------------------------------
        // Measure size of format string if an ASCIIZ string was indicated.
        // --------------------------------------------------------------------------
        if (len == 0) len = std::strlen(format);
 
        // --------------------------------------------------------------------------
        // Internal variables.
        // --------------------------------------------------------------------------
        rsocket_io* data        = addr == nullptr ? net_io().get() : addr; // Copy current statistics so we have a snapshot instead of a set of possibly-changing statistics to work with
        std::string stats;               // Formatted result
        ulong       val;                 // Value (to be inserted)
        char        c;                   // Current character
        std::string cmd;                 // Accumulated command (may be subsituted)
        bool        flag_commas = false; // Thousands separators flag
        bool        flag_right  = false; // Flush-right flag
 
        // --------------------------------------------------------------------------
        // Process format string and build resulting formatted stats string.
        //
        // This is designed to be fast, and I'm taking huge shortcuts here since the
        // commands are all the same size (except for the first one, which is only
        // two dollar sign characters).  Processing in this loop should be quite fast
        // compared to using library functions to search for dollar sign characters
        // since data needs to be copied anyway -- why run a loop over the text twice
        // when can get away with doing it faster by doing it only once?  This is an
        // optimized approach, although it probably could be even faster by not using
        // std::string for temporary command storage (there are other ways to do this
        // but I think this should suffice for now since it isn't expected to be used
        // very often).
        // --------------------------------------------------------------------------
        for (int i = 0; i < len; i++) {
 
          // --------------------------------------------------------------------------
          // First character (potentially).
          // --------------------------------------------------------------------------
          if ((c = format[i]) != '$') { // Not a dollar sign -- save it and move on
            stats.push_back(c);
            continue;
          } // -x- if !$ -x-
          cmd = c; // Start building up the command string
 
          // --------------------------------------------------------------------------
          // Second character:  Part 1 of 2
          //
          // TODO:  Add support for "," commas, and "r" right-alignment.
          // --------------------------------------------------------------------------
          if (++i == len) continue; // End of format string, so we're done
          cmd.push_back(c = format[i]);
          if (c == '$') { // Consume the previous dollar sign so that $$ turns into $
            stats.push_back(c); // Add $ to stats string (we're only keeping one dollar sign)
            continue;
          } // -x- if $ -x-
          flag_commas = flag_right = false; // Reset these flags for a clean start
 
          // --------------------------------------------------------------------------
          // Flag checks:
          //    , = Include thousands separators (commas)
          //    r = Flush right (leading spaces will be added)
          // --------------------------------------------------------------------------
          net_io_flags_loop:
          if (c == ',') {
            if (++i == len) continue; // End of format string, so we're done
            cmd.push_back(c = format[i]);
            flag_commas = true;
            goto net_io_flags_loop;
          } else if (c == 'r') {
            if (++i == len) continue; // End of format string, so we're done
            cmd.push_back(c = format[i]);
            flag_right = true;
            goto net_io_flags_loop;
          } // -x- if [,r] -x-
          // TODO:  Do more
 
          // --------------------------------------------------------------------------
          // Second character:  Part 1 of 2
          // --------------------------------------------------------------------------
          if (c < 'a' || c > 'c') { // Not a, b, or c, so treat it as a regular character
            stats.append(cmd); // Add invalid command string to stats string (we're effectively ignoring it)
            continue;
          } // -x- if !~[abc] -x-
 
          // --------------------------------------------------------------------------
          // Third character.
          // --------------------------------------------------------------------------
          if (++i == len) continue; // End of format string, so we're done
          cmd.push_back(c = format[i]);
          if (c != 'R' && c != 'T') { // Not R or T, so treat it as a regular character
            stats.append(cmd); // Add invalid command string to stats string (we're effectively ignoring it)
            continue;
          } // -x- if !~[RT] -x-
 
          // --------------------------------------------------------------------------
          // Command processing.  If the command is valid, then it will be interpolated
          // with its expected result by replacing it with the resulting value.
          // --------------------------------------------------------------------------
  //std::cout << "[" << cmd << "]"; // Debug
               if (cmd.ends_with("aR")) val = data->bytes_rx + data->crypt_rx;
          else if (cmd.ends_with("aT")) val = data->bytes_tx + data->crypt_tx;
          else if (cmd.ends_with("bR")) val = data->bytes_rx                 ;
          else if (cmd.ends_with("bT")) val = data->bytes_tx                 ;
          else if (cmd.ends_with("cR")) val =                  data->crypt_rx;
          else if (cmd.ends_with("cT")) val =                  data->crypt_tx;
          else                          { stats.append(cmd); continue; } // This is wrong, so ignore it
 
          // --------------------------------------------------------------------------
          // Re-use cmd to generate formatted value.
          // --------------------------------------------------------------------------
          cmd.clear();
          cmd.resize(21); // Maximum length without commas (plus character zero):  18446744073709551615
          cmd.resize(sprintf(cmd.data(), flag_right ? "%20lu" : "%lu", val)); // The ::sprintf function can't use cmd.c_str() here
          if (flag_commas) cmd = randolf::rtools::insert_commas(cmd.c_str()); // Insert commas (this makes the string longer)
 
          // --------------------------------------------------------------------------
          // Convert to std::string and add to the stats string.
          // --------------------------------------------------------------------------
          stats.append(cmd);
 
        }; // -x- for i -x-
 
        return stats;
      }; // -x- std::string net_io -x-
 
      /*======================================================================*//**
      @brief
      Where the destructor should save final I/O statistics before this rsocket's
      resources are completely freed/deallocated.
      @attention
      Developers should take care to check that the @ref rsocket_io::is_final flag
      is set to @c TRUE prior to relying on the results of the @ref rsocket_io data
      since there's no guarantee that the destructor will necessarily be executed
      in a timely manner (this flag is set last, after all other statistics are
      copied into the structure while in a mutex-locked state).
      @returns The same rsocket object so as to facilitate stacking
      @see ~rsocket
      @see net_io
      @see net_io_update
      @see printf
      @qualifier TLS
      *///=========================================================================
      rsocket* net_io_final(
      /// Pointer to @ref rsocket_io structure (nullptr = disabled)
      rsocket_io* addr) noexcept {
        __io_final_addr = addr;
        return this;
      }; // -x- rsocket* net_io_final -x-
 
      /*======================================================================*//**
      @brief
      Where the destructor should save current I/O statistics.
      @attention
      Statistics are copied into the structure while in a mutex-locked state, but
      the copy itself is not an overall atomic snapshot of the I/O statistics even
      though each statistic is copied atomically.  This means that the actual
      statistics could be slightly different if updates occur independently (e.g.,
      due to activities in a different thread), but this likely won't matter since
      the anticipated use for these statistics is to display or otherwise present
      general statistical information to a user at regular intervals.
      @returns The same rsocket object so as to facilitate stacking
      @see ~rsocket
      @see net_io
      @see net_io_final
      @see printf
      @qualifier TLS
      *///=========================================================================
      rsocket* net_io_update(
      /// Pointer to @ref rsocket_io structure (nullptr = do nothing)
      rsocket_io* addr) noexcept {
 
        // --------------------------------------------------------------------------
        // Copy statistics to final location.  (We do this last in case there's an
        // issue with locking; there shouldn't be, but if there is then at least we
        // already we're not inadvertently hanging on to resources at this point that
        // need to be freed/closed anyway.)
        // --------------------------------------------------------------------------
        if (addr != nullptr) {
          addr->lock();
          addr->bytes_rx = __bytes_rx;
          addr->bytes_tx = __bytes_tx;
          addr->crypt_rx = __crypt_rx;
          addr->crypt_tx = __crypt_tx;
          addr->is_final = false;
          addr->unlock();
        } // -x- if addr -x-
 
        return this;
      }; // -x- rsocket* net_io_update -x-
 
      /*======================================================================*//**
      @brief
      Return the number of bytes pending to be received, without actually receiving
      any data.
 
      @note
      When using TLS, OpenSSL may not report all the pending data, but this is
      resolved here by also adding the total amount of pending raw data that is not
      currently being processed in the current record by OpenSSL, even when "read
      ahead" is enabled.
 
      @throws randolf::rex::xEBADF The underlying socket is not open
      @throws randolf::rex::xEFAULT Address structure/memory is not in a writable
              part of the user address space
      @throws randolf::rex::xEINVAL Socket is not in @ref listen() mode or the
      @throws randolf::rex::xENOTTY The underlying socket is not associated with a
              character special device, or the specified operation does not apply
              to the kind of object that the file descriptor fd references (this
              exception will probably never occur unless the underlying socket
              handle was arbitrarily replaced with the type of handle that can
              cause this error to occur)
 
      @returns Total number of bytes pending (0 = none)
      @see eos
      @see recv
      @qualifier TLS
      *///=========================================================================
      ulong pending() {
        if (__debug) debug("pending(socket{0x" + randolf::rtools::to_hex(__socket_fd) + "}"
                         + ");");
 
        // --------------------------------------------------------------------------
        // Get pending bytes from raw socket.
        // --------------------------------------------------------------------------
        ulong pending_bytes = 0; // BSD, glibc, etc., use ulong; older UNIX systems use int // TODO: Figure out how to detect what ioctl needs
        __rc_check(ioctl(__socket_fd, FIONREAD, &pending_bytes));
 
        // --------------------------------------------------------------------------
        // Add pending bytes from OpenSSL if TLS is active, because this total isn't
        // included in the raw socket count since OpenSSL received these bytes.
        // --------------------------------------------------------------------------
        return __tls ? pending_bytes + SSL_pending(__tls_fd) : pending_bytes;
 
      }; // -x- ulong pending -x-
 
      /*======================================================================*//**
      @brief
      Poll the underlying socket using the poll() method for data that's ready for
      receiving (default), etc.
 
      @note
      The @ref rsocket_mux class provides methods that support poll(), ppoll(),
      select(), and accept()/accept4() when using multiple sockets.
 
      @throws randolf::rex::xEFAULT Address structure/memory is not in a writable
              part of the user address space
      @throws randolf::rex::xEINTR Interrupted by a signal
      @throws randolf::rex::xENOMEM Insufficient memory
      @throws randolf::rex::xENOTSOCK Underlying socket file descriptor (handle)
              doesn't refer to a socket
      @throws randolf::rex::xETIMEDOUT Timeout period elapsed (even if the @c
              TIMEOUT_BEHAVIOUR flag is @em not set to @c TIMEOUT_EXCEPTION, there
              is a highly improbable chance that a timeout could still occur if the
              data is read by another thread before the `recv(..., MSG_PEEK)` call)
      @throws randolf::rex::xEWOULDBLOCK The underlying socket is non-blocking and
              there's no new data
 
      @returns The resulting (short)pollfd.revents bitfield
      @returns 0 if @c timeout_behaviour is set to TIMEOUT_ZERO
      @see ppoll
      @see rsocket_mux
      @qualifier POSIX
      @qualifier TLS
      *///=========================================================================
      // TODO:  Integrate SSL_poll (requires OpenSSL 3.3 or newer) with SSL_POLL_EVENT_R, SSL_POLL_EVENT_W, and SSL_POLL_EVENT_E conversion
      short poll(
      /// Events bitfield (e.g., @c POLLIN, @c POLLOUT, and @c POLLERR)
      const short events = POLLIN,
      /// Number of milliseconds to wait
      const int timeout = 0,
      /// Timeout behaviour (see @ref TIMEOUT_BEHAVIOUR for details)
      const bool timeout_behaviour = TIMEOUT_EXCEPTION) {
        if (__debug) debug("poll(socket{0x" + randolf::rtools::to_hex(__socket_fd) + "}"
                         + ", pollfd.events=" + std::to_string(events)
                         + ", timeout=" + std::to_string(timeout)
                         + ");");
        struct pollfd fds{__socket_fd, events, 0};
        if (__rc_check(::poll(&fds, 1, timeout)) == 0) {
          if (timeout_behaviour) throw randolf::rex::xETIMEDOUT("ETIMEDOUT");
          else return 0;
        } // -x- if 0 -x-
        return fds.revents;
      }; // -x- short poll -x-
 
      /*======================================================================*//**
      @brief
      Get port number associated with underlying socket descriptor/handle.
 
      Returns 0 if:
         - an emphemeral port number assignment (dynamic) is intended
         - the underlying socket details are not defined (e.g., in the case of an
           empty rsocket instantiation)
         - port numbers are not supported/utilized by the current family (e.g., not
           AF_INET {IPv4} or AF_INET6 {IPv6})
 
      The port number can be set in most constructors, or via one of the socket()
      or bind() methods.
      @returns Port number (typically TCP and UDP, although some other families
               such as SCTP and DCCP also utilize port numbers)
      @see socket_family()
      @see socket_protocol()
      @see socket_type()
      @qualifier TLS
      *///=========================================================================
      const uint16_t port() noexcept {
        switch (__socket_addr.ss_family) {
          case AF_INET: // IPv4
            return ntohs(((sockaddr_in*)&__socket_addr)->sin_port);
          case AF_INET6: // IPv6
            return ntohs(((sockaddr_in6*)&__socket_addr)->sin6_port);
          default: // Everything else
            return 0;
        } // -x- switch __socket_addr.ss_family -x-
      }; // -x- uint16_t port -x-
 
      /*======================================================================*//**
      @brief
      Poll the underlying socket using the ppoll() method for data that's ready for
      receiving (default), etc.
 
      @note
      The @ref rsocket_mux class provides methods that support poll(), ppoll(),
      select(), and accept()/accept4() when using multiple sockets.
 
      @throws randolf::rex::xEFAULT Address structure/memory is not in a writable
              part of the user address space
      @throws randolf::rex::xEINTR Interrupted by a signal
      @throws randolf::rex::xENOMEM Insufficient memory
      @throws randolf::rex::xENOTSOCK Underlying socket file descriptor (handle)
              doesn't refer to a socket
      @throws randolf::rex::xETIMEDOUT Timeout period elapsed (even if the @c
              TIMEOUT_BEHAVIOUR flag is @em not set to @c TIMEOUT_EXCEPTION, there
              is a highly improbable chance that a timeout could still occur if the
              data is read by another thread before the `recv(..., MSG_PEEK)` call)
      @throws randolf::rex::xEWOULDBLOCK The underlying socket is non-blocking and
              there's no new data
 
      @returns The resulting (short)pollfd.revents bitfield
      @see poll
      @see rsocket_mux
      @qualifier POSIX
      @qualifier TLS
      *///=========================================================================
      // TODO:  Integrate SSL_poll (requires OpenSSL 3.3 or newer) with SSL_POLL_EVENT_R, SSL_POLL_EVENT_W, and SSL_POLL_EVENT_E conversion
      short ppoll(
      /// Events bitfield (e.g., @c POLLIN, @c POLLOUT, and @c POLLERR)
      const short events = POLLIN,
      /// Timeout
      const struct timespec* tmo_p = nullptr,
      /// Signal mask
      const sigset_t* sigmask = nullptr,
      /// Timeout behaviour (see @ref TIMEOUT_BEHAVIOUR for details)
      const bool timeout_behaviour = TIMEOUT_EXCEPTION) {
        if (__debug) debug("ppoll(socket{0x" + randolf::rtools::to_hex(__socket_fd) + "}"
                         + ", pollfd.events=" + std::to_string(events)
                         + ", timespec{tv_sec=" + std::to_string(tmo_p->tv_sec)
                                 + ", tv_nsec=" + std::to_string(tmo_p->tv_nsec) + "}"
                         + ", sigset_t"
                         + ");");
        struct pollfd fds{__socket_fd, events, 0};
        if (__rc_check(::ppoll(&fds, 1, tmo_p, sigmask)) == 0) {
          if (timeout_behaviour) throw randolf::rex::xETIMEDOUT("ETIMEDOUT");
          else return 0;
        } // -x- if 0 -x-
        return fds.revents;
      }; // -x- short ppoll -x-
 
      /*======================================================================*//**
      @brief
      Poll the underlying socket using the ppoll() method for data that's ready for
      receiving (default), etc.
 
      @note
      The @ref rsocket_mux class provides methods that support poll(), ppoll(),
      select(), and accept()/accept4() when using multiple sockets.
 
      @throws randolf::rex::xEFAULT Address structure/memory is not in a writable
              part of the user address space
      @throws randolf::rex::xEINTR Interrupted by a signal
      @throws randolf::rex::xENOMEM Insufficient memory
      @throws randolf::rex::xENOTSOCK Underlying socket file descriptor (handle)
              doesn't refer to a socket
      @throws randolf::rex::xETIMEDOUT Timeout period elapsed (even if the @c
              TIMEOUT_BEHAVIOUR flag is @em not set to @c TIMEOUT_EXCEPTION, there
              is a highly improbable chance that a timeout could still occur if the
              data is read by another thread before the `recv(..., MSG_PEEK)` call)
      @throws randolf::rex::xEWOULDBLOCK The underlying socket is non-blocking and
              there's no new data
 
      @returns The resulting (short)pollfd.revents bitfield
      @see ppoll
      @see rsocket_mux
      @qualifier TLS
      *///=========================================================================
      // TODO:  Integrate SSL_poll (requires OpenSSL 3.3 or newer) with SSL_POLL_EVENT_R, SSL_POLL_EVENT_W, and SSL_POLL_EVENT_E conversion
      short ppoll(
      /// Events bitfield (e.g., @c POLLIN, @c POLLOUT, and @c POLLERR)
      const short events = POLLIN,
      /// Timeout in seconds
      const int tv_sec = 0,
      /// Timeout in nanoseconds
      const long tv_nsec = 0,
      /// Signal mask
      const sigset_t* sigmask = nullptr,
      /// Timeout behaviour (see @ref TIMEOUT_BEHAVIOUR for details)
      const bool timeout_behaviour = TIMEOUT_EXCEPTION) {
        struct timespec tmo_p{tv_sec, tv_nsec};
        if (__debug) debug("ppoll(socket{0x" + randolf::rtools::to_hex(__socket_fd) + "}"
                         + ", pollfd.events=" + std::to_string(events)
                         + ", timespec{tv_sec=" + std::to_string(tmo_p.tv_sec)
                                 + ", tv_nsec=" + std::to_string(tmo_p.tv_nsec) + "}"
                         + ", sigset_t"
                         + ");");
        struct pollfd fds{__socket_fd, events, 0};
        if (__rc_check(::ppoll(&fds, 1, &tmo_p, sigmask)) == 0) {
          if (timeout_behaviour) throw randolf::rex::xETIMEDOUT("ETIMEDOUT");
          else return 0;
        } // -x- if 0 -x-
        return fds.revents;
      }; // -x- short ppoll -x-
 
      /*======================================================================*//**
      @brief
      Send a formatted string to the @ref rsocket endpoint.
 
      The @c format is described in the documentation for the POSIX or Standard C
      Library @c printf() function.
      @throws randolf::rex::xEBADF The underlying socket is not open
      @throws randolf::rex::xEILSEQ An invalid wide-character code was detected
      @throws randolf::rex::xEOVERFLOW The value returned is greater than {INT_MAX}
      @throws randolf::rex::xEMFILE Per-process maximum open files limit reached
      @throws randolf::rex::xENOMEM Insufficient memory
      @returns The same rsocket object so as to facilitate stacking
      @see eol_fix_printf
      @see is_eol_fix_printf
      @see net_io
      @see printfline
      @see vprintf
      @see vprintfline
      @qualifier POSIX
      @qualifier TLS
      *///=========================================================================
      rsocket* printf(
      /// Format string to use
      const char* format,
      /// Variadic arguments
      ...) {
        char* buf;
        ::va_list args;
        ::va_start(args, format);
        int rc = ::vasprintf(&buf, format, args);
        ::va_end(args); // Cleanup must occur before calling __rc_check to prevent memory leak in case of exception
        __rc_check(rc); // Check for error, and throw exception (buf was not allocated, so does not need to be freed)
        if (__eol_fix_printf && !__eol.empty()) {
          std::string str = std::regex_replace(buf, std::regex("\n"), __eol);
          ::free(buf);
          __send(str.c_str(), str.length());
        } else {
          try {
            __send(buf, rc);
          } catch (std::exception& e) { // Free buf then re-throw the exception
            ::free(buf); // Prevent memory leak when an exception is thrown
            throw;
          }
        } // -x- if __eol_fix_printf -x-
        return this;
      }; // -x- rsocket* printf -x-
 
      /*======================================================================*//**
      @brief
      Send a formatted string to the @ref rsocket endpoint, and append an EoL
      sequence.
 
      The @c format is described in the documentation for the POSIX or Standard C
      Library @c printf() function.
      @throws randolf::rex::xEBADF The underlying socket is not open
      @throws randolf::rex::xEILSEQ An invalid wide-character code was detected
      @throws randolf::rex::xEOVERFLOW The value returned is greater than {INT_MAX}
      @throws randolf::rex::xEMFILE Per-process maximum open files limit reached
      @throws randolf::rex::xENOMEM Insufficient memory
      @returns The same rsocket object so as to facilitate stacking
      @see eol
      @see eol_fix_printf
      @see is_eol_fix_printf
      @see net_io
      @see printf
      @see sendline
      @see vprintf
      @see vprintfline
      @qualifier TLS
      *///=========================================================================
      rsocket* printfline(
      /// Format string to use
      const char* format,
      /// Variadic arguments
      ...) {
        char* buf;
        ::va_list args;
        ::va_start(args, format);
        int rc = ::vasprintf(&buf, format, args);
        ::va_end(args); // Cleanup must occur before calling __rc_check to prevent memory leak in case of exception
        __rc_check(rc); // Check for error, and throw exception (buf was not allocated, so does not need to be freed)
        if (__eol_fix_printf && !__eol.empty()) {
          std::string str = std::regex_replace(buf, std::regex("\n"), __eol)
                           .append(__eol);
          ::free(buf);
          __send(str.c_str(), str.length());
        } else {
          try {
            __sendline(buf, rc);
          } catch (std::exception& e) { // Free buf then re-throw the exception
            ::free(buf); // Prevent memory leak when an exception is thrown
            throw;
          }
        } // -x- if __eol_fix_printf -x-
        return this;
      }; // -x- rsocket* printfline -x-
 
      /*======================================================================*//**
      @brief
      Receive data from the endpoint into a @c std::vector<char> that is allocated
      on-the-fly.
 
      If nbytes is 0, then the internal @ref buffer_size() will be used as the
      default, which can also be changed from its compiled-in default of 1024 by
      using one of the buffer_size() methods.
 
      @par Notes
      The @c MSG_WAITALL flag is particularly useful for preventing premature data
      reception, but it's important to note that it does implement temporary
      blocking while waiting for data.
 
      @throws randolf::rex::xEBADF The underlying socket is not open
      @throws randolf::rex::xECONNREFUSED Remote address is not listening for new
              connections
      @throws randolf::rex::xEFAULT Address structure/memory is not in a writable
              part of the user address space
      @throws randolf::rex::xEINTR Interrupted by a signal
      @throws randolf::rex::xEINVAL Invalid argument passed
      @throws randolf::rex::xENOMEM Insufficient memory
      @throws randolf::rex::xENOTCONN Underlying socket is not connected
      @throws randolf::rex::xENOTSOCK Underlying socket file descriptor (handle)
              doesn't refer to a socket
      @throws randolf::rex::xEWOULDBLOCK The underlying socket is non-blocking and
              there's no new data
 
      @returns appropriately-sized vector of characters
      @see recv(std::vector<char>, const int)
      @see recvz(const size_t, const int)
      @qualifier TLS
      *///=========================================================================
      std::vector<char> recv(
      /// Maximum number of bytes to receive
      const size_t nbytes = 0,
      /// MSG_OOB@n
      /// MSG_PEEK@n
      /// MSG_WAITALL@n
      /// MSG_DONTWAIT@n
      /// MSG_CMSG_CLOEXEC
      const int posix_flags = 0) {
        size_t buf_size = nbytes != 0 ? nbytes : __buffer_size;
        if (__debug) debug("recv{vector}(socket{0x" + randolf::rtools::to_hex(__socket_fd) + "}"
                         + ", <buf>"
                         + ", " + std::to_string(buf_size)
                         + ", " + std::to_string(posix_flags)
                         + ");");
        std::vector<char> buf(buf_size);
        buf.resize(__recv(buf.data(), buf.size(), posix_flags));
        return buf;
      }; // -x- std::vector<char> recv -x-
 
      /*======================================================================*//**
      @brief
      Receive data from the endpoint into the @c std::vector object supplied in the
      @c buf parameter.
 
      The maximum number of bytes that can be received won't exceed the number of
      bytes that the supplied @c std::vector<char> was initialized or resized to.
 
      @pre
      For @c std::vector it's important that the @c resize() method is used to
      pre-allocate the underlying char[] array, instead of the unfortunately-named
      @c reserve() method that doesn't pre-allocate, to avoid causing segmentation
      faults or other undefined behaviours.
 
      @par Notes
      The @c MSG_WAITALL flag is particularly useful for preventing premature data
      reception, but it's important to note that it does implement temporary
      blocking while waiting for data.
 
      @throws randolf::rex::xEBADF The underlying socket is not open
      @throws randolf::rex::xECONNREFUSED Remote address is not listening for new
              connections
      @throws randolf::rex::xEFAULT Address structure/memory is not in a writable
              part of the user address space
      @throws randolf::rex::xEINTR Interrupted by a signal
      @throws randolf::rex::xEINVAL Invalid argument passed
      @throws randolf::rex::xENOMEM Insufficient memory
      @throws randolf::rex::xENOTCONN Underlying socket is not connected
      @throws randolf::rex::xENOTSOCK Underlying socket file descriptor (handle)
              doesn't refer to a socket
      @throws randolf::rex::xEWOULDBLOCK The underlying socket is non-blocking and
              there's no new data
 
      @returns The same array that was specified in the @c buf parameter
      @see recv(const size_t, const int)
      @see recvz(const size_t, const int)
      @qualifier POSIX
      @qualifier TLS
      *///=========================================================================
      std::vector<char> recv(
      /// Target std::vector<char> to receive data into
      std::vector<char> buf,
      /// MSG_OOB@n
      /// MSG_PEEK@n
      /// MSG_WAITALL@n
      /// MSG_DONTWAIT@n
      /// MSG_CMSG_CLOEXEC
      const int posix_flags = 0) {
        if (__debug) debug("recv{vector}(socket{0x" + randolf::rtools::to_hex(__socket_fd) + "}"
                         + ", <buf>"
                         + ", " + std::to_string(buf.size())
                         + ", " + std::to_string(posix_flags)
                         + ");");
        buf.resize(__recv(buf.data(), buf.size(), posix_flags));
        return buf;
      }; // -x- std::vector<char> recv -x-
 
      /*======================================================================*//**
      @brief
      Receive data from the endpoint into a @c std::string object that is allocated
      on-the-fly.
 
      If nbytes is 0, then the internal @ref buffer_size() will be used as the
      default, which can also be changed from its compiled-in default of 1024 by
      using one of the buffer_size() methods.
 
      @par Notes
      The @c MSG_WAITALL flag is particularly useful for preventing premature data
      reception, but it's important to note that it does implement temporary
      blocking while waiting for data.
 
      @throws randolf::rex::xEBADF The underlying socket is not open
      @throws randolf::rex::xECONNREFUSED Remote address is not listening for new
              connections
      @throws randolf::rex::xEFAULT Address structure/memory is not in a writable
              part of the user address space
      @throws randolf::rex::xEINTR Interrupted by a signal
      @throws randolf::rex::xEINVAL Invalid argument passed
      @throws randolf::rex::xENOMEM Insufficient memory
      @throws randolf::rex::xENOTCONN Underlying socket is not connected
      @throws randolf::rex::xENOTSOCK Underlying socket file descriptor (handle)
              doesn't refer to a socket
      @throws randolf::rex::xEWOULDBLOCK The underlying socket is non-blocking and
              there's no new data
 
      @returns appropriately-sized vector of characters
      @see recv
      @see recv(std::vector<char>, const int)
      @see recvz(const size_t, const int)
      @qualifier TLS
      *///=========================================================================
      std::string recv_as_string(
      /// Maximum number of bytes to receive
      const size_t nbytes = 0,
      /// MSG_OOB@n
      /// MSG_PEEK@n
      /// MSG_WAITALL@n
      /// MSG_DONTWAIT@n
      /// MSG_CMSG_CLOEXEC
      const int posix_flags = 0) {
        size_t buf_size = nbytes != 0 ? nbytes : __buffer_size;
        if (__debug) debug("recv{vector}(socket{0x" + randolf::rtools::to_hex(__socket_fd) + "}"
                         + ", <buf>"
                         + ", " + std::to_string(buf_size)
                         + ", " + std::to_string(posix_flags)
                         + ");");
        std::string buf;
        buf.resize(buf_size); // Pre-fill anticipated string size
        buf.resize(__recv(buf.data(), buf.size(), posix_flags)); // Shorten string
        return buf;
      }; // -x- std::string recv -x-
 
      /*======================================================================*//**
      @brief
      Receive an ASCIIZ string from the endpoint, including the NULL terminator.
 
      @throws randolf::rex::xEBADF The underlying socket is not open
      @throws randolf::rex::xECONNREFUSED Remote address is not listening for new
              connections
      @throws randolf::rex::xEFAULT Address structure/memory is not in a writable
              part of the user address space
      @throws randolf::rex::xEINTR Interrupted by a signal
      @throws randolf::rex::xEINVAL Invalid argument passed
      @throws randolf::rex::xENOMEM Insufficient memory
      @throws randolf::rex::xENOTCONN Underlying socket is not connected
      @throws randolf::rex::xENOTSOCK Underlying socket file descriptor (handle)
              doesn't refer to a socket
      @throws randolf::rex::xERANGE if no NULL terminator is detected (this may
              occur before the underlying ASCIIZ string char* array is allocated)
      @throws randolf::rex::xEWOULDBLOCK The underlying socket is non-blocking and
              there's no new data
 
      @returns Pointer to ASCIIZ string (will need to be deleted by caller)
      @see send_asciiz(const char*, const int)
      @qualifier TLS
      *///=========================================================================
      char* recv_asciiz(
      /// Maximum number of bytes to receive
      const size_t nbytes = 0,
      /// MSG_OOB@n
      /// MSG_PEEK@n
      /// MSG_WAITALL@n
      /// MSG_DONTWAIT@n
      /// MSG_CMSG_CLOEXEC
      const int posix_flags = 0) {
        size_t buf_size = nbytes != 0 ? nbytes : __buffer_size;
        if (__debug) debug("recv_asciiz(socket{0x" + randolf::rtools::to_hex(__socket_fd) + "}"
                         + ", " + std::to_string(buf_size)
                         + ", " + std::to_string(posix_flags)
                         + ");");
 
        // --------------------------------------------------------------------------
        // Calculate size of buffer (includes NULL terminator since we'll also be
        // receiving this from the endpoint).
        // --------------------------------------------------------------------------
        char buf[buf_size];
 
        // --------------------------------------------------------------------------
        // Reduce buffer size to what is actually read (remember: we don't actually
        // know where the EoL sequence is yet, or if there even is one).
        // --------------------------------------------------------------------------
        int max = __recv(&buf, buf_size, posix_flags | MSG_PEEK); // Look-ahead at socket stream (buffer was inflated to include EoL sequence)
        int len = -1;
        for (int i = 0; i < max; i++) {
          if (buf[i] == 0) {
            len = i;
            break;
          } // -x- if v[i] -x-
        } // -x- for i -x-
        if (len < 0) throw randolf::rex::xERANGE("ERANGE:  NULL terminator not found");
 
        // --------------------------------------------------------------------------
        // I'd love to use std::shared_ptr<char*> for this next part, but it leads
        // to intermittent segmentation faults and/or "malloc(): corrupted top size
        // occurs" errors outside of this method.  So, my conclusion is that char*
        // (and char[], as I've tried with this too) are not properly supported by:
        // std::shared_ptr<char*> v = std::make_shared<char*>(new char[len + 1]);
        //
        // Using std::string() is really not what we want because there is confusion
        // concerning the NULL terminator -- with char* strings, it's crystal clear
        // that there must be a NULL terminator (since a length isn't tracked).  Now,
        // if you want an std::string, just initialize as follows:
        //
        //    char* temp_string = r.recv_asciiz();
        //    std::string mystr = std::string(temp_string);
        //    delete temp_string;
        // --------------------------------------------------------------------------
        char* v = new char[len + 1];
        int  rc = __recv(v, len + 1, posix_flags); // Consume with NULL terminator from socket stream
// TODO:  Free "v" in a catch-and-rethrow block (check other calls to __recv and __send too)
        return v;
 
      }; // -x- char* recv_asciiz -x-
 
      /*======================================================================*//**
      @brief
      Receive one byte (unsigned 8-bit byte) of data from the endpoint.
      @par Notes
      The @c MSG_WAITALL flag is particularly useful for preventing premature data
      reception, but it's important to note that it does implement temporary
      blocking while waiting for data.
 
      @throws randolf::rex::xEBADF The underlying socket is not open
      @throws randolf::rex::xECONNREFUSED Remote address is not listening for new
              connections
      @throws randolf::rex::xEFAULT Address structure/memory is not in a writable
              part of the user address space
      @throws randolf::rex::xEINTR Interrupted by a signal
      @throws randolf::rex::xEINVAL Invalid argument passed
      @throws randolf::rex::xENOMEM Insufficient memory
      @throws randolf::rex::xENOTCONN Underlying socket is not connected
      @throws randolf::rex::xENOTSOCK Underlying socket file descriptor (handle)
              doesn't refer to a socket
      @throws randolf::rex::xEWOULDBLOCK The underlying socket is non-blocking and
              there's no new data
 
      @returns one unsigned character
      @see recv(std::vector<char>, const int)
      @see recvz(const size_t, const int)
      @see recv_char
      @see send_byte
      @see send_char
      @qualifier TLS
      *///=========================================================================
      u_char recv_byte(
      /// MSG_OOB@n
      /// MSG_PEEK@n
      /// MSG_WAITALL@n
      /// MSG_DONTWAIT@n
      /// MSG_CMSG_CLOEXEC
      const int posix_flags = 0) {
        char buf(0);
        if (__debug) debug("recv_byte(socket{0x" + randolf::rtools::to_hex(__socket_fd) + "}"
                         + ", <buf>"
                         + ", " + std::to_string(sizeof(buf))
                         + ", " + std::to_string(posix_flags)
                         + ");");
        int rc = __recv(&buf, sizeof(buf), posix_flags | MSG_WAITALL);
        return buf;
      }; // -x- byte recv_byte -x-
 
      /*======================================================================*//**
      @brief
      Receive one character (signed 8-bit byte) of data from the endpoint.
      @par Notes
      The @c MSG_WAITALL flag is particularly useful for preventing premature data
      reception, but it's important to note that it does implement temporary
      blocking while waiting for data.
 
      @throws randolf::rex::xEBADF The underlying socket is not open
      @throws randolf::rex::xECONNREFUSED Remote address is not listening for new
              connections
      @throws randolf::rex::xEFAULT Address structure/memory is not in a writable
              part of the user address space
      @throws randolf::rex::xEINTR Interrupted by a signal
      @throws randolf::rex::xEINVAL Invalid argument passed
      @throws randolf::rex::xENOMEM Insufficient memory
      @throws randolf::rex::xENOTCONN Underlying socket is not connected
      @throws randolf::rex::xENOTSOCK Underlying socket file descriptor (handle)
              doesn't refer to a socket
      @throws randolf::rex::xEWOULDBLOCK The underlying socket is non-blocking and
              there's no new data
 
      @returns one signed character
      @see recv(std::vector<char>, const int)
      @see recvz(const size_t, const int)
      @see recv_byte
      @see send_byte
      @see send_char
      @qualifier TLS
      *///=========================================================================
      char recv_char(
      /// MSG_OOB@n
      /// MSG_PEEK@n
      /// MSG_WAITALL@n
      /// MSG_DONTWAIT@n
      /// MSG_CMSG_CLOEXEC
      const int posix_flags = 0) {
        char buf(0);
        if (__debug) debug("recv_char(socket{0x" + randolf::rtools::to_hex(__socket_fd) + "}"
                         + ", <buf>"
                         + ", " + std::to_string(sizeof(buf))
                         + ", " + std::to_string(posix_flags)
                         + ");");
        int rc = __recv(&buf, sizeof(buf), posix_flags | MSG_WAITALL);
  // How to detect disconnected stream when telnet user presses CTRL-C?
  //std::cout << "rc=" << std::to_string(rc) << std::endl; // Debug (to be removed)
// TODO:  Investigate checking platform's char size and moving signing bit accordingly
        return buf;
      }; // -x- char recv_char -x-
 
      /*======================================================================*//**
      @brief
      Receive a line of data from the endpoint, into an @ref randolf::rline object
      with the EoL character(s) isolated.  While this is meant for ASCII and UTF-8
      text, it will also work with binary data that doesn't include EoL character
      sequences as non-line-ending data (when receiving binary data,
      the @ref recv() and @ref recvz() methods tend to be better-suited).
 
      This is essentially a wrapper around what recvline() does, but returns both
      the line of text and the EoL sequence together in an @ref randolf::rline
      object.
      @note
      For additional details on the other parameters, please see the @ref recvline
      method's documentation for the remaining details.
      @warning
      If you're using a customzied EoL sequence, then it's important to note that
      it probably won't be recognized by the @ref randolf::rline class, but do also
      check that documentation to confirm this.
 
      @throws randolf::rex::xEAGAIN If @c timeout occurs before EoL
      @throws randolf::rex::xEBADF The underlying socket is not open
      @throws randolf::rex::xECONNREFUSED Remote address is not listening for new
              connections
      @throws randolf::rex::xEFAULT Address structure/memory is not in a writable
              part of the user address space
      @throws randolf::rex::xEINTR Interrupted by a signal
      @throws randolf::rex::xEINVAL Invalid argument passed
      @throws randolf::rex::xENOMEM Insufficient memory
      @throws randolf::rex::xENOTCONN Underlying socket is not connected
      @throws randolf::rex::xENOTSOCK Underlying socket file descriptor (handle)
              doesn't refer to a socket
      @throws randolf::rex::xEOVERFLOW if the line is too long; in other words, if
              no EoL character sequence is detected after recvline's buffer became
              full (whatever data is waiting may still be received using any of the
              recv_ methods {with or without the @c MSG_PEEK flag set}, including
              @c recvline() with a larger buffer {see the @c nbytes parameter})
      @throws randolf::rex::xERANGE if the timeout parameter is below 0
      @throws randolf::rex::xEWOULDBLOCK The underlying socket is non-blocking and
              there's no new data
 
      @returns One line of text as a randolf::rline object.
      @see discard
      @see eol()
      @see eol_consumed_seq()
      @see randolf::rline
      @see recvline
      @see sendline(const std::string, const int)
      @see timeout
      @see timeout_recvline
      @see timeout_recvline(long)
      @qualifier TLS
      *///=========================================================================
      randolf::rline recv_rline(
      /// Maximum number of bytes to receive (including EoL character sequence)
      const size_t nbytes = 0,
      /// MSG_OOB@n
      /// MSG_PEEK@n
      /// MSG_WAITALL@n
      /// MSG_DONTWAIT@n
      /// MSG_CMSG_CLOEXEC
      const int posix_flags = 0,
      /// Line timeout (in seconds)@n
      /// 0 = no timeout (default), unless it was configured by way of the
      ///     @ref timeout_recvline(long) method
      long timeout = 0,
      /// Configuration parameters
      const int recvline_flags = RECVLINE_FLAGS::RECVLINE_DEFAULT) {
        size_t buf_size = (nbytes != 0 ? nbytes : __buffer_size); // If 0, then set this to the internal __buffer_size default
                     // + (__eol.size() == 0 ? 2 : __eol.size()); // If 0, then set this to 2 bytes for automatic detection of CRLF; TODO:  Add an option for this
                     //   Internally, the length of the @ref eol() sequence is added to the buffer size
                     //   so that the maximum line length without EoL characters matches the maximum
                     //   that was specified with @ref buffer_size() or with the @c nbytes parameter.
        if (__debug) debug("recv_rline(socket{0x" + randolf::rtools::to_hex(__socket_fd) + "}"
                         + ", " + std::to_string(buf_size)
                         + ", " + std::to_string(posix_flags)
                         + ");");
        std::string line = __recvline(buf_size, posix_flags, timeout, recvline_flags);
        return randolf::rline(line.append(eol_consumed_seq()));
      }; // -x- randolf::rline recv_rline -x-
 
      /*======================================================================*//**
      @brief
      Receive a data structure from the endpoint.
      @post
      MSB/LSB considerations are important for any integers within your structure,
      so be sure to sanitize them with htons(), ntohs(), and related methods prior
      to sending, and then after receiving.  This way, your data will be protected
      against corruption resulting from byte order differences when communicating
      between hardware architectures that differ in MSB and LSB byte ordering.
      @par Notes
      The @c MSG_WAITALL flag is particularly useful for preventing premature data
      reception, but it's important to note that it does implement temporary
      blocking while waiting for data.
 
      @throws randolf::rex::xEBADF The underlying socket is not open
      @throws randolf::rex::xECONNREFUSED Remote address is not listening for new
              connections
      @throws randolf::rex::xEFAULT Address structure/memory is not in a writable
              part of the user address space
      @throws randolf::rex::xEINTR Interrupted by a signal
      @throws randolf::rex::xEINVAL Invalid argument passed
      @throws randolf::rex::xENOMEM Insufficient memory
      @throws randolf::rex::xENOTCONN Underlying socket is not connected
      @throws randolf::rex::xENOTSOCK Underlying socket file descriptor (handle)
              doesn't refer to a socket
      @throws randolf::rex::xEWOULDBLOCK The underlying socket is non-blocking and
              there's no new data
 
      @returns Data structure
      @see send_struct
      @qualifier TLS
      *///=========================================================================
      template <typename T> T recv_struct(
      /// MSG_OOB@n
      /// MSG_PEEK@n
      /// MSG_WAITALL@n
      /// MSG_DONTWAIT@n
      /// MSG_CMSG_CLOEXEC
      const int posix_flags = 0) {
        T buf{0};
        if (__debug) debug("recv_struct(socket{0x" + randolf::rtools::to_hex(__socket_fd) + "}"
                         + ", <buf>"
                         + ", " + std::to_string(sizeof(buf))
                         + ", " + std::to_string(posix_flags)
                         + ");");
        __recv(&buf, sizeof(buf), posix_flags);
        return buf;
      }; // -x- T recv_struct -x-
 
      /*======================================================================*//**
      @brief
      Receive one 16-bit unsigned integer of data in LSB (little endian) order from
      the endpoint.
      @par Notes
      The @c MSG_WAITALL flag is used behind-the-scenes to prevent premature data
      reception, which implements temporary blocking while waiting for data.
 
      @throws randolf::rex::xEBADF The underlying socket is not open
      @throws randolf::rex::xECONNREFUSED Remote address is not listening for new
              connections
      @throws randolf::rex::xEFAULT Address structure/memory is not in a writable
              part of the user address space
      @throws randolf::rex::xEINTR Interrupted by a signal
      @throws randolf::rex::xEINVAL Invalid argument passed
      @throws randolf::rex::xENOMEM Insufficient memory
      @throws randolf::rex::xENOTCONN Underlying socket is not connected
      @throws randolf::rex::xENOTSOCK Underlying socket file descriptor (handle)
              doesn't refer to a socket
      @throws randolf::rex::xEWOULDBLOCK The underlying socket is non-blocking and
              there's no new data
 
      @returns uint16_t (converted to local endianness)
      @qualifier TLS
      *///=========================================================================
      uint16_t recv_uint16_lsb(
      /// MSG_OOB@n
      /// MSG_PEEK@n
      /// MSG_WAITALL@n
      /// MSG_DONTWAIT@n
      /// MSG_CMSG_CLOEXEC
      const int posix_flags = 0) {
        uint16_t buf(0);
        if (__debug) debug("recv_uint16_lsb(socket{0x" + randolf::rtools::to_hex(__socket_fd) + "}"
                         + ", <buf>"
                         + ", " + std::to_string(sizeof(buf))
                         + ", " + std::to_string(posix_flags)
                         + ");");
        __recv(&buf, sizeof(buf), posix_flags | MSG_WAITALL);
        return !__endian_is_msb ? buf : ntohs(buf);
      }; // -x- uint16_t recv_uint16_lsb -x-
 
      /*======================================================================*//**
      @brief
      Receive one 16-bit unsigned integer of data in MSB (big endian) order from
      the endpoint.
      @par Notes
      The @c MSG_WAITALL flag is used behind-the-scenes to prevent premature data
      reception, which implements temporary blocking while waiting for data.
 
      @throws randolf::rex::xEBADF The underlying socket is not open
      @throws randolf::rex::xECONNREFUSED Remote address is not listening for new
              connections
      @throws randolf::rex::xEFAULT Address structure/memory is not in a writable
              part of the user address space
      @throws randolf::rex::xEINTR Interrupted by a signal
      @throws randolf::rex::xEINVAL Invalid argument passed
      @throws randolf::rex::xENOMEM Insufficient memory
      @throws randolf::rex::xENOTCONN Underlying socket is not connected
      @throws randolf::rex::xENOTSOCK Underlying socket file descriptor (handle)
              doesn't refer to a socket
      @throws randolf::rex::xEWOULDBLOCK The underlying socket is non-blocking and
              there's no new data
 
      @returns uint16_t (converted to local endianness)
      @qualifier TLS
      *///=========================================================================
      uint16_t recv_uint16_msb(
      /// MSG_OOB@n
      /// MSG_PEEK@n
      /// MSG_WAITALL@n
      /// MSG_DONTWAIT@n
      /// MSG_CMSG_CLOEXEC
      const int posix_flags = 0) {
        uint16_t buf(0);
        if (__debug) debug("recv_uint16_msb(socket{0x" + randolf::rtools::to_hex(__socket_fd) + "}"
                         + ", <buf>"
                         + ", " + std::to_string(sizeof(buf))
                         + ", " + std::to_string(posix_flags)
                         + ");");
        __recv(&buf, sizeof(buf), posix_flags | MSG_WAITALL);
        return __endian_is_msb ? buf : htons(buf);
      }; // -x- uint16_t recv_uint16_msb -x-
 
      /*======================================================================*//**
      @brief
      Receive one 32-bit unsigned integer of data in LSB (little endian) order from
      the endpoint.
      @par Notes
      The @c MSG_WAITALL flag is used behind-the-scenes to prevent premature data
      reception, which implements temporary blocking while waiting for data.
 
      @throws randolf::rex::xEBADF The underlying socket is not open
      @throws randolf::rex::xECONNREFUSED Remote address is not listening for new
              connections
      @throws randolf::rex::xEFAULT Address structure/memory is not in a writable
              part of the user address space
      @throws randolf::rex::xEINTR Interrupted by a signal
      @throws randolf::rex::xEINVAL Invalid argument passed
      @throws randolf::rex::xENOMEM Insufficient memory
      @throws randolf::rex::xENOTCONN Underlying socket is not connected
      @throws randolf::rex::xENOTSOCK Underlying socket file descriptor (handle)
              doesn't refer to a socket
      @throws randolf::rex::xEWOULDBLOCK The underlying socket is non-blocking and
              there's no new data
 
      @returns uint32_t (converted to local endianness)
      @qualifier TLS
      *///=========================================================================
      uint32_t recv_uint32_lsb(
      /// MSG_OOB@n
      /// MSG_PEEK@n
      /// MSG_WAITALL@n
      /// MSG_DONTWAIT@n
      /// MSG_CMSG_CLOEXEC
      const int posix_flags = 0) {
        uint32_t buf(0);
        if (__debug) debug("recv_uint32_lsb(socket{0x" + randolf::rtools::to_hex(__socket_fd) + "}"
                         + ", <buf>"
                         + ", " + std::to_string(sizeof(buf))
                         + ", " + std::to_string(posix_flags)
                         + ");");
        __recv(&buf, sizeof(buf), posix_flags | MSG_WAITALL);
        return !__endian_is_msb ? buf : htonl(buf);
      }; // -x- uint32_t recv_uint32_lsb -x-
 
      /*======================================================================*//**
      @brief
      Receive one 32-bit unsigned integer of data in MSB (big endian) order from
      the endpoint.
      @par Notes
      The @c MSG_WAITALL flag is used behind-the-scenes to prevent premature data
      reception, which implements temporary blocking while waiting for data.
 
      @throws randolf::rex::xEBADF The underlying socket is not open
      @throws randolf::rex::xECONNREFUSED Remote address is not listening for new
              connections
      @throws randolf::rex::xEFAULT Address structure/memory is not in a writable
              part of the user address space
      @throws randolf::rex::xEINTR Interrupted by a signal
      @throws randolf::rex::xEINVAL Invalid argument passed
      @throws randolf::rex::xENOMEM Insufficient memory
      @throws randolf::rex::xENOTCONN Underlying socket is not connected
      @throws randolf::rex::xENOTSOCK Underlying socket file descriptor (handle)
              doesn't refer to a socket
      @throws randolf::rex::xEWOULDBLOCK The underlying socket is non-blocking and
              there's no new data
 
      @returns uint32_t (converted to local endianness)
      @qualifier TLS
      *///=========================================================================
      uint32_t recv_uint32_msb(
      /// MSG_OOB@n
      /// MSG_PEEK@n
      /// MSG_WAITALL@n
      /// MSG_DONTWAIT@n
      /// MSG_CMSG_CLOEXEC
      const int posix_flags = 0) {
        uint32_t buf(0);
        if (__debug) debug("recv_uint32_msb(socket{0x" + randolf::rtools::to_hex(__socket_fd) + "}"
                         + ", <buf>"
                         + ", " + std::to_string(sizeof(buf))
                         + ", " + std::to_string(posix_flags)
                         + ");");
        __recv(&buf, sizeof(buf), posix_flags | MSG_WAITALL);
        return __endian_is_msb ? buf : ntohl(buf);
      }; // -x- uint32_t recv_uint32_msb -x-
 
      /*======================================================================*//**
      @brief
      Receive one 64-bit unsigned integer of data in LSB (little endian) order from
      the endpoint.
      @par Notes
      The @c MSG_WAITALL flag is used behind-the-scenes to prevent premature data
      reception, which implements temporary blocking while waiting for data.
 
      @throws randolf::rex::xEBADF The underlying socket is not open
      @throws randolf::rex::xECONNREFUSED Remote address is not listening for new
              connections
      @throws randolf::rex::xEFAULT Address structure/memory is not in a writable
              part of the user address space
      @throws randolf::rex::xEINTR Interrupted by a signal
      @throws randolf::rex::xEINVAL Invalid argument passed
      @throws randolf::rex::xENOMEM Insufficient memory
      @throws randolf::rex::xENOTCONN Underlying socket is not connected
      @throws randolf::rex::xENOTSOCK Underlying socket file descriptor (handle)
              doesn't refer to a socket
      @throws randolf::rex::xEWOULDBLOCK The underlying socket is non-blocking and
              there's no new data
 
      @returns uint64_t (converted to local endianness)
      @qualifier TLS
      *///=========================================================================
      uint64_t recv_uint64_lsb(
      /// MSG_OOB@n
      /// MSG_PEEK@n
      /// MSG_WAITALL@n
      /// MSG_DONTWAIT@n
      /// MSG_CMSG_CLOEXEC
      const int posix_flags = 0) {
        uint64_t buf(0);
        if (__debug) debug("recv_uint64_lsb(socket{0x" + randolf::rtools::to_hex(__socket_fd) + "}"
                         + ", <buf>"
                         + ", " + std::to_string(sizeof(buf))
                         + ", " + std::to_string(posix_flags)
                         + ");");
        __recv(&buf, sizeof(buf), posix_flags | MSG_WAITALL);
        return !__endian_is_msb ? buf : ((((uint64_t)ntohl((buf) & 0xffffffffUL)) << 32) | ntohl((uint32_t)((buf) >> 32)));
      }; // -x- uint64_t recv_uint64_lsb -x-
 
      /*======================================================================*//**
      @brief
      Receive one 64-bit unsigned integer of data in MSB (big endian) order from
      the endpoint.
      @par Notes
      The @c MSG_WAITALL flag is used behind-the-scenes to prevent premature data
      reception, which implements temporary blocking while waiting for data.
 
      @throws randolf::rex::xEBADF The underlying socket is not open
      @throws randolf::rex::xECONNREFUSED Remote address is not listening for new
              connections
      @throws randolf::rex::xEFAULT Address structure/memory is not in a writable
              part of the user address space
      @throws randolf::rex::xEINTR Interrupted by a signal
      @throws randolf::rex::xEINVAL Invalid argument passed
      @throws randolf::rex::xENOMEM Insufficient memory
      @throws randolf::rex::xENOTCONN Underlying socket is not connected
      @throws randolf::rex::xENOTSOCK Underlying socket file descriptor (handle)
              doesn't refer to a socket
      @throws randolf::rex::xEWOULDBLOCK The underlying socket is non-blocking and
              there's no new data
 
      @returns uint64_t (converted to local endianness)
      @qualifier TLS
      *///=========================================================================
      uint64_t recv_uint64_msb(
      /// MSG_OOB@n
      /// MSG_PEEK@n
      /// MSG_WAITALL@n
      /// MSG_DONTWAIT@n
      /// MSG_CMSG_CLOEXEC
      const int posix_flags = 0) {
        uint64_t buf(0);
        if (__debug) debug("recv_uint64_msb(socket{0x" + randolf::rtools::to_hex(__socket_fd) + "}"
                         + ", <buf>"
                         + ", " + std::to_string(sizeof(buf))
                         + ", " + std::to_string(posix_flags)
                         + ");");
        __recv(&buf, sizeof(buf), posix_flags | MSG_WAITALL);
        return __endian_is_msb ? buf : ((((uint64_t)htonl((buf) & 0xffffffffUL)) << 32) | htonl((uint32_t)((buf) >> 32)));
      }; // -x- uint64_t recv_uint64_msb -x-
 
      /*======================================================================*//**
      @brief
      Receive data from a specific endpoint.
 
      @par Notes
      The @c MSG_WAITALL flag is particularly useful for preventing premature data
      reception, but it's important to note that it does implement temporary
      blocking while waiting for data.
 
      @warning
      This method is not compatible with TLS.
 
      @throws randolf::rex::xEBADF The underlying socket is not open
      @throws randolf::rex::xECONNREFUSED Remote address is not listening for new
              connections
      @throws randolf::rex::xEFAULT Address structure/memory is not in a writable
              part of the user address space
      @throws randolf::rex::xEINTR Interrupted by a signal
      @throws randolf::rex::xEINVAL Invalid argument passed
      @throws randolf::rex::xENOMEM Insufficient memory
      @throws randolf::rex::xENOTCONN Underlying socket is not connected
      @throws randolf::rex::xENOTSOCK Underlying socket file descriptor (handle)
              doesn't refer to a socket
      @throws randolf::rex::xEWOULDBLOCK The underlying socket is non-blocking and
              there's no new data
 
      @returns Appropriately-sized vector of characters
      @qualifier POSIX
      *///=========================================================================
      std::vector<char> recvfrom(
      /// Maximum number of bytes to receive
      const size_t nbytes,
      /// MSG_OOB@n
      /// MSG_PEEK@n
      /// MSG_WAITALL@n
      /// MSG_DONTWAIT@n
      /// MSG_CMSG_CLOEXEC
      const int posix_flags,
      /// Target endpoint address structure
      struct sockaddr *from,
      /// Size of target endpoint structure
      socklen_t fromlen = sizeof(sockaddr)) {
        size_t buf_size = nbytes != 0 ? nbytes : __buffer_size;
        if (__debug) debug("recvfrom(socket{0x" + randolf::rtools::to_hex(__socket_fd) + "}"
                         + ", <buf>"
                         + ", " + std::to_string(buf_size)
                         + ", " + std::to_string(posix_flags)
                         + ", <sockaddr>"
                         + ", " + std::to_string(fromlen)
                         + ");");
        std::vector<char> v(buf_size);
        v.resize(__track_bytes_rx(__rc_check(::recvfrom(__socket_fd, v.data(), v.size(), posix_flags, from, &fromlen))));
        return v;
      }; // -x- std::vector<char> recvfrom -x-
 
    private:
      /*======================================================================*//**
      @brief
      This is an internal function that:
         1. receives data from the endpoint:
            - via underlying socket when TLS is not enabled
            - via the OpenSSL socket API when TLS is enabled
         2. checks for a socket I/O error (and throws an exception)
         3. tracks number of bytes received (if there were no errors)
 
      @note
      The ring buffer will only be used if there is one.  The @ref __recvline
      method is one method that instantiates the internal ring buffer, and there
      could be others in the future (although this is not strongly anticipated
      aside from a method that allows the software developer to explicitly choose
      to have a buffer active for all socket-read operations).
 
      @throws randolf::rex::xEAGAIN The underlying socket timed out
      @throws randolf::rex::xEBADF The underlying socket is not open
      @throws randolf::rex::xECONNREFUSED Remote address is not listening for new
              connections
      @throws randolf::rex::xEFAULT Address structure/memory is not in a writable
              part of the user address space
      @throws randolf::rex::xEINTR Interrupted by a signal
      @throws randolf::rex::xEINVAL Invalid argument passed
      @throws randolf::rex::xENOMEM Insufficient memory
      @throws randolf::rex::xENOTCONN Underlying socket is not connected
      @throws randolf::rex::xENOTSOCK Underlying socket file descriptor (handle)
              doesn't refer to a socket
      @throws randolf::rex::xEWOULDBLOCK The underlying socket is non-blocking and
              there's no new data
 
      @returns Number of bytes that were successfully received
      @qualifier TLS
      *///=========================================================================
      int __recv(
      /// Pointer to data
      void* data,
      /// Length of message data
      const int len,
      /// Flags (ignored with encrypted streams, except for the MSG_PEEK flag)
      const int posix_flags = 0) {
 
        // --------------------------------------------------------------------------
        // When internal buffering is not set up (which is the default operation), we
        // simply pass data directly.
        // --------------------------------------------------------------------------
        if (__buffer == nullptr) {
          return __tls ? (posix_flags & MSG_PEEK ?                  __rc_check_tls(SSL_peek(__tls_fd, data, len))
                                                 : __track_crypt_rx(__rc_check_tls(SSL_read(__tls_fd, data, len))))
                       :                           __track_bytes_rx(__rc_check(   ::recv(__socket_fd, data, len, posix_flags)));
        } // -x- if !__buffer -x-
 
        // --------------------------------------------------------------------------
        // If the amount of data contained in the internal buffer is sufficient to
        // satisfy the amount of data that "len" represents, then all that's needed
        // is to return "len" bytes from the ring buffer without having to receive
        // more data from the socket.
        // --------------------------------------------------------------------------
        if (len <= __buffer->get_utilized()) {
          if (posix_flags & MSG_PEEK) __buffer->peek_array(  (size_t)len, (char*)data); // Copy character(s) from ring buffer because MSG_PEEK flag is set
          else                        __buffer->remove_array((size_t)len, (char*)data); // Consume character(s) from ring buffer
          return len;
        } // -x- if len -x-
 
        // --------------------------------------------------------------------------
        // Consume data from socket to make up for OpenSSL's inability to read beyond
        // one packet of data in its SSL_peek() and SSL_read() methods, and also some
        // inconsistencies with certain raw (unencrypted) socket implementations that
        // occasionally refuse to read beyond one packet of data (at least on a first
        // attempt to read with or without the MSG_PEEK flag).
        //
        // Fill internal buffer.  It may be more than len is set to, but this is okay
        // because we're committed to using internal buffering now anyway (it's far
        // more likely that a protocol that requires the use of recvline() even once
        // is going to be using it repeatedly, but as long as the ring buffer is
        // large enough to cover the maximum length of a line of text, including its
        // EoL sequence, then this will always succeed).
        // --------------------------------------------------------------------------
        __buffer_bam = __buffer->data_bam(__buffer_bam); // Update ring buffer setup (will be allocated automatically if "nullptr" default)
        if (__buffer_bam->avail1_size == 0) return 0; // Buffer is full, so return 0
        int n = __tls ? __track_crypt_rx(__rc_check_tls(SSL_read(__tls_fd, __buffer_bam->avail1, __buffer_bam->avail1_size))) // Not using SSL_peek() at all here because we need to consume this data as we stuff it into the internal buffer
                      : __track_bytes_rx(__rc_check(   ::recv(__socket_fd, __buffer_bam->avail1, __buffer_bam->avail1_size, posix_flags & (~MSG_PEEK)))); // Mask the MSG_PEEK flag because we need to consume this data as we stuff it into the internal buffer
        if (n == 0) return 0;
        __buffer->set_head(n, false); // Add number of bytes received to the ring buffer after writing to the available portion of the ring buffer
 
        // --------------------------------------------------------------------------
        // Fill in the remaining (unused) portion of the internal buffer (if it's
        // available).
        //
        // Note:  FIONREAD instructs ioctl() to acquire the number of bytes that are
        //        immediately available for reading.  Returns 0 when successful.
        // --------------------------------------------------------------------------
        if (n == __buffer_bam->avail1_size // First available block got filled
         && __buffer_bam->avail2_size > 0  // Second available block is not 0 (which means that more data can be stored there)
         && !eos()) {                         // More data is in stream, ready to be copied without any delay
          int n2 = __tls ? __track_crypt_rx(__rc_check_tls(SSL_read(__tls_fd, __buffer_bam->avail2, __buffer_bam->avail2_size))) // Not using SSL_peek() at all here because we need to consume this data as we stuff it into the internal buffer
                         : __track_bytes_rx(__rc_check(   ::recv(__socket_fd, __buffer_bam->avail2, __buffer_bam->avail2_size, posix_flags & (~MSG_PEEK)))); // Mask the MSG_PEEK flag because we need to consume this data as we stuff it into the internal buffer
          __buffer->set_head(n2, false); // Add number of bytes received to the ring buffer after writing to the available portion of the ring buffer
          n += n2; // Update n
        } // -x- if n -x-
 
        // --------------------------------------------------------------------------
        // Copy or move data into destination.
        // --------------------------------------------------------------------------
        size_t utilized = std::min((size_t)len, __buffer->get_utilized()); // Specified length or utilized data in ring buffer, whichever is less
        if (posix_flags & MSG_PEEK)             __buffer->peek_array(  utilized, (char*)data); // Copy character(s) from ring buffer because MSG_PEEK flag is set
        else                                    __buffer->remove_array(utilized, (char*)data); // Consume character(s) from ring buffer
        return n;
 
      }; // -x- int __recv -x-
 
      /*======================================================================*//**
      @brief
      This is an internal function that:
         1. receives a line of data from the endpoint:
            - via underlying socket when TLS is not enabled
            - via the OpenSSL socket API when TLS is enabled
         2. checks for a socket I/O error (and throws an exception)
         3. tracks number of bytes received (if there were no errors)
         4. isolates the EoL sequence from the line of data, and records it for
            later reference (for those cases where it's needed)
 
      @throws randolf::rex::xEAGAIN If @c timeout occurs before EoL
      @throws randolf::rex::xEBADF The underlying socket is not open
      @throws randolf::rex::xECONNREFUSED Remote address is not listening for new
              connections
      @throws randolf::rex::xEFAULT Address structure/memory is not in a writable
              part of the user address space
      @throws randolf::rex::xEINTR Interrupted by a signal
      @throws randolf::rex::xEINVAL Invalid argument passed
      @throws randolf::rex::xENOMEM Insufficient memory
      @throws randolf::rex::xENOTCONN Underlying socket is not connected
      @throws randolf::rex::xENOTSOCK Underlying socket file descriptor (handle)
              doesn't refer to a socket
      @throws randolf::rex::xEOVERFLOW if the line is too long; in other words, if
              no EoL character sequence is detected after recvline's buffer became
              full (whatever data is waiting may still be received using any of the
              recv_ methods {with or without the @c MSG_PEEK flag set}, including
              @c recvline() with a larger buffer {see the @c nbytes parameter})
      @throws randolf::rex::xERANGE if the timeout parameter is below 0
      @throws randolf::rex::xEWOULDBLOCK The underlying socket is non-blocking and
              there's no new data
 
      @qualifier TLS
      *///=========================================================================
      std::string __recvline(
      /// Maximum number of bytes to receive (including EoL character sequence)
      const int buf_size,
      /// MSG_OOB@n
      /// MSG_PEEK (with some limitations)@n
      /// MSG_WAITALL@n
      /// MSG_DONTWAIT (ineffective when @c timeout is not 0)@n
      /// MSG_CMSG_CLOEXEC
      const int posix_flags,
      /// Line timeout (in seconds)@n
      /// 0 = no timeout (default), unless it was configured by way of the
      ///     @ref timeout_recvline(long) method
      const ulong timeout,
      /// Configuration parameters
      const int recvline_flags = RECVLINE_FLAGS::RECVLINE_DEFAULT) {
 
        // --------------------------------------------------------------------------
        // Syntax checks as part of preparation of timeout variable for faster
        // comparisons within line-reading loop.  To avoid problems when wrapping
        // past ULONG_MAX, we mask out the most-significant bit by multiplying by two
        // and then dividing by two.
        // --------------------------------------------------------------------------
        //if (timeout <  0) throw randolf::rex::xERANGE("timeout parameter of " + std::to_string(timeout) + " is below 0");
        //if (timeout == 0) timeout = (__recvline_timeout * 2) / 2; // Convert 0 to 
//std::cout << "timeout=" << timeout << std::endl;
        ulong timeout_target = timeout == 0 ? ULONG_MAX : timeout + time(0);
//std::cout << "timeout_target=" << timeout_target << std::endl;
 
        // --------------------------------------------------------------------------
        // Allocate line buffer.
        // --------------------------------------------------------------------------
        std::string v; v.resize(buf_size);
 
        // --------------------------------------------------------------------------
        // If an internal buffer, which is used by __recv, hasn't been instantiated,
        // then instantiate it and save the pointer to it for future use.
        //
        // Buffering becomes necessary with TLS connection because SSL_peek fails to
        // return data that spans multiple packets.  What triggers this behaviour is
        // the command "stty -icanon && openssl s_client host_name tcp_port" followed
        // by manual interactive typing some text then pressing the "[Enter]" key.
        //
        // The ::malloc(__buffer_size) won't be leaked because it will be freed in
        // in this rsocket's destructor (if it isn't freed elsewhere before this).
        // --------------------------------------------------------------------------
        if (__buffer == nullptr) __buffer = new rring(__buffer_size);
 
        int br = 0; // Number of Bytes Received
        int len_with_eol = 0;
        int len = -1;
 
        // --------------------------------------------------------------------------
        // Line-reading loop.
        // --------------------------------------------------------------------------
        do {
 
          // --------------------------------------------------------------------------
          // Attempt to read from the stream.
          // --------------------------------------------------------------------------
          try {
            br = __recv(v.data(), buf_size, posix_flags | MSG_PEEK); // Look-ahead at socket stream (with buffer size that was inflated earlier to include EoL sequence)
          } catch (const randolf::rex::xEAGAIN e) {
            // Socket timeout occurred, but ignore it so we can handle it separately
          }
std::cout << "br=" << br << std::endl;
          len = eol_index(v, &len_with_eol); // Measure length of string with EoL (-1 = no EoL found)
          if (len >= 0) break;
          if (br == buf_size && len < 0) break;
 
//std::cout << "br=" << br << " buf_size=" << buf_size << " v.size()=" << v.size() << " len=" << len << " len_with_eol=" << len_with_eol << " v[]=" << randolf::rtools::to_hex(v.substr(0, len < 0 ? 0 : 20), ":") << " t=" << timeout_target - time(0) << std::endl;
          // --------------------------------------------------------------------------
          // Wait for pending data for a duration no longer than the remaining timeout.
          // --------------------------------------------------------------------------
          if (eos(timeout == 0 ? timeout_target : timeout_target - time(0))) break;
 
        // --------------------------------------------------------------------------
        // Keep going if we haven't timed out yet.
        // --------------------------------------------------------------------------
        } while (timeout == 0 || time(0) < timeout_target);
 
std::cout << "break -- br=" << br << std::endl;
//std::cout << "br=" << br << " buf_size=" << buf_size << " v.size()=" << v.size() << " len=" << len << " len_with_eol=" << len_with_eol << " v[]=" << randolf::rtools::to_hex(v.substr(0, len < 0 ? 0 : 20), ":") << std::endl;
        // --------------------------------------------------------------------------
        // EoL sequence not found.  Either the buffer is exhausted, or we're at the
        // end of the stream, with no EoL anywhere in sight.
        // --------------------------------------------------------------------------
        if (len < 0) {
          //std::cout << "overflow  br=" << br << " buf_size=" << buf_size << std::endl; // Debug
 
          // --------------------------------------------------------------------------
          // Caller wants partial data instead of throwing an exception, even if it has
          // no EoL sequence.
          // --------------------------------------------------------------------------
          if (recvline_flags && RECVLINE_PARTIAL) {
            __eol_consumed_seq = ""; // Indicate that there's no EoL sequence
            if (!(posix_flags & MSG_PEEK)) __recv(v.data(), br, posix_flags & (~MSG_PEEK)); // Consume data if not in MSG_PEEK mode / __recv will throw exception if something goes wrong so there's no need for an additional __rc_check call from here
            v.resize(br); // Truncate string to "br" (bytes received)
            return v;
          } // -x- if RECVLINE_PARTIAL -x-
 
          // --------------------------------------------------------------------------
          // Generate xEOVERFLOW exception.
          //
          // TODO:  Generate a different exception for no EoL when the buffer isn't
          //        full.
          // --------------------------------------------------------------------------
          if (!(recvline_flags && RECVLINE_KEEP_ON_OVERFLOW) && !(posix_flags & MSG_PEEK)) {
            discard_line(); // Consume all that remains, or stop after first EoL sequence encountered
std::cout << "discarded" << std::endl;
          }
          throw randolf::rex::xEOVERFLOW("recvline overflow (line too long or missing EoL sequence)");
 
        } // -x- if !len -x-
 
        // --------------------------------------------------------------------------
        // Save the EoL sequence that was detected following a successful recvline()
        // (this must be completed prior to "final clean-up" {which is next}, because
        // we need to copy these characters before the truncation occurs).
        // --------------------------------------------------------------------------
//std::cout << "len=" << len << " len_with_eol=" << len_with_eol << " __buffer.get_utilized()=" << __buffer->get_utilized() << std::endl;
        __eol_consumed_seq = v.substr(len, len_with_eol - len);
 
        // --------------------------------------------------------------------------
        // Final clean-up.
        // --------------------------------------------------------------------------
        if (!(posix_flags & MSG_PEEK)) __recv(v.data(), len_with_eol, posix_flags & (~MSG_PEEK)); // Consume data if not in MSG_PEEK mode / __recv will throw exception if something goes wrong so there's no need for an additional __rc_check call from here
        //if ((posix_flags & MSG_PEEK) == 0) __recv(v.data(), len_with_eol, posix_flags); // Consume data if not in MSG_PEEK mode / __recv will throw exception if something goes wrong so there's no need for an additional __rc_check call from here
        v.resize(len); // Truncate string to exclude unused portion (and we're also not including the EoL sequence)
        return v;
 
      }; // -x- std::string __recvline -x-
 
    public:
      /*======================================================================*//**
      @brief
      Receive a line of data from the endpoint, with the EoL character(s) removed.
      While this is meant for ASCII and UTF-8 text, it will also work with binary
      data that doesn't include EoL character sequences as non-line-ending data
      (when receiving binary data, the @ref recv() and @ref recvz() methods tend to
      be better-suited).
 
      If @c nbytes is 0, then the internal buffer_size will be used as the default,
      which can also be changed from its compiled-in default of 1024 by using one
      of the buffer_size() methods.  The total number of bytes received, including
      the EoL sequence, will not exceed the total number of byte specified with the
      @c nbytes parameter.
      @warning
      For @c nbytes the EoL character sequence size should be included, especially
      for shorter lines -- if the EoL character sequence is detected automatically
      on-the-fly (which is the default), then provisioning 2 characters is needed
      since an EoL sequence could be 1 or 2 characters long (line lengths shorter
      than 3 characters could be particularly problematic when detecting on-the-fly
      EoL character sequences).  In such a case, a better approach is to allow for
      2 additional characters and then test the length of the returned string to
      ensure it doesn't exceed whatever the required maximum is (and throw the same
      @ref randolf::rex::xEOVERFLOW exception if the length is exceeded).
 
      For more information about which characters an EoL sequence is comprised of,
      and how our specialized support for multiple EoL sequences works, see the
      documentation for the various @ref eol methods.
 
      @pre
      When setting the recvline timeout (either with the @c timeout parameter with
      this method, or by using the @ref timeout_recvline(long) method), you may
      also need to set the socket timeout beforehand using the @ref timeout()
      method, because @c recvline doesn't do this...
      @n
      <blockquote>
        @ref timeout_recvline sets the overall total timeout for an entire line to
        be entered
        @n
        @ref timeout sets the timeout between individual characters received (such
        as keystrokes from a live end-user)
      </blockquote>
      @n
      If your socket timeout is longer than then recvline timeout, this will have
      the effect of rendering the recvling timeout as ineffective.
 
      The @c timeout parameter can be used to override the total overall timeout
      for receiving a line, which is useful for specific situations where a
      specific timeout is desired for particular prompts, during certain data entry
      stages, etc.
 
      @post
      When a line is not found (@c randolf::rex::xEAGAIN), or a line is too long
      because there's too much data (longer than a line) without an EoL sequence
      (@c randolf::rex::xOVERFLOW), then that data will not be discarded or
      consumed, and will remain ready for receiving (@ref recv) or for discarding
      @ref discard).
 
      @par Notes
      If you're searching for a readline() method for socket I/O, then this is most
      likely what you're wanting/needing.
 
      @throws randolf::rex::xEAGAIN If @c timeout occurs before EoL
      @throws randolf::rex::xEBADF The underlying socket is not open
      @throws randolf::rex::xECONNREFUSED Remote address is not listening for new
              connections
      @throws randolf::rex::xEFAULT Address structure/memory is not in a writable
              part of the user address space
      @throws randolf::rex::xEINTR Interrupted by a signal
      @throws randolf::rex::xEINVAL Invalid argument passed
      @throws randolf::rex::xENOMEM Insufficient memory
      @throws randolf::rex::xENOTCONN Underlying socket is not connected
      @throws randolf::rex::xENOTSOCK Underlying socket file descriptor (handle)
              doesn't refer to a socket
      @throws randolf::rex::xEOVERFLOW if the line is too long; in other words, if
              no EoL character sequence is detected after recvline's buffer became
              full (whatever data is waiting may still be received using any of the
              recv_ methods {with or without the @c MSG_PEEK flag set}, including
              @c recvline() with a larger buffer {see the @c nbytes parameter})
      @throws randolf::rex::xERANGE if the timeout parameter is below 0
      @throws randolf::rex::xEWOULDBLOCK The underlying socket is non-blocking and
              there's no new data
 
      @returns One line of text as a std::string object.
      @see discard
      @see eol()
      @see eol_consumed_seq()
      @see recv_rline
      @see sendline(const std::string, const int)
      @see timeout
      @see timeout_recvline
      @see timeout_recvline(long)
      @qualifier TLS
      *///=========================================================================
      std::string recvline(
      /// Maximum number of bytes to receive (including EoL character sequence)@n
      /// 0 = use internal @ref buffer_size()
      const size_t nbytes = 0,
      /// MSG_OOB@n
      /// MSG_PEEK@n
      /// MSG_WAITALL@n
      /// MSG_DONTWAIT@n
      /// MSG_CMSG_CLOEXEC
      const int posix_flags = 0,
      /// Line timeout (in seconds)@n
      /// 0 = no timeout (default), unless it was configured by way of the
      ///     @ref timeout_recvline(long) method
      long timeout = 0,
      /// Configuration parameters
      const int recvline_flags = RECVLINE_FLAGS::RECVLINE_DEFAULT) {
        size_t buf_size = (nbytes != 0 ? nbytes : __buffer_size); // If 0, then set this to the internal __buffer_size default
                     // + (__eol.size() == 0 ? 2 : __eol.size()); // If 0, then set this to 2 bytes for automatic detection of CRLF; TODO:  Add an option for this
                     //   Internally, the length of the @ref eol() sequence is added to the buffer size
                     //   so that the maximum line length without EoL characters matches the maximum
                     //   that was specified with @ref buffer_size() or with the @c nbytes parameter.
        if (__debug) debug("recvline(socket{0x" + randolf::rtools::to_hex(__socket_fd) + "}"
                         + ", " + std::to_string(buf_size)
                         + ", " + std::to_string(posix_flags)
                         + ");");
        return __recvline(buf_size, posix_flags, timeout, recvline_flags);
      }; // -x- std::string recvline -x-
 
      /*======================================================================*//**
      @brief
      Receive data in the form of a "msghdr" structure.
      @warning
      This method is not compatible with TLS.
 
      @throws randolf::rex::xEBADF The underlying socket is not open
      @throws randolf::rex::xECONNREFUSED Remote address is not listening for new
              connections
      @throws randolf::rex::xEFAULT Address structure/memory is not in a writable
              part of the user address space
      @throws randolf::rex::xEINTR Interrupted by a signal
      @throws randolf::rex::xEINVAL Invalid argument passed
      @throws randolf::rex::xENOMEM Insufficient memory
      @throws randolf::rex::xENOTCONN Underlying socket is not connected
      @throws randolf::rex::xENOTSOCK Underlying socket file descriptor (handle)
              doesn't refer to a socket
      @throws randolf::rex::xEWOULDBLOCK The underlying socket is non-blocking and
              there's no new data
 
      @returns pointer to "msghdr" structure
      @qualifier POSIX
      *///=========================================================================
      msghdr* recvmsg(
      /// Pointer to "msghdr" structure (or nullptr for automatic allocation)
      msghdr* msg,
      /// MSG_OOB@n
      /// MSG_PEEK@n
      /// MSG_WAITALL@n
      /// MSG_DONTWAIT@n
      /// MSG_CMSG_CLOEXEC
      const int posix_flags = 0) {
        if (__debug) debug("recvmsg(socket{0x" + randolf::rtools::to_hex(__socket_fd) + "}"
                         + ", <msghdr>"
                         + ", " + std::to_string(posix_flags)
                         + ");");
        if (msg == nullptr) msg = new msghdr{0};
        __track_bytes_rx(__rc_check(::recvmsg(__socket_fd, msg, posix_flags)));
        return msg;
      }; // -x- msghdr* recvmsg -x-
 
      /*======================================================================*//**
      @brief
      Receive data in the form of an "mmsghdr" structure.
      @warning
      This method is not compatible with TLS.
 
      @throws randolf::rex::xEBADF The underlying socket is not open
      @throws randolf::rex::xECONNREFUSED Remote address is not listening for new
              connections
      @throws randolf::rex::xEFAULT Address structure/memory is not in a writable
              part of the user address space
      @throws randolf::rex::xEINTR Interrupted by a signal
      @throws randolf::rex::xEINVAL Invalid argument passed
      @throws randolf::rex::xENOMEM Insufficient memory
      @throws randolf::rex::xENOTCONN Underlying socket is not connected
      @throws randolf::rex::xENOTSOCK Underlying socket file descriptor (handle)
              doesn't refer to a socket
      @throws randolf::rex::xEWOULDBLOCK The underlying socket is non-blocking and
              there's no new data
 
      @returns pointer to "mmsghdr" structure
      @qualifier POSIX
      *///=========================================================================
      mmsghdr* recvmmsg(
      /// Pointer to "mmsghdr" structure (or nullptr for automatic allocation)
      struct mmsghdr* mmsg,
      /// Size of target endpoint structure
      const unsigned int vlen = sizeof(mmsghdr),
      /// MSG_DONTROUTE@n
      /// MSG_DONTWAIT@n
      /// MSG_EOR@n
      /// MSG_NOSIGNAL@n
      /// MSG_OOB
      const int posix_flags = 0,
      /// Timeout
      struct timespec* timeout = {0}) {
        if (__debug) debug("recvmmsg(socket{0x" + randolf::rtools::to_hex(__socket_fd) + "}"
                         + ", <mmsghdr>"
                         + ", " + std::to_string(vlen)
                         + ", " + std::to_string(posix_flags)
                         + ", timeout{tv_sec=" + std::to_string(timeout->tv_sec)
                                + ", tv_nsec=" + std::to_string(timeout->tv_nsec) + "}"
                         + ");");
        __track_bytes_rx(__rc_check(::recvmmsg(__socket_fd, mmsg, vlen, posix_flags, timeout)));
        return mmsg;
      }; // -x- mmsghdr* recvmmsg -x-
 
      /*======================================================================*//**
      @brief
      Receive data from the endpoint, and add a 0 (null) onto the end.  This is
      useful when using the resulting std::vector<char> as an ASCIIZ string.
 
      If nbytes is 0, then the internal buffer_size will be used as the default,
      which can also be changed from its compiled-in default of 1024 by using one
      of the buffer_size() methods.
 
      @post
      The resulting std::vector size is always inflated by 1.  This means that
      relying on a comparison against 0 will result in an infinite loop:
      @code{.cpp}
      for (std::vector<char> v = r.recvz(); v.size > 0; v = recvz()) { ... }
      @endcode
      So, you'll need to compare against 1 instead of 0 to compensate fot the
      inflated size due to the addition of null character 0:
      @code{.cpp}
      for (std::vector<char> v = r.recvz(); v.size > 1; v = recvz()) { ... }
      @endcode
 
      @warning
      The resulting size of std::vector<char> will be <tt>nbytes + 1</tt> which
      ensures that any string processing functions or presentation libraries - such
      as @c printf() - expecting an ASCIIZ string buffer will stop at null (0), and
      will reliably output no more than the maximum size specified.
      @n@n
      The way to think of this is that @c nbytes specifies the maximum number of
      bytes (a.k.a., characters) to recieve over the underlying socket, and the
      final 0 (null) being added is not included in the maximum specified by the
      @c nbytes parameter.
 
      @par Notes
      The @c MSG_WAITALL flag is particularly useful for preventing premature data
      reception, but it's important to note that it does implement temporary
      blocking while waiting for data.
 
      @throws randolf::rex::xEBADF The underlying socket is not open
      @throws randolf::rex::xECONNREFUSED Remote address is not listening for new
              connections
      @throws randolf::rex::xEFAULT Address structure/memory is not in a writable
              part of the user address space
      @throws randolf::rex::xEINTR Interrupted by a signal
      @throws randolf::rex::xEINVAL Invalid argument passed
      @throws randolf::rex::xENOMEM Insufficient memory
      @throws randolf::rex::xENOTCONN Underlying socket is not connected
      @throws randolf::rex::xENOTSOCK Underlying socket file descriptor (handle)
              doesn't refer to a socket
      @throws randolf::rex::xEWOULDBLOCK The underlying socket is non-blocking and
              there's no new data
 
      @returns appropriately-sized vector of characters + 1 (includes additional
               null terminator character 0)
      @see recv(const size_t, const int)
      @see recv(std::vector<char>, const int)
      @qualifier TLS
      *///=========================================================================
      std::vector<char> recvz(
      /// Maximum number of bytes to receive
      const size_t nbytes = 0,
      /// MSG_OOB@n
      /// MSG_PEEK@n
      /// MSG_WAITALL@n
      /// MSG_DONTWAIT@n
      /// MSG_CMSG_CLOEXEC
      const int posix_flags = 0) {
        size_t buf_size = nbytes != 0 ? nbytes : __buffer_size;
        if (__debug) debug("recvz(socket{0x" + randolf::rtools::to_hex(__socket_fd) + "}"
                         + ", <buf>"
                         + ", " + std::to_string(buf_size)
                         + ", " + std::to_string(posix_flags)
                         + ");");
        std::vector<char> v(buf_size);
        v.resize(__recv(v.data(), v.size(), posix_flags) + 1); // Add 1 to include room for final null character 0
        v[v.size() - 1] = (char)0; // Set final element to 0 (null)
        return v;
      }; // -x- std::vector<char> recvz -x-
 
    private:
      /*======================================================================*//**
      @brief
      This is an internal function that:
         1. sends data to the endpoint:
            - via underlying socket when TLS is not enabled
            - via the OpenSSL socket API when TLS is enabled
         2. checks for a socket I/O error (and throws an exception)
         3. tracks number of bytes transmitted (if there were no errors)
 
      @par Threads
      This method is threadsafe because the underlying POSIX send() and OpenSSL's
      SSL_write() functions are threadsafe.
 
      @throws randolf::rex::xEBADF The underlying socket is not open
      @throws randolf::rex::xECONNRESET Connect reset by peer
      @throws randolf::rex::xEDESTADDRREQ Socket is not connected to an endpoint
      @throws randolf::rex::xEFAULT Address structure/memory is not in a writable
              part of the user address space
      @throws randolf::rex::xEINTR Interrupted by a signal
      @throws randolf::rex::xEINVAL Invalid argument passed
      @throws randolf::rex::xEISCONN Socket is already connected (this shouldn't
              occur, but the POSIX sockets documentation lists it as one of the
              errors that can be returned, perhaps because some incorrectly
              implemented TCP/IP stacks return this error?)
      @throws randolf::rex::xEMSGSIZE Message data exceeds the maximum size to be
              sent atomically (the maximum size is typically 65,507 bytes for IPv4
              and 65,527 bytes for IPv6)
      @throws randolf::rex::xENOBUFS Output queue is full, mostly likely due to
              network congestion (or, less commonly, insufficient memory)
      @throws randolf::rex::xENOMEM Insufficient memory
      @throws randolf::rex::xENOTCONN Underlying socket is not connected
      @throws randolf::rex::xENOTSOCK Underlying socket file descriptor (handle)
              doesn't refer to a socket
      @throws randolf::rex::xEOPNOTSUPP Underlying socket is no of type SOCK_STREAM
      @throws randolf::rex::xEPIPE Connection-oriented socket was shut down on the
              local end (and @c SIGPIPE will also be received if @c MSG_NOSIGNAL
              isn't set)
      @throws randolf::rex::xEWOULDBLOCK The underlying socket is non-blocking and
              there's no new data
      @throws randolf::rex::xEWOULDBLOCK No ephemeral ports are available for
              assignment to unbound socket (should be randolf::rex::xEADDRNOTAVAIL,
              but it really isn't)
 
      @returns Number of bytes that were successfully transmitted
      @qualifier TLS
      *///=========================================================================
      int __send(
      /// Pointer to data
      const void* data,
      /// Length of message data
      const size_t len,
      /// Flags (ignored with encrypted streams)
      const int posix_flags = 0) {
        if (__tls) return __track_crypt_tx(__rc_check_tls(SSL_write(__tls_fd, data, len)));
                   return __track_bytes_tx(__rc_check(    ::send(__socket_fd, data, len, posix_flags)));
      }; // -x- int __send -x-
 
      /*======================================================================*//**
      @brief
      This is an internal function that:
         1. sends data to the endpoint:
            - via underlying socket when TLS is not enabled
            - via the OpenSSL socket API when TLS is enabled
         2. checks for a socket I/O error (and throws an exception)
         3. tracks number of bytes transmitted (if there were no errors)
 
      @par Threads
      This method is threadsafe because the underlying POSIX send() and OpenSSL's
      SSL_write() functions are threadsafe.
 
      @throws randolf::rex::xEBADF The underlying socket is not open
      @throws randolf::rex::xECONNRESET Connect reset by peer
      @throws randolf::rex::xEDESTADDRREQ Socket is not connected to an endpoint
      @throws randolf::rex::xEFAULT Address structure/memory is not in a writable
              part of the user address space
      @throws randolf::rex::xEINTR Interrupted by a signal
      @throws randolf::rex::xEINVAL Invalid argument passed
      @throws randolf::rex::xEISCONN Socket is already connected (this shouldn't
              occur, but the POSIX sockets documentation lists it as one of the
              errors that can be returned, perhaps because some incorrectly
              implemented TCP/IP stacks return this error?)
      @throws randolf::rex::xEMSGSIZE Message data exceeds the maximum size to be
              sent atomically (the maximum size is typically 65,507 bytes for IPv4
              and 65,527 bytes for IPv6)
      @throws randolf::rex::xENOBUFS Output queue is full, mostly likely due to
              network congestion (or, less commonly, insufficient memory)
      @throws randolf::rex::xENOMEM Insufficient memory
      @throws randolf::rex::xENOTCONN Underlying socket is not connected
      @throws randolf::rex::xENOTSOCK Underlying socket file descriptor (handle)
              doesn't refer to a socket
      @throws randolf::rex::xEOPNOTSUPP Underlying socket is no of type SOCK_STREAM
      @throws randolf::rex::xEPIPE Connection-oriented socket was shut down on the
              local end (and @c SIGPIPE will also be received if @c MSG_NOSIGNAL
              isn't set)
      @throws randolf::rex::xEWOULDBLOCK The underlying socket is non-blocking and
              there's no new data
      @throws randolf::rex::xEWOULDBLOCK No ephemeral ports are available for
              assignment to unbound socket (should be randolf::rex::xEADDRNOTAVAIL,
              but it really isn't)
 
      @returns Number of bytes that were successfully transmitted
      @qualifier TLS
      *///=========================================================================
      int __sendline(
      /// Pointer to data
      const void* data,
      /// Number of bytes to send
      const size_t len,
      /// Flags (ignored with encrypted streams)
      const int posix_flags = 0) {
        if (__tls) { // Encrypted
          return __track_crypt_tx(__rc_check_tls(SSL_write(__tls_fd,            data  ,              len  )))
               + __track_crypt_tx(__rc_check_tls(SSL_write(__tls_fd, __eol_out.c_str(), __eol_out.length())));
        } else { // Not encrypted
          return __track_bytes_tx(__rc_check(    ::send(__socket_fd,            data  ,              len  , posix_flags | MSG_MORE))) // MSG_MORE prevents extra packets from being sent
               + __track_bytes_tx(__rc_check(    ::send(__socket_fd, __eol_out.c_str(), __eol_out.length(), posix_flags           )));
        } // -x- if __tls -x-
      }; // -x- int __sendline -x-
 
      /*======================================================================*//**
      @brief
      This is an internal function that:
         1. sends data to the endpoint:
            - via underlying socket when TLS is not enabled
            - via the OpenSSL socket API when TLS is enabled
         2. checks for a socket I/O error (and throws an exception)
         3. tracks number of bytes transmitted (if there were no errors)
 
      @par Threads
      This method is threadsafe because the underlying POSIX send() and OpenSSL's
      SSL_write() functions are threadsafe.
 
      @throws randolf::rex::xEBADF The underlying socket is not open
      @throws randolf::rex::xECONNRESET Connect reset by peer
      @throws randolf::rex::xEDESTADDRREQ Socket is not connected to an endpoint
      @throws randolf::rex::xEFAULT Address structure/memory is not in a writable
              part of the user address space
      @throws randolf::rex::xEINTR Interrupted by a signal
      @throws randolf::rex::xEINVAL Invalid argument passed
      @throws randolf::rex::xEISCONN Socket is already connected (this shouldn't
              occur, but the POSIX sockets documentation lists it as one of the
              errors that can be returned, perhaps because some incorrectly
              implemented TCP/IP stacks return this error?)
      @throws randolf::rex::xEMSGSIZE Message data exceeds the maximum size to be
              sent atomically (the maximum size is typically 65,507 bytes for IPv4
              and 65,527 bytes for IPv6)
      @throws randolf::rex::xENOBUFS Output queue is full, mostly likely due to
              network congestion (or, less commonly, insufficient memory)
      @throws randolf::rex::xENOMEM Insufficient memory
      @throws randolf::rex::xENOTCONN Underlying socket is not connected
      @throws randolf::rex::xENOTSOCK Underlying socket file descriptor (handle)
              doesn't refer to a socket
      @throws randolf::rex::xEOPNOTSUPP Underlying socket is no of type SOCK_STREAM
      @throws randolf::rex::xEPIPE Connection-oriented socket was shut down on the
              local end (and @c SIGPIPE will also be received if @c MSG_NOSIGNAL
              isn't set)
      @throws randolf::rex::xEWOULDBLOCK The underlying socket is non-blocking and
              there's no new data
      @throws randolf::rex::xEWOULDBLOCK No ephemeral ports are available for
              assignment to unbound socket (should be randolf::rex::xEADDRNOTAVAIL,
              but it really isn't)
 
      @returns Number of bytes that were successfully transmitted
      @qualifier TLS
      *///=========================================================================
      int __send_eol(
      /// Flags (ignored with encrypted streams)
      const int posix_flags = 0) {
        if (__tls) { // Encrypted
          return __track_crypt_tx(__rc_check_tls(SSL_write(__tls_fd, __eol_out.c_str(), __eol_out.length())));
        } else { // Not encrypted
          return __track_bytes_tx(__rc_check(    ::send(__socket_fd, __eol_out.c_str(), __eol_out.length(), posix_flags)));
        } // -x- if __tls -x-
      }; // -x- int __send_eol -x-
      // TODO:  Create a recv_eol() method that some people will probably consider to be evil (ha ha!)
      //        recv_eol() will need to be able to auto-detect the CRLF sequence on-the-fly (if necessary) just like recvline() does
 
    public:
      /*======================================================================*//**
      @brief
      Send data in the form of a std::string to the endpoint.
      @par Threads
      This method is threadsafe.
 
      @throws randolf::rex::xEBADF The underlying socket is not open
      @throws randolf::rex::xECONNRESET Connect reset by peer
      @throws randolf::rex::xEDESTADDRREQ Socket is not connected to an endpoint
      @throws randolf::rex::xEFAULT Address structure/memory is not in a writable
              part of the user address space
      @throws randolf::rex::xEINTR Interrupted by a signal
      @throws randolf::rex::xEINVAL Invalid argument passed
      @throws randolf::rex::xEISCONN Socket is already connected (this shouldn't
              occur, but the POSIX sockets documentation lists it as one of the
              errors that can be returned, perhaps because some incorrectly
              implemented TCP/IP stacks return this error?)
      @throws randolf::rex::xEMSGSIZE Message data exceeds the maximum size to be
              sent atomically (the maximum size is typically 65,507 bytes for IPv4
              and 65,527 bytes for IPv6)
      @throws randolf::rex::xENOBUFS Output queue is full, mostly likely due to
              network congestion (or, less commonly, insufficient memory)
      @throws randolf::rex::xENOMEM Insufficient memory
      @throws randolf::rex::xENOTCONN Underlying socket is not connected
      @throws randolf::rex::xENOTSOCK Underlying socket file descriptor (handle)
              doesn't refer to a socket
      @throws randolf::rex::xEOPNOTSUPP Underlying socket is no of type SOCK_STREAM
      @throws randolf::rex::xEPIPE Connection-oriented socket was shut down on the
              local end (and @c SIGPIPE will also be received if @c MSG_NOSIGNAL
              isn't set)
      @throws randolf::rex::xEWOULDBLOCK The underlying socket is non-blocking and
              there's no new data
      @throws randolf::rex::xEWOULDBLOCK No ephemeral ports are available for
              assignment to unbound socket (should be randolf::rex::xEADDRNOTAVAIL,
              but it really isn't)
 
      @returns The same rsocket object so as to facilitate stacking
      @qualifier TLS
      *///=========================================================================
      rsocket* send(
      /// Data to send
      const std::string msg,
      /// MSG_DONTROUTE@n
      /// MSG_DONTWAIT@n
      /// MSG_EOR@n
      /// MSG_NOSIGNAL@n
      /// MSG_OOB
      const int posix_flags = 0) {
        if (__debug) debug("send(socket{0x" + randolf::rtools::to_hex(__socket_fd) + "}"
                         + ", <std::string>"
                         + ", " + std::to_string(msg.length())
                         + ", " + std::to_string(posix_flags)
                         + ");");
        __send(msg.c_str(), msg.length(), posix_flags);
        return this;
      }; // -x- rsocket* send -x-
 
      /*======================================================================*//**
      @brief
      Send data in the form of a std::vector<char> to the endpoint.
      @par Threads
      This method is threadsafe.
 
      @throws randolf::rex::xEBADF The underlying socket is not open
      @throws randolf::rex::xECONNRESET Connect reset by peer
      @throws randolf::rex::xEDESTADDRREQ Socket is not connected to an endpoint
      @throws randolf::rex::xEFAULT Address structure/memory is not in a writable
              part of the user address space
      @throws randolf::rex::xEINTR Interrupted by a signal
      @throws randolf::rex::xEINVAL Invalid argument passed
      @throws randolf::rex::xEISCONN Socket is already connected (this shouldn't
              occur, but the POSIX sockets documentation lists it as one of the
              errors that can be returned, perhaps because some incorrectly
              implemented TCP/IP stacks return this error?)
      @throws randolf::rex::xEMSGSIZE Message data exceeds the maximum size to be
              sent atomically (the maximum size is typically 65,507 bytes for IPv4
              and 65,527 bytes for IPv6)
      @throws randolf::rex::xENOBUFS Output queue is full, mostly likely due to
              network congestion (or, less commonly, insufficient memory)
      @throws randolf::rex::xENOMEM Insufficient memory
      @throws randolf::rex::xENOTCONN Underlying socket is not connected
      @throws randolf::rex::xENOTSOCK Underlying socket file descriptor (handle)
              doesn't refer to a socket
      @throws randolf::rex::xEOPNOTSUPP Underlying socket is no of type SOCK_STREAM
      @throws randolf::rex::xEPIPE Connection-oriented socket was shut down on the
              local end (and @c SIGPIPE will also be received if @c MSG_NOSIGNAL
              isn't set)
      @throws randolf::rex::xEWOULDBLOCK The underlying socket is non-blocking and
              there's no new data
      @throws randolf::rex::xEWOULDBLOCK No ephemeral ports are available for
              assignment to unbound socket (should be randolf::rex::xEADDRNOTAVAIL,
              but it really isn't)
 
      @returns The same rsocket object so as to facilitate stacking
      @qualifier TLS
      *///=========================================================================
      rsocket* send(
      /// Data to send
      const std::vector<char> msg,
      /// MSG_DONTROUTE@n
      /// MSG_DONTWAIT@n
      /// MSG_EOR@n
      /// MSG_NOSIGNAL@n
      /// MSG_OOB
      const int posix_flags = 0) {
        if (__debug) debug("send(socket{0x" + randolf::rtools::to_hex(__socket_fd) + "}"
                         + ", <std::vector>"
                         + ", " + std::to_string(msg.size())
                         + ", " + std::to_string(posix_flags)
                         + ");");
        __send(msg.data(), msg.size(), posix_flags);
        return this;
      }; // -x- rsocket* send -x-
 
      /*======================================================================*//**
      @brief
      Send data in the form of a C-string to the endpoint.
      @par Threads
      This method is threadsafe.
 
      @throws randolf::rex::xEBADF The underlying socket is not open
      @throws randolf::rex::xECONNRESET Connect reset by peer
      @throws randolf::rex::xEDESTADDRREQ Socket is not connected to an endpoint
      @throws randolf::rex::xEFAULT Address structure/memory is not in a writable
              part of the user address space
      @throws randolf::rex::xEINTR Interrupted by a signal
      @throws randolf::rex::xEINVAL Invalid argument passed
      @throws randolf::rex::xEISCONN Socket is already connected (this shouldn't
              occur, but the POSIX sockets documentation lists it as one of the
              errors that can be returned, perhaps because some incorrectly
              implemented TCP/IP stacks return this error?)
      @throws randolf::rex::xEMSGSIZE Message data exceeds the maximum size to be
              sent atomically (the maximum size is typically 65,507 bytes for IPv4
              and 65,527 bytes for IPv6)
      @throws randolf::rex::xENOBUFS Output queue is full, mostly likely due to
              network congestion (or, less commonly, insufficient memory)
      @throws randolf::rex::xENOMEM Insufficient memory
      @throws randolf::rex::xENOTCONN Underlying socket is not connected
      @throws randolf::rex::xENOTSOCK Underlying socket file descriptor (handle)
              doesn't refer to a socket
      @throws randolf::rex::xEOPNOTSUPP Underlying socket is no of type SOCK_STREAM
      @throws randolf::rex::xEPIPE Connection-oriented socket was shut down on the
              local end (and @c SIGPIPE will also be received if @c MSG_NOSIGNAL
              isn't set)
      @throws randolf::rex::xEWOULDBLOCK The underlying socket is non-blocking and
              there's no new data
      @throws randolf::rex::xEWOULDBLOCK No ephemeral ports are available for
              assignment to unbound socket (should be randolf::rex::xEADDRNOTAVAIL,
              but it really isn't)
 
      @returns The same rsocket object so as to facilitate stacking
      @qualifier POSIX
      @qualifier TLS
      *///=========================================================================
      rsocket* send(
      /// Pointer to data to send
      const char* msg,
      /// Number of bytes to send, or 0 to auto-detect length if message is an ASCIIZ string
      size_t len = 0,
      /// MSG_DONTROUTE@n
      /// MSG_DONTWAIT@n
      /// MSG_EOR@n
      /// MSG_NOSIGNAL@n
      /// MSG_OOB
      const int posix_flags = 0) {
        if (__debug) debug("send(socket{0x" + randolf::rtools::to_hex(__socket_fd) + "}"
                         + ", <msg>"
                         + ", " + std::to_string(len)
                         + ", " + std::to_string(posix_flags)
                         + ");");
 
        // --------------------------------------------------------------------------
        // Measure size of format string if an ASCIIZ string was indicated.
        // --------------------------------------------------------------------------
        if (len == 0) len = std::strlen(msg);
 
        // --------------------------------------------------------------------------
        // Send string.
        // --------------------------------------------------------------------------
        __send(msg, len, posix_flags);
        return this;
      }; // -x- rsocket* send -x-
 
      /*======================================================================*//**
      @brief
      Send data in the form of an ASCIIZ string to the endpoint, including the
      terminating NULL character.
      @par Threads
      This method is threadsafe.
 
      @throws randolf::rex::xEBADF The underlying socket is not open
      @throws randolf::rex::xECONNRESET Connect reset by peer
      @throws randolf::rex::xEDESTADDRREQ Socket is not connected to an endpoint
      @throws randolf::rex::xEFAULT Address structure/memory is not in a writable
              part of the user address space
      @throws randolf::rex::xEINTR Interrupted by a signal
      @throws randolf::rex::xEINVAL Invalid argument passed
      @throws randolf::rex::xEISCONN Socket is already connected (this shouldn't
              occur, but the POSIX sockets documentation lists it as one of the
              errors that can be returned, perhaps because some incorrectly
              implemented TCP/IP stacks return this error?)
      @throws randolf::rex::xEMSGSIZE Message data exceeds the maximum size to be
              sent atomically (the maximum size is typically 65,507 bytes for IPv4
              and 65,527 bytes for IPv6)
      @throws randolf::rex::xENOBUFS Output queue is full, mostly likely due to
              network congestion (or, less commonly, insufficient memory)
      @throws randolf::rex::xENOMEM Insufficient memory
      @throws randolf::rex::xENOTCONN Underlying socket is not connected
      @throws randolf::rex::xENOTSOCK Underlying socket file descriptor (handle)
              doesn't refer to a socket
      @throws randolf::rex::xEOPNOTSUPP Underlying socket is no of type SOCK_STREAM
      @throws randolf::rex::xEPIPE Connection-oriented socket was shut down on the
              local end (and @c SIGPIPE will also be received if @c MSG_NOSIGNAL
              isn't set)
      @throws randolf::rex::xEWOULDBLOCK The underlying socket is non-blocking and
              there's no new data
      @throws randolf::rex::xEWOULDBLOCK No ephemeral ports are available for
              assignment to unbound socket (should be randolf::rex::xEADDRNOTAVAIL,
              but it really isn't)
 
      @returns The same rsocket object so as to facilitate stacking
      @see recv_asciiz(const size_t, const int)
      @see sendz(const char*, const int) which doesn't transmit the terminating
           NULL character
      @qualifier TLS
      *///=========================================================================
      rsocket* send_asciiz(
      /// Pointer to data to send
      const char* msg,
      /// MSG_DONTROUTE@n
      /// MSG_DONTWAIT@n
      /// MSG_EOR@n
      /// MSG_NOSIGNAL@n
      /// MSG_OOB
      const int posix_flags = 0) {
        if (__debug) debug("send_asciiz(socket{0x" + randolf::rtools::to_hex(__socket_fd) + "}"
                         + ", <msg>"
                         + ", " + std::to_string(std::strlen(msg) + 1)
                         + ", " + std::to_string(posix_flags)
                         + ");");
        __send(msg, std::strlen(msg) + 1, posix_flags);
        return this;
      }; // -x- rsocket* send_asciiz -x-
 
      /*======================================================================*//**
      @brief
      Send one 8-bit byte (one unsigned character) of data to the endpoint.
      @par Threads
      This method is threadsafe.
 
      @throws randolf::rex::xEBADF The underlying socket is not open
      @throws randolf::rex::xECONNRESET Connect reset by peer
      @throws randolf::rex::xEDESTADDRREQ Socket is not connected to an endpoint
      @throws randolf::rex::xEFAULT Address structure/memory is not in a writable
              part of the user address space
      @throws randolf::rex::xEINTR Interrupted by a signal
      @throws randolf::rex::xEINVAL Invalid argument passed
      @throws randolf::rex::xEISCONN Socket is already connected (this shouldn't
              occur, but the POSIX sockets documentation lists it as one of the
              errors that can be returned, perhaps because some incorrectly
              implemented TCP/IP stacks return this error?)
      @throws randolf::rex::xEMSGSIZE Message data exceeds the maximum size to be
              sent atomically (the maximum size is typically 65,507 bytes for IPv4
              and 65,527 bytes for IPv6)
      @throws randolf::rex::xENOBUFS Output queue is full, mostly likely due to
              network congestion (or, less commonly, insufficient memory)
      @throws randolf::rex::xENOMEM Insufficient memory
      @throws randolf::rex::xENOTCONN Underlying socket is not connected
      @throws randolf::rex::xENOTSOCK Underlying socket file descriptor (handle)
              doesn't refer to a socket
      @throws randolf::rex::xEOPNOTSUPP Underlying socket is no of type SOCK_STREAM
      @throws randolf::rex::xEPIPE Connection-oriented socket was shut down on the
              local end (and @c SIGPIPE will also be received if @c MSG_NOSIGNAL
              isn't set)
      @throws randolf::rex::xEWOULDBLOCK The underlying socket is non-blocking and
              there's no new data
      @throws randolf::rex::xEWOULDBLOCK No ephemeral ports are available for
              assignment to unbound socket (should be randolf::rex::xEADDRNOTAVAIL,
              but it really isn't)
 
      @returns The same rsocket object so as to facilitate stacking
      @see recv_byte
      @see recv_char
      @see send_char
      @qualifier TLS
      *///=========================================================================
      rsocket* send_byte(
      /// Data to send
      const u_char value,
      /// MSG_DONTROUTE@n
      /// MSG_DONTWAIT@n
      /// MSG_EOR@n
      /// MSG_NOSIGNAL@n
      /// MSG_OOB
      const int posix_flags = 0) {
        if (__debug) debug("send_byte(socket{0x" + randolf::rtools::to_hex(__socket_fd) + "}"
                         + ", <value>"
                         + ", " + std::to_string(sizeof(value))
                         + ", " + std::to_string(posix_flags)
                         + ");");
        __send(&value, sizeof(value), posix_flags);
        return this;
      }; // -x- rsocket* send_byte -x-
 
      /*======================================================================*//**
      @brief
      Send one signed character (one 8-bit byte) of data to the endpoint.
      @copydoc send_byte(char, int)
      @returns The same rsocket object so as to facilitate stacking
      @see recv_byte
      @see recv_char
      @see send_byte
      @qualifier TLS
      *///=========================================================================
      rsocket* send_char(
      /// Data to send
      const char value,
      /// MSG_DONTROUTE@n
      /// MSG_DONTWAIT@n
      /// MSG_EOR@n
      /// MSG_NOSIGNAL@n
      /// MSG_OOB
      const int posix_flags = 0) {
        if (__debug) debug("send_byte(socket{0x" + randolf::rtools::to_hex(__socket_fd) + "}"
                         + ", <value>"
                         + ", " + std::to_string(sizeof(value))
                         + ", " + std::to_string(posix_flags)
                         + ");");
        __send(&value, sizeof(value), posix_flags);
        return this;
      }; // -x- rsocket* send_char -x-
 
      /*======================================================================*//**
      @brief
      Send the EoL sequence to the endpoint.
      @par Threads
      This method is threadsafe.
 
      @throws randolf::rex::xEBADF The underlying socket is not open
      @throws randolf::rex::xECONNRESET Connect reset by peer
      @throws randolf::rex::xEDESTADDRREQ Socket is not connected to an endpoint
      @throws randolf::rex::xEFAULT Address structure/memory is not in a writable
              part of the user address space
      @throws randolf::rex::xEINTR Interrupted by a signal
      @throws randolf::rex::xEINVAL Invalid argument passed
      @throws randolf::rex::xEISCONN Socket is already connected (this shouldn't
              occur, but the POSIX sockets documentation lists it as one of the
              errors that can be returned, perhaps because some incorrectly
              implemented TCP/IP stacks return this error?)
      @throws randolf::rex::xEMSGSIZE Message data exceeds the maximum size to be
              sent atomically (the maximum size is typically 65,507 bytes for IPv4
              and 65,527 bytes for IPv6)
      @throws randolf::rex::xENOBUFS Output queue is full, mostly likely due to
              network congestion (or, less commonly, insufficient memory)
      @throws randolf::rex::xENOMEM Insufficient memory
      @throws randolf::rex::xENOTCONN Underlying socket is not connected
      @throws randolf::rex::xENOTSOCK Underlying socket file descriptor (handle)
              doesn't refer to a socket
      @throws randolf::rex::xEOPNOTSUPP Underlying socket is no of type SOCK_STREAM
      @throws randolf::rex::xEPIPE Connection-oriented socket was shut down on the
              local end (and @c SIGPIPE will also be received if @c MSG_NOSIGNAL
              isn't set)
      @throws randolf::rex::xEWOULDBLOCK The underlying socket is non-blocking and
              there's no new data
      @throws randolf::rex::xEWOULDBLOCK No ephemeral ports are available for
              assignment to unbound socket (should be randolf::rex::xEADDRNOTAVAIL,
              but it really isn't)
 
      @returns The same rsocket object so as to facilitate stacking
      @qualifier TLS
      *///=========================================================================
      rsocket* send_eol(
      /// MSG_DONTROUTE@n
      /// MSG_DONTWAIT@n
      /// MSG_EOR@n
      /// MSG_NOSIGNAL@n
      /// MSG_OOB
      const int posix_flags = 0) {
        if (__debug) debug("send_eol(socket{0x" + randolf::rtools::to_hex(__socket_fd) + "}"
                         + ", " + std::to_string(posix_flags)
                         + ");");
        __send_eol(posix_flags);
        return this;
      }; // -x- rsocket* send_eol -x-
 
      /*======================================================================*//**
      @brief
      Send a data structure to the endpoint.
      @pre
      MSB/LSB considerations are important for any integers within your structure,
      so be sure to sanitize them with htons(), ntohs(), and related methods prior
      to sending, and then after receiving.  This way, your data will be protected
      against corruption resulting from byte order differences when communicating
      between hardware architectures that differ in MSB and LSB byte ordering.
      @par Threads
      This method is threadsafe.
 
      @throws randolf::rex::xEBADF The underlying socket is not open
      @throws randolf::rex::xECONNRESET Connect reset by peer
      @throws randolf::rex::xEDESTADDRREQ Socket is not connected to an endpoint
      @throws randolf::rex::xEFAULT Address structure/memory is not in a writable
              part of the user address space
      @throws randolf::rex::xEINTR Interrupted by a signal
      @throws randolf::rex::xEINVAL Invalid argument passed
      @throws randolf::rex::xEISCONN Socket is already connected (this shouldn't
              occur, but the POSIX sockets documentation lists it as one of the
              errors that can be returned, perhaps because some incorrectly
              implemented TCP/IP stacks return this error?)
      @throws randolf::rex::xEMSGSIZE Message data exceeds the maximum size to be
              sent atomically (the maximum size is typically 65,507 bytes for IPv4
              and 65,527 bytes for IPv6)
      @throws randolf::rex::xENOBUFS Output queue is full, mostly likely due to
              network congestion (or, less commonly, insufficient memory)
      @throws randolf::rex::xENOMEM Insufficient memory
      @throws randolf::rex::xENOTCONN Underlying socket is not connected
      @throws randolf::rex::xENOTSOCK Underlying socket file descriptor (handle)
              doesn't refer to a socket
      @throws randolf::rex::xEOPNOTSUPP Underlying socket is no of type SOCK_STREAM
      @throws randolf::rex::xEPIPE Connection-oriented socket was shut down on the
              local end (and @c SIGPIPE will also be received if @c MSG_NOSIGNAL
              isn't set)
      @throws randolf::rex::xEWOULDBLOCK The underlying socket is non-blocking and
              there's no new data
      @throws randolf::rex::xEWOULDBLOCK No ephemeral ports are available for
              assignment to unbound socket (should be randolf::rex::xEADDRNOTAVAIL,
              but it really isn't)
 
      @returns The same rsocket object so as to facilitate stacking
      @see recv_struct
      @qualifier TLS
      *///=========================================================================
      template <typename T> rsocket* send_struct(
      /// Data to send
      const T value,
      /// MSG_DONTROUTE@n
      /// MSG_DONTWAIT@n
      /// MSG_EOR@n
      /// MSG_NOSIGNAL@n
      /// MSG_OOB
      const int posix_flags = 0) {
        if (__debug) debug("send_struct(socket{0x" + randolf::rtools::to_hex(__socket_fd) + "}"
                         + ", <value>"
                         + ", " + std::to_string(sizeof(value))
                         + ", " + std::to_string(posix_flags)
                         + ");");
        __send(&value, sizeof(value), posix_flags);
        return this;
      }; // -x- rsocket* send_struct -x-
 
      /*======================================================================*//**
      @brief
      Send one 16-bit unsigned integer of data in LSB (little endian) order to the
      endpoint.
      @par Threads
      This method is threadsafe.
 
      @throws randolf::rex::xEBADF The underlying socket is not open
      @throws randolf::rex::xECONNRESET Connect reset by peer
      @throws randolf::rex::xEDESTADDRREQ Socket is not connected to an endpoint
      @throws randolf::rex::xEFAULT Address structure/memory is not in a writable
              part of the user address space
      @throws randolf::rex::xEINTR Interrupted by a signal
      @throws randolf::rex::xEINVAL Invalid argument passed
      @throws randolf::rex::xEISCONN Socket is already connected (this shouldn't
              occur, but the POSIX sockets documentation lists it as one of the
              errors that can be returned, perhaps because some incorrectly
              implemented TCP/IP stacks return this error?)
      @throws randolf::rex::xEMSGSIZE Message data exceeds the maximum size to be
              sent atomically (the maximum size is typically 65,507 bytes for IPv4
              and 65,527 bytes for IPv6)
      @throws randolf::rex::xENOBUFS Output queue is full, mostly likely due to
              network congestion (or, less commonly, insufficient memory)
      @throws randolf::rex::xENOMEM Insufficient memory
      @throws randolf::rex::xENOTCONN Underlying socket is not connected
      @throws randolf::rex::xENOTSOCK Underlying socket file descriptor (handle)
              doesn't refer to a socket
      @throws randolf::rex::xEOPNOTSUPP Underlying socket is no of type SOCK_STREAM
      @throws randolf::rex::xEPIPE Connection-oriented socket was shut down on the
              local end (and @c SIGPIPE will also be received if @c MSG_NOSIGNAL
              isn't set)
      @throws randolf::rex::xEWOULDBLOCK The underlying socket is non-blocking and
              there's no new data
      @throws randolf::rex::xEWOULDBLOCK No ephemeral ports are available for
              assignment to unbound socket (should be randolf::rex::xEADDRNOTAVAIL,
              but it really isn't)
 
      @returns The same rsocket object so as to facilitate stacking
      @qualifier TLS
      *///=========================================================================
      rsocket* send_uint16_lsb(
      /// Data to send
      const uint16_t value,
      /// MSG_DONTROUTE@n
      /// MSG_DONTWAIT@n
      /// MSG_EOR@n
      /// MSG_NOSIGNAL@n
      /// MSG_OOB
      const int posix_flags = 0) {
        uint16_t buf = !__endian_is_msb ? value : ntohs(value);
        if (__debug) debug("send_uint16_lsb(socket{0x" + randolf::rtools::to_hex(__socket_fd) + "}"
                         + ", " + std::to_string(value)
                         + ", " + std::to_string(sizeof(buf))
                         + ", " + std::to_string(posix_flags)
                         + ");");
        __send(&buf, sizeof(buf), posix_flags);
        return this;
      }; // -x- rsocket* send_uint16_lsb -x-
 
      /*======================================================================*//**
      @brief
      Send one 16-bit integer of data in MSB (big endian) order to the endpoint.
      @par Threads
      This method is threadsafe.
 
      @throws randolf::rex::xEBADF The underlying socket is not open
      @throws randolf::rex::xECONNRESET Connect reset by peer
      @throws randolf::rex::xEDESTADDRREQ Socket is not connected to an endpoint
      @throws randolf::rex::xEFAULT Address structure/memory is not in a writable
              part of the user address space
      @throws randolf::rex::xEINTR Interrupted by a signal
      @throws randolf::rex::xEINVAL Invalid argument passed
      @throws randolf::rex::xEISCONN Socket is already connected (this shouldn't
              occur, but the POSIX sockets documentation lists it as one of the
              errors that can be returned, perhaps because some incorrectly
              implemented TCP/IP stacks return this error?)
      @throws randolf::rex::xEMSGSIZE Message data exceeds the maximum size to be
              sent atomically (the maximum size is typically 65,507 bytes for IPv4
              and 65,527 bytes for IPv6)
      @throws randolf::rex::xENOBUFS Output queue is full, mostly likely due to
              network congestion (or, less commonly, insufficient memory)
      @throws randolf::rex::xENOMEM Insufficient memory
      @throws randolf::rex::xENOTCONN Underlying socket is not connected
      @throws randolf::rex::xENOTSOCK Underlying socket file descriptor (handle)
              doesn't refer to a socket
      @throws randolf::rex::xEOPNOTSUPP Underlying socket is no of type SOCK_STREAM
      @throws randolf::rex::xEPIPE Connection-oriented socket was shut down on the
              local end (and @c SIGPIPE will also be received if @c MSG_NOSIGNAL
              isn't set)
      @throws randolf::rex::xEWOULDBLOCK The underlying socket is non-blocking and
              there's no new data
      @throws randolf::rex::xEWOULDBLOCK No ephemeral ports are available for
              assignment to unbound socket (should be randolf::rex::xEADDRNOTAVAIL,
              but it really isn't)
 
      @returns The same rsocket object so as to facilitate stacking
      @qualifier TLS
      *///=========================================================================
      rsocket* send_uint16_msb(
      /// Data to send
      const uint16_t value,
      /// MSG_DONTROUTE@n
      /// MSG_DONTWAIT@n
      /// MSG_EOR@n
      /// MSG_NOSIGNAL@n
      /// MSG_OOB
      const int posix_flags = 0) {
        int16_t buf = __endian_is_msb ? value : htons(value);
        if (__debug) debug("send_uint16_msb(socket{0x" + randolf::rtools::to_hex(__socket_fd) + "}"
                         + ", " + std::to_string(value)
                         + ", " + std::to_string(sizeof(buf))
                         + ", " + std::to_string(posix_flags)
                         + ");");
        __send(&buf, sizeof(buf), posix_flags);
        return this;
      }; // -x- rsocket* send_int16_msb -x-
 
      /*======================================================================*//**
      @brief
      Send one 32-bit unsigned integer of data in LSB (little endian) order to the
      endpoint.
      @par Threads
      This method is threadsafe.
 
      @throws randolf::rex::xEBADF The underlying socket is not open
      @throws randolf::rex::xECONNRESET Connect reset by peer
      @throws randolf::rex::xEDESTADDRREQ Socket is not connected to an endpoint
      @throws randolf::rex::xEFAULT Address structure/memory is not in a writable
              part of the user address space
      @throws randolf::rex::xEINTR Interrupted by a signal
      @throws randolf::rex::xEINVAL Invalid argument passed
      @throws randolf::rex::xEISCONN Socket is already connected (this shouldn't
              occur, but the POSIX sockets documentation lists it as one of the
              errors that can be returned, perhaps because some incorrectly
              implemented TCP/IP stacks return this error?)
      @throws randolf::rex::xEMSGSIZE Message data exceeds the maximum size to be
              sent atomically (the maximum size is typically 65,507 bytes for IPv4
              and 65,527 bytes for IPv6)
      @throws randolf::rex::xENOBUFS Output queue is full, mostly likely due to
              network congestion (or, less commonly, insufficient memory)
      @throws randolf::rex::xENOMEM Insufficient memory
      @throws randolf::rex::xENOTCONN Underlying socket is not connected
      @throws randolf::rex::xENOTSOCK Underlying socket file descriptor (handle)
              doesn't refer to a socket
      @throws randolf::rex::xEOPNOTSUPP Underlying socket is no of type SOCK_STREAM
      @throws randolf::rex::xEPIPE Connection-oriented socket was shut down on the
              local end (and @c SIGPIPE will also be received if @c MSG_NOSIGNAL
              isn't set)
      @throws randolf::rex::xEWOULDBLOCK The underlying socket is non-blocking and
              there's no new data
      @throws randolf::rex::xEWOULDBLOCK No ephemeral ports are available for
              assignment to unbound socket (should be randolf::rex::xEADDRNOTAVAIL,
              but it really isn't)
 
      @returns The same rsocket object so as to facilitate stacking
      @qualifier TLS
      *///=========================================================================
      rsocket* send_uint32_lsb(
      /// Data to send
      const uint32_t value,
      /// MSG_DONTROUTE@n
      /// MSG_DONTWAIT@n
      /// MSG_EOR@n
      /// MSG_NOSIGNAL@n
      /// MSG_OOB
      const int posix_flags = 0) {
        uint32_t buf = !__endian_is_msb ? value : ntohl(value);
        if (__debug) debug("send_uint32_lsb(socket{0x" + randolf::rtools::to_hex(__socket_fd) + "}"
                         + ", " + std::to_string(value)
                         + ", " + std::to_string(sizeof(buf))
                         + ", " + std::to_string(posix_flags)
                         + ");");
        __send(&buf, sizeof(buf), posix_flags);
        return this;
      }; // -x- rsocket* send_uint32_lsb -x-
 
      /*======================================================================*//**
      @brief
      Send one 32-bit unsigned integer of data in MSB (big endian) order to the
      endpoint.
      @par Threads
      This method is threadsafe.
 
      @throws randolf::rex::xEBADF The underlying socket is not open
      @throws randolf::rex::xECONNRESET Connect reset by peer
      @throws randolf::rex::xEDESTADDRREQ Socket is not connected to an endpoint
      @throws randolf::rex::xEFAULT Address structure/memory is not in a writable
              part of the user address space
      @throws randolf::rex::xEINTR Interrupted by a signal
      @throws randolf::rex::xEINVAL Invalid argument passed
      @throws randolf::rex::xEISCONN Socket is already connected (this shouldn't
              occur, but the POSIX sockets documentation lists it as one of the
              errors that can be returned, perhaps because some incorrectly
              implemented TCP/IP stacks return this error?)
      @throws randolf::rex::xEMSGSIZE Message data exceeds the maximum size to be
              sent atomically (the maximum size is typically 65,507 bytes for IPv4
              and 65,527 bytes for IPv6)
      @throws randolf::rex::xENOBUFS Output queue is full, mostly likely due to
              network congestion (or, less commonly, insufficient memory)
      @throws randolf::rex::xENOMEM Insufficient memory
      @throws randolf::rex::xENOTCONN Underlying socket is not connected
      @throws randolf::rex::xENOTSOCK Underlying socket file descriptor (handle)
              doesn't refer to a socket
      @throws randolf::rex::xEOPNOTSUPP Underlying socket is no of type SOCK_STREAM
      @throws randolf::rex::xEPIPE Connection-oriented socket was shut down on the
              local end (and @c SIGPIPE will also be received if @c MSG_NOSIGNAL
              isn't set)
      @throws randolf::rex::xEWOULDBLOCK The underlying socket is non-blocking and
              there's no new data
      @throws randolf::rex::xEWOULDBLOCK No ephemeral ports are available for
              assignment to unbound socket (should be randolf::rex::xEADDRNOTAVAIL,
              but it really isn't)
 
      @returns The same rsocket object so as to facilitate stacking
      @qualifier TLS
      *///=========================================================================
      rsocket* send_uint32_msb(
      /// Data to send
      const uint32_t value,
      /// MSG_DONTROUTE@n
      /// MSG_DONTWAIT@n
      /// MSG_EOR@n
      /// MSG_NOSIGNAL@n
      /// MSG_OOB
      const int posix_flags = 0) {
        uint32_t buf = __endian_is_msb ? value : htonl(value);
        if (__debug) debug("send_uint32_msb(socket{0x" + randolf::rtools::to_hex(__socket_fd) + "}"
                         + ", " + std::to_string(value)
                         + ", " + std::to_string(sizeof(buf))
                         + ", " + std::to_string(posix_flags)
                         + ");");
        __send(&buf, sizeof(buf), posix_flags);
        return this;
      }; // -x- rsocket* send_uint32_msb -x-
 
      /*======================================================================*//**
      @brief
      Send one 64-bit unsigned integer of data in LSB (little endian) order to the
      endpoint.
      @par Threads
      This method is threadsafe.
 
      @throws randolf::rex::xEBADF The underlying socket is not open
      @throws randolf::rex::xECONNRESET Connect reset by peer
      @throws randolf::rex::xEDESTADDRREQ Socket is not connected to an endpoint
      @throws randolf::rex::xEFAULT Address structure/memory is not in a writable
              part of the user address space
      @throws randolf::rex::xEINTR Interrupted by a signal
      @throws randolf::rex::xEINVAL Invalid argument passed
      @throws randolf::rex::xEISCONN Socket is already connected (this shouldn't
              occur, but the POSIX sockets documentation lists it as one of the
              errors that can be returned, perhaps because some incorrectly
              implemented TCP/IP stacks return this error?)
      @throws randolf::rex::xEMSGSIZE Message data exceeds the maximum size to be
              sent atomically (the maximum size is typically 65,507 bytes for IPv4
              and 65,527 bytes for IPv6)
      @throws randolf::rex::xENOBUFS Output queue is full, mostly likely due to
              network congestion (or, less commonly, insufficient memory)
      @throws randolf::rex::xENOMEM Insufficient memory
      @throws randolf::rex::xENOTCONN Underlying socket is not connected
      @throws randolf::rex::xENOTSOCK Underlying socket file descriptor (handle)
              doesn't refer to a socket
      @throws randolf::rex::xEOPNOTSUPP Underlying socket is no of type SOCK_STREAM
      @throws randolf::rex::xEPIPE Connection-oriented socket was shut down on the
              local end (and @c SIGPIPE will also be received if @c MSG_NOSIGNAL
              isn't set)
      @throws randolf::rex::xEWOULDBLOCK The underlying socket is non-blocking and
              there's no new data
      @throws randolf::rex::xEWOULDBLOCK No ephemeral ports are available for
              assignment to unbound socket (should be randolf::rex::xEADDRNOTAVAIL,
              but it really isn't)
 
      @returns The same rsocket object so as to facilitate stacking
      @qualifier TLS
      *///=========================================================================
      rsocket* send_uint64_lsb(
      /// Data to send
      const uint64_t value,
      /// MSG_DONTROUTE@n
      /// MSG_DONTWAIT@n
      /// MSG_EOR@n
      /// MSG_NOSIGNAL@n
      /// MSG_OOB
      const int posix_flags = 0) {
        uint64_t buf = !__endian_is_msb ? value : ((((uint64_t)ntohl((value) & 0xffffffffUL)) << 32) | ntohl((uint32_t)((value) >> 32)));
        if (__debug) debug("send_uint64_lsb(socket{0x" + randolf::rtools::to_hex(__socket_fd) + "}"
                         + ", " + std::to_string(value)
                         + ", " + std::to_string(sizeof(buf))
                         + ", " + std::to_string(posix_flags)
                         + ");");
        __send(&buf, sizeof(buf), posix_flags);
        return this;
      }; // -x- rsocket* send_uint64_lsb -x-
 
      /*======================================================================*//**
      @brief
      Send one 64-bit unsigned integer of data in MSB (big endian) order to the
      endpoint.
      @par Threads
      This method is threadsafe.
 
      @throws randolf::rex::xEBADF The underlying socket is not open
      @throws randolf::rex::xECONNRESET Connect reset by peer
      @throws randolf::rex::xEDESTADDRREQ Socket is not connected to an endpoint
      @throws randolf::rex::xEFAULT Address structure/memory is not in a writable
              part of the user address space
      @throws randolf::rex::xEINTR Interrupted by a signal
      @throws randolf::rex::xEINVAL Invalid argument passed
      @throws randolf::rex::xEISCONN Socket is already connected (this shouldn't
              occur, but the POSIX sockets documentation lists it as one of the
              errors that can be returned, perhaps because some incorrectly
              implemented TCP/IP stacks return this error?)
      @throws randolf::rex::xEMSGSIZE Message data exceeds the maximum size to be
              sent atomically (the maximum size is typically 65,507 bytes for IPv4
              and 65,527 bytes for IPv6)
      @throws randolf::rex::xENOBUFS Output queue is full, mostly likely due to
              network congestion (or, less commonly, insufficient memory)
      @throws randolf::rex::xENOMEM Insufficient memory
      @throws randolf::rex::xENOTCONN Underlying socket is not connected
      @throws randolf::rex::xENOTSOCK Underlying socket file descriptor (handle)
              doesn't refer to a socket
      @throws randolf::rex::xEOPNOTSUPP Underlying socket is no of type SOCK_STREAM
      @throws randolf::rex::xEPIPE Connection-oriented socket was shut down on the
              local end (and @c SIGPIPE will also be received if @c MSG_NOSIGNAL
              isn't set)
      @throws randolf::rex::xEWOULDBLOCK The underlying socket is non-blocking and
              there's no new data
      @throws randolf::rex::xEWOULDBLOCK No ephemeral ports are available for
              assignment to unbound socket (should be randolf::rex::xEADDRNOTAVAIL,
              but it really isn't)
 
      @returns The same rsocket object so as to facilitate stacking
      @qualifier TLS
      *///=========================================================================
      rsocket* send_uint64_msb(
      /// Data to send
      const uint64_t value,
      /// MSG_DONTROUTE@n
      /// MSG_DONTWAIT@n
      /// MSG_EOR@n
      /// MSG_NOSIGNAL@n
      /// MSG_OOB
      const int posix_flags = 0) {
        uint64_t buf = __endian_is_msb ? value : ((((uint64_t)htonl((value) & 0xffffffffUL)) << 32) | htonl((uint32_t)((value) >> 32)));
        if (__debug) debug("send_uint64_msb(socket{0x" + randolf::rtools::to_hex(__socket_fd) + "}"
                         + ", " + std::to_string(value)
                         + ", " + std::to_string(sizeof(buf))
                         + ", " + std::to_string(posix_flags)
                         + ");");
        __send(&buf, sizeof(buf), posix_flags);
        return this;
      }; // -x- rsocket* send_uint64_msb -x-
 
      /*======================================================================*//**
      @brief
      Send data in the form of a std::string to the endpoint, with an EoL sequence
      appended.
      @par Threads
      This method is threadsafe.
 
      @throws randolf::rex::xEBADF The underlying socket is not open
      @throws randolf::rex::xECONNRESET Connect reset by peer
      @throws randolf::rex::xEDESTADDRREQ Socket is not connected to an endpoint
      @throws randolf::rex::xEFAULT Address structure/memory is not in a writable
              part of the user address space
      @throws randolf::rex::xEINTR Interrupted by a signal
      @throws randolf::rex::xEINVAL Invalid argument passed
      @throws randolf::rex::xEISCONN Socket is already connected (this shouldn't
              occur, but the POSIX sockets documentation lists it as one of the
              errors that can be returned, perhaps because some incorrectly
              implemented TCP/IP stacks return this error?)
      @throws randolf::rex::xEMSGSIZE Message data exceeds the maximum size to be
              sent atomically (the maximum size is typically 65,507 bytes for IPv4
              and 65,527 bytes for IPv6)
      @throws randolf::rex::xENOBUFS Output queue is full, mostly likely due to
              network congestion (or, less commonly, insufficient memory)
      @throws randolf::rex::xENOMEM Insufficient memory
      @throws randolf::rex::xENOTCONN Underlying socket is not connected
      @throws randolf::rex::xENOTSOCK Underlying socket file descriptor (handle)
              doesn't refer to a socket
      @throws randolf::rex::xEOPNOTSUPP Underlying socket is no of type SOCK_STREAM
      @throws randolf::rex::xEPIPE Connection-oriented socket was shut down on the
              local end (and @c SIGPIPE will also be received if @c MSG_NOSIGNAL
              isn't set)
      @throws randolf::rex::xEWOULDBLOCK The underlying socket is non-blocking and
              there's no new data
      @throws randolf::rex::xEWOULDBLOCK No ephemeral ports are available for
              assignment to unbound socket (should be randolf::rex::xEADDRNOTAVAIL,
              but it really isn't)
 
      @returns The same rsocket object so as to facilitate stacking
      @see eol
      @see printfline
      @see recvline(const size_t, const int)
      @see vprintfline
      @qualifier TLS
      *///=========================================================================
      rsocket* sendline(
      /// Data to send
      const std::string msg = std::string(),
      /// MSG_DONTROUTE@n
      /// MSG_DONTWAIT@n
      /// MSG_EOR@n
      /// MSG_NOSIGNAL@n
      /// MSG_OOB
      const int posix_flags = 0) {
        if (__debug) debug("sendline(socket{0x" + randolf::rtools::to_hex(__socket_fd) + "}"
                         + ", <std::string>"
                         + ", " + std::to_string(msg.length())
                         + "+"  + std::to_string(__eol_out.length())
                         + ", " + std::to_string(posix_flags)
                         + ");");
        __sendline(msg.c_str(), msg.length(), posix_flags);
        return this;
      }; // -x- rsocket* sendline -x-
 
      /*======================================================================*//**
      @brief
      Send data in the form of a "msghdr" structure to a specific endpoint.
      @warning
      This method is not compatible with TLS.
      @par Threads
      This method is threadsafe.
 
      @throws randolf::rex::xEBADF The underlying socket is not open
      @throws randolf::rex::xECONNRESET Connect reset by peer
      @throws randolf::rex::xEDESTADDRREQ Socket is not connected to an endpoint
      @throws randolf::rex::xEFAULT Address structure/memory is not in a writable
              part of the user address space
      @throws randolf::rex::xEINTR Interrupted by a signal
      @throws randolf::rex::xEINVAL Invalid argument passed
      @throws randolf::rex::xEISCONN Socket is already connected (this shouldn't
              occur, but the POSIX sockets documentation lists it as one of the
              errors that can be returned, perhaps because some incorrectly
              implemented TCP/IP stacks return this error?)
      @throws randolf::rex::xEMSGSIZE Message data exceeds the maximum size to be
              sent atomically (the maximum size is typically 65,507 bytes for IPv4
              and 65,527 bytes for IPv6)
      @throws randolf::rex::xENOBUFS Output queue is full, mostly likely due to
              network congestion (or, less commonly, insufficient memory)
      @throws randolf::rex::xENOMEM Insufficient memory
      @throws randolf::rex::xENOTCONN Underlying socket is not connected
      @throws randolf::rex::xENOTSOCK Underlying socket file descriptor (handle)
              doesn't refer to a socket
      @throws randolf::rex::xEOPNOTSUPP Underlying socket is no of type SOCK_STREAM
      @throws randolf::rex::xEPIPE Connection-oriented socket was shut down on the
              local end (and @c SIGPIPE will also be received if @c MSG_NOSIGNAL
              isn't set)
      @throws randolf::rex::xEWOULDBLOCK The underlying socket is non-blocking and
              there's no new data
      @throws randolf::rex::xEWOULDBLOCK No ephemeral ports are available for
              assignment to unbound socket (should be randolf::rex::xEADDRNOTAVAIL,
              but it really isn't)
 
      @returns The same rsocket object so as to facilitate stacking
      @qualifier POSIX
      *///=========================================================================
      rsocket* sendmsg(
      /// Pointer to data to send
      const struct msghdr* msg,
      /// MSG_DONTROUTE@n
      /// MSG_DONTWAIT@n
      /// MSG_EOR@n
      /// MSG_NOSIGNAL@n
      /// MSG_OOB
      const int posix_flags = 0) {
        if (__debug) debug("sendmsg(socket{0x" + randolf::rtools::to_hex(__socket_fd) + "}"
                         + ", <msghdr>"
                         + ", " + std::to_string(posix_flags)
                         + ");");
        __track_bytes_tx(__rc_check(::sendmsg(__socket_fd, msg, posix_flags)));
        return this;
      }; // -x- rsocket* sendmsg -x-
 
      /*======================================================================*//**
      @brief
      Send data in the form of a "mmsghdr" structure to a specific endpoint.
      @warning
      This method is not compatible with TLS.
      @par Threads
      This method is threadsafe.
 
      @throws randolf::rex::xEBADF The underlying socket is not open
      @throws randolf::rex::xECONNRESET Connect reset by peer
      @throws randolf::rex::xEDESTADDRREQ Socket is not connected to an endpoint
      @throws randolf::rex::xEFAULT Address structure/memory is not in a writable
              part of the user address space
      @throws randolf::rex::xEINTR Interrupted by a signal
      @throws randolf::rex::xEINVAL Invalid argument passed
      @throws randolf::rex::xEISCONN Socket is already connected (this shouldn't
              occur, but the POSIX sockets documentation lists it as one of the
              errors that can be returned, perhaps because some incorrectly
              implemented TCP/IP stacks return this error?)
      @throws randolf::rex::xEMSGSIZE Message data exceeds the maximum size to be
              sent atomically (the maximum size is typically 65,507 bytes for IPv4
              and 65,527 bytes for IPv6)
      @throws randolf::rex::xENOBUFS Output queue is full, mostly likely due to
              network congestion (or, less commonly, insufficient memory)
      @throws randolf::rex::xENOMEM Insufficient memory
      @throws randolf::rex::xENOTCONN Underlying socket is not connected
      @throws randolf::rex::xENOTSOCK Underlying socket file descriptor (handle)
              doesn't refer to a socket
      @throws randolf::rex::xEOPNOTSUPP Underlying socket is no of type SOCK_STREAM
      @throws randolf::rex::xEPIPE Connection-oriented socket was shut down on the
              local end (and @c SIGPIPE will also be received if @c MSG_NOSIGNAL
              isn't set)
      @throws randolf::rex::xEWOULDBLOCK The underlying socket is non-blocking and
              there's no new data
      @throws randolf::rex::xEWOULDBLOCK No ephemeral ports are available for
              assignment to unbound socket (should be randolf::rex::xEADDRNOTAVAIL,
              but it really isn't)
 
      @returns The same rsocket object so as to facilitate stacking
      @qualifier POSIX
      *///=========================================================================
      rsocket* sendmmsg(
      /// Pointer to data to send
      struct mmsghdr* mmsg,
      /// Size of target endpoint structure
      const unsigned int vlen = sizeof(mmsghdr),
      /// MSG_DONTROUTE@n
      /// MSG_DONTWAIT@n
      /// MSG_EOR@n
      /// MSG_NOSIGNAL@n
      /// MSG_OOB
      const int posix_flags = 0) {
        if (__debug) debug("sendmmsg(socket{0x" + randolf::rtools::to_hex(__socket_fd) + "}"
                         + ", <mmsghdr>"
                         + ", " + std::to_string(vlen)
                         + ", " + std::to_string(posix_flags)
                         + ");");
        __track_bytes_tx(__rc_check(::sendmmsg(__socket_fd, mmsg, vlen, posix_flags)));
        return this;
      }; // -x- rsocket* sendmsg -x-
 
      /*======================================================================*//**
      @brief
      Send data in the form of a std::string to a specific endpoint.
      @warning
      This method is not compatible with TLS.
      @par Threads
      This method is threadsafe.
 
      @throws randolf::rex::xEBADF The underlying socket is not open
      @throws randolf::rex::xECONNRESET Connect reset by peer
      @throws randolf::rex::xEDESTADDRREQ Socket is not connected to an endpoint
      @throws randolf::rex::xEFAULT Address structure/memory is not in a writable
              part of the user address space
      @throws randolf::rex::xEINTR Interrupted by a signal
      @throws randolf::rex::xEINVAL Invalid argument passed
      @throws randolf::rex::xEISCONN Socket is already connected (this shouldn't
              occur, but the POSIX sockets documentation lists it as one of the
              errors that can be returned, perhaps because some incorrectly
              implemented TCP/IP stacks return this error?)
      @throws randolf::rex::xEMSGSIZE Message data exceeds the maximum size to be
              sent atomically (the maximum size is typically 65,507 bytes for IPv4
              and 65,527 bytes for IPv6)
      @throws randolf::rex::xENOBUFS Output queue is full, mostly likely due to
              network congestion (or, less commonly, insufficient memory)
      @throws randolf::rex::xENOMEM Insufficient memory
      @throws randolf::rex::xENOTCONN Underlying socket is not connected
      @throws randolf::rex::xENOTSOCK Underlying socket file descriptor (handle)
              doesn't refer to a socket
      @throws randolf::rex::xEOPNOTSUPP Underlying socket is no of type SOCK_STREAM
      @throws randolf::rex::xEPIPE Connection-oriented socket was shut down on the
              local end (and @c SIGPIPE will also be received if @c MSG_NOSIGNAL
              isn't set)
      @throws randolf::rex::xEWOULDBLOCK The underlying socket is non-blocking and
              there's no new data
      @throws randolf::rex::xEWOULDBLOCK No ephemeral ports are available for
              assignment to unbound socket (should be randolf::rex::xEADDRNOTAVAIL,
              but it really isn't)
 
      @returns The same rsocket object so as to facilitate stacking
      @qualifier POSIX
      *///=========================================================================
      rsocket* sendto(
      /// Data to send
      const std::string msg,
      /// MSG_DONTROUTE@n
      /// MSG_DONTWAIT@n
      /// MSG_EOR@n
      /// MSG_NOSIGNAL@n
      /// MSG_OOB
      const int posix_flags,
      /// Target endpoint address structure
      const struct sockaddr *to,
      /// Size of target endpoint structure
      socklen_t tolen = sizeof(sockaddr)) {
        if (__debug) debug("sendto(socket{0x" + randolf::rtools::to_hex(__socket_fd) + "}"
                         + ", <std::string>"
                         + ", " + std::to_string(posix_flags)
                         + ", <sockaddr>"
                         + ", " + std::to_string(tolen)
                         + ");");
        __track_bytes_tx(__rc_check(::sendto(__socket_fd, msg.c_str(), msg.length(), posix_flags, to, tolen)));
        return this;
      }; // -x- rsocket* sendto -x- // TODO:  Create easier-to-use variants
 
      /*======================================================================*//**
      @brief
      Send data in the form of a C-string to a specific endpoint.
      @warning
      This method is not compatible with TLS.
      @par Threads
      This method is threadsafe.
 
      @throws randolf::rex::xEBADF The underlying socket is not open
      @throws randolf::rex::xECONNRESET Connect reset by peer
      @throws randolf::rex::xEDESTADDRREQ Socket is not connected to an endpoint
      @throws randolf::rex::xEFAULT Address structure/memory is not in a writable
              part of the user address space
      @throws randolf::rex::xEINTR Interrupted by a signal
      @throws randolf::rex::xEINVAL Invalid argument passed
      @throws randolf::rex::xEISCONN Socket is already connected (this shouldn't
              occur, but the POSIX sockets documentation lists it as one of the
              errors that can be returned, perhaps because some incorrectly
              implemented TCP/IP stacks return this error?)
      @throws randolf::rex::xEMSGSIZE Message data exceeds the maximum size to be
              sent atomically (the maximum size is typically 65,507 bytes for IPv4
              and 65,527 bytes for IPv6)
      @throws randolf::rex::xENOBUFS Output queue is full, mostly likely due to
              network congestion (or, less commonly, insufficient memory)
      @throws randolf::rex::xENOMEM Insufficient memory
      @throws randolf::rex::xENOTCONN Underlying socket is not connected
      @throws randolf::rex::xENOTSOCK Underlying socket file descriptor (handle)
              doesn't refer to a socket
      @throws randolf::rex::xEOPNOTSUPP Underlying socket is no of type SOCK_STREAM
      @throws randolf::rex::xEPIPE Connection-oriented socket was shut down on the
              local end (and @c SIGPIPE will also be received if @c MSG_NOSIGNAL
              isn't set)
      @throws randolf::rex::xEWOULDBLOCK The underlying socket is non-blocking and
              there's no new data
      @throws randolf::rex::xEWOULDBLOCK No ephemeral ports are available for
              assignment to unbound socket (should be randolf::rex::xEADDRNOTAVAIL,
              but it really isn't)
 
      @returns The same rsocket object so as to facilitate stacking
      @qualifier POSIX
      *///=========================================================================
      rsocket* sendto(
      /// Pointer to data to send
      const char* msg,
      /// Number of bytes to send
      const size_t len,
      /// MSG_DONTROUTE@n
      /// MSG_DONTWAIT@n
      /// MSG_EOR@n
      /// MSG_NOSIGNAL@n
      /// MSG_OOB
      const int posix_flags,
      /// Target endpoint address structure
      const struct sockaddr *to,
      /// Size of target endpoint structure
      socklen_t tolen = sizeof(sockaddr)) {
        if (__debug) debug("sendto(socket{0x" + randolf::rtools::to_hex(__socket_fd) + "}"
                         + ", <msg>"
                         + ", " + std::to_string(std::strlen(msg))
                         + ", " + std::to_string(posix_flags)
                         + ", <sockaddr>"
                         + ", " + std::to_string(tolen)
                         + ");");
        __track_bytes_tx(__rc_check(::sendto(__socket_fd, msg, len, posix_flags, to, tolen)));
        return this;
      }; // -x- rsocket* sendto -x-
 
      /*======================================================================*//**
      @brief
      Send data in the form of an ASCIIZ string to the endpoint.  The terminating
      NULL character won't be transmitted.
      @par Threads
      This method is threadsafe.
 
      @throws randolf::rex::xEBADF The underlying socket is not open
      @throws randolf::rex::xECONNRESET Connect reset by peer
      @throws randolf::rex::xEDESTADDRREQ Socket is not connected to an endpoint
      @throws randolf::rex::xEFAULT Address structure/memory is not in a writable
              part of the user address space
      @throws randolf::rex::xEINTR Interrupted by a signal
      @throws randolf::rex::xEINVAL Invalid argument passed
      @throws randolf::rex::xEISCONN Socket is already connected (this shouldn't
              occur, but the POSIX sockets documentation lists it as one of the
              errors that can be returned, perhaps because some incorrectly
              implemented TCP/IP stacks return this error?)
      @throws randolf::rex::xEMSGSIZE Message data exceeds the maximum size to be
              sent atomically (the maximum size is typically 65,507 bytes for IPv4
              and 65,527 bytes for IPv6)
      @throws randolf::rex::xENOBUFS Output queue is full, mostly likely due to
              network congestion (or, less commonly, insufficient memory)
      @throws randolf::rex::xENOMEM Insufficient memory
      @throws randolf::rex::xENOTCONN Underlying socket is not connected
      @throws randolf::rex::xENOTSOCK Underlying socket file descriptor (handle)
              doesn't refer to a socket
      @throws randolf::rex::xEOPNOTSUPP Underlying socket is no of type SOCK_STREAM
      @throws randolf::rex::xEPIPE Connection-oriented socket was shut down on the
              local end (and @c SIGPIPE will also be received if @c MSG_NOSIGNAL
              isn't set)
      @throws randolf::rex::xEWOULDBLOCK The underlying socket is non-blocking and
              there's no new data
      @throws randolf::rex::xEWOULDBLOCK No ephemeral ports are available for
              assignment to unbound socket (should be randolf::rex::xEADDRNOTAVAIL,
              but it really isn't)
 
      @returns The same rsocket object so as to facilitate stacking
      @see recvz(const size_t, const int)
      @see send_asciiz(const char*, const int) which also transmits the terminating
           NULL character
      @qualifier TLS
      *///=========================================================================
      rsocket* sendz(
      /// Pointer to data to send
      const char* msg,
      /// MSG_DONTROUTE@n
      /// MSG_DONTWAIT@n
      /// MSG_EOR@n
      /// MSG_NOSIGNAL@n
      /// MSG_OOB
      const int posix_flags = 0) {
        if (__debug) debug("sendz(socket{0x" + randolf::rtools::to_hex(__socket_fd) + "}"
                         + ", <msg>"
                         + ", " + std::to_string(std::strlen(msg))
                         + ", " + std::to_string(posix_flags)
                         + ");");
        __send(msg, std::strlen(msg), posix_flags);
        return this;
      }; // -x- rsocket* sendz -x-
 
      /*======================================================================*//**
      @brief
      Send data in the form of an ASCIIZ string to a specific endpoint.  The
      terminating NULL character won't be transmitted.
      @warning
      This method is not compatible with TLS.
      @par Threads
      This method is threadsafe.
 
      @throws randolf::rex::xEBADF The underlying socket is not open
      @throws randolf::rex::xECONNRESET Connect reset by peer
      @throws randolf::rex::xEDESTADDRREQ Socket is not connected to an endpoint
      @throws randolf::rex::xEFAULT Address structure/memory is not in a writable
              part of the user address space
      @throws randolf::rex::xEINTR Interrupted by a signal
      @throws randolf::rex::xEINVAL Invalid argument passed
      @throws randolf::rex::xEISCONN Socket is already connected (this shouldn't
              occur, but the POSIX sockets documentation lists it as one of the
              errors that can be returned, perhaps because some incorrectly
              implemented TCP/IP stacks return this error?)
      @throws randolf::rex::xEMSGSIZE Message data exceeds the maximum size to be
              sent atomically (the maximum size is typically 65,507 bytes for IPv4
              and 65,527 bytes for IPv6)
      @throws randolf::rex::xENOBUFS Output queue is full, mostly likely due to
              network congestion (or, less commonly, insufficient memory)
      @throws randolf::rex::xENOMEM Insufficient memory
      @throws randolf::rex::xENOTCONN Underlying socket is not connected
      @throws randolf::rex::xENOTSOCK Underlying socket file descriptor (handle)
              doesn't refer to a socket
      @throws randolf::rex::xEOPNOTSUPP Underlying socket is no of type SOCK_STREAM
      @throws randolf::rex::xEPIPE Connection-oriented socket was shut down on the
              local end (and @c SIGPIPE will also be received if @c MSG_NOSIGNAL
              isn't set)
      @throws randolf::rex::xEWOULDBLOCK The underlying socket is non-blocking and
              there's no new data
      @throws randolf::rex::xEWOULDBLOCK No ephemeral ports are available for
              assignment to unbound socket (should be randolf::rex::xEADDRNOTAVAIL,
              but it really isn't)
 
      @returns The same rsocket object so as to facilitate stacking
      *///=========================================================================
      rsocket* sendzto(
      /// Pointer to data to send
      const char* msg,
      /// MSG_DONTROUTE@n
      /// MSG_DONTWAIT@n
      /// MSG_EOR@n
      /// MSG_NOSIGNAL@n
      /// MSG_OOB
      const int posix_flags,
      /// Target endpoint address structure
      const struct sockaddr *to,
      /// Size of target endpoint structure
      socklen_t tolen = sizeof(sockaddr)) {
        if (__debug) debug("sendzto(socket{0x" + randolf::rtools::to_hex(__socket_fd) + "}"
                         + ", <msg>"
                         + ", " + std::to_string(std::strlen(msg))
                         + ", " + std::to_string(posix_flags)
                         + ", <sockaddr>"
                         + ", " + std::to_string(tolen)
                         + ");");
        __track_bytes_tx(__rc_check(::sendto(__socket_fd, msg, std::strlen(msg), posix_flags, to, tolen)));
        return this;
      }; // -x- rsocket* sendzto -x-
 
      /*======================================================================*//**
      @brief
      Set socket option to the specific integer.
 
      @par Notes
      These setsockopt() methods take an integer or character value directly, or a
      pointer to a structure, and then rsocket handles the remaining tedious
      technical details behind-the-scenes for you when calling the underlying
      socket's setsockopt() function.
 
      @throws randolf::rex::xEBADF The underlying socket is not open
      @throws randolf::rex::xEFAULT Address structure/memory is not in a writable
              part of the user address space
      @throws randolf::rex::xEINVAL Address length is incorrect, or address is not
              valid for this socket's family (a.k.a., communication domain)
      @throws randolf::rex::xENOPROTOOPT Either the level or the specified optname
              is not supported
      @throws randolf::rex::xENOTSOCK Underlying socket file descriptor (handle)
              doesn't refer to a socket
 
      @returns The same rsocket object so as to facilitate stacking
      @qualifier POSIX
      @qualifier TLS
      *///=========================================================================
      rsocket* setsockopt(
      /// The level at which the option resides; typically @c SOL_SOCKET
      const int level,
      /// The name of the option, such as @c SO_REUSEADDR, @c SO_LINGER, etc.
      const int option,
      /// The value that this socket option will be set to
      const int value) {
        if (__debug) __debug_sockopt("setsockopt(socket{0x", level, option, value);
        __rc_check(::setsockopt(__socket_fd, level, option, &value, sizeof(value)));
        return this;
      }; // -x- rsocket* setsockopt -x-
 
      /*======================================================================*//**
      @brief
      Set socket option to the specific unsigned integer.
      @copydetails setsockopt(const int, const int, const int)
 
      @pre
      For any values that require a u_int, you'll need to explicitly cast this type
      when specifying the value directly; for example:  (u_int)32768
 
      @throws randolf::rex::xEBADF The underlying socket is not open
      @throws randolf::rex::xEFAULT Address structure/memory is not in a writable
              part of the user address space
      @throws randolf::rex::xEINVAL Address length is incorrect, or address is not
              valid for this socket's family (a.k.a., communication domain)
      @throws randolf::rex::xENOPROTOOPT Either the level or the specified optname
              is not supported
      @throws randolf::rex::xENOTSOCK Underlying socket file descriptor (handle)
              doesn't refer to a socket
 
      @returns The same rsocket object so as to facilitate stacking
      @qualifier TLS
      *///=========================================================================
      rsocket* setsockopt(
      /// The level at which the option resides; typically @c SOL_SOCKET
      const int level,
      /// The name of the option, such as @c SO_REUSEADDR, @c SO_LINGER, etc.
      const int option,
      /// The value that this socket option will be set to
      const u_int value) {
        if (__debug) __debug_sockopt("setsockopt(socket{0x", level, option, value);
        __rc_check(::setsockopt(__socket_fd, level, option, &value, sizeof(value)));
        return this;
      }; // -x- rsocket* setsockopt -x-
 
      /*======================================================================*//**
      @brief
      Set socket option to the specific unsigned character.
      @copydetails setsockopt(const int, const int, const int)
      @qualifier TLS
      *///=========================================================================
      rsocket* setsockopt(
      /// The level at which the option resides; typically @c SOL_SOCKET
      const int level,
      /// The name of the option, such as @c SO_REUSEADDR, @c SO_LINGER, etc.
      const int option,
      /// The value that this socket option will be set to
      const u_char value) {
        if (__debug) __debug_sockopt("setsockopt(socket{0x", level, option, value);
        __rc_check(::setsockopt(__socket_fd, level, option, &value, sizeof(value)));
        return this;
      }; // -x- rsocket* setsockopt -x-
 
      /*======================================================================*//**
      @brief
      Set socket option to the specific structure.
      @copydetails setsockopt(const int, const int, const int)
      @qualifier TLS
      *///=========================================================================
      rsocket* setsockopt(
      /// The level at which the option resides; typically @c SOL_SOCKET
      const int level,
      /// The name of the option, such as @c SO_REUSEADDR, @c SO_LINGER, etc.
      const int option,
      /// The structure that this socket option will be set to
      const linger& value) {
        if (__debug) __debug_sockopt("setsockopt(socket{0x", level, option, &value);
        __rc_check(::setsockopt(__socket_fd, level, option, &value, sizeof(value)));
        return this;
      }; // -x- rsocket* setsockopt -x-
 
      /*======================================================================*//**
      @brief
      Set socket option to the specific structure.
      @copydetails setsockopt(const int, const int, const linger&)
      @qualifier TLS
      *///=========================================================================
      rsocket* setsockopt(
      /// The level at which the option resides; typically @c SOL_SOCKET
      const int level,
      /// The name of the option, such as @c SO_REUSEADDR, @c SO_LINGER, etc.
      const int option,
      /// The structure that this socket option will be set to
      const timeval& value) {
        if (__debug) __debug_sockopt("setsockopt(socket{0x", level, option, &value);
        __rc_check(::setsockopt(__socket_fd, level, option, &value, sizeof(value)));
        return this;
      }; // -x- rsocket* setsockopt -x-
 
      /*======================================================================*//**
      @brief
      Set socket option to the specific structure.
      @copydetails setsockopt(const int, const int, const linger&)
      @qualifier TLS
      *///=========================================================================
      rsocket* setsockopt(
      /// The level at which the option resides; typically @c SOL_SOCKET
      const int level,
      /// The name of the option, such as @c SO_REUSEADDR, @c SO_LINGER, etc.
      const int option,
      /// The structure that this socket option will be set to
      const in_addr& value) {
        if (__debug) __debug_sockopt("setsockopt(socket{0x", level, option, &value);
        __rc_check(::setsockopt(__socket_fd, level, option, &value, sizeof(value)));
        return this;
      }; // -x- rsocket* setsockopt -x- 
 
      /*======================================================================*//**
      @brief
      Set socket option to the specific structure.
      @copydetails setsockopt(const int, const int, const linger&)
      @qualifier TLS
      *///=========================================================================
      rsocket* setsockopt(
      /// The level at which the option resides; typically @c SOL_SOCKET
      const int level,
      /// The name of the option, such as @c SO_REUSEADDR, @c SO_LINGER, etc.
      const int option,
      /// The structure that this socket option will be set to
      const ip_mreq& value) {
        if (__debug) __debug_sockopt("setsockopt(socket{0x", level, option, &value);
        __rc_check(::setsockopt(__socket_fd, level, option, &value, sizeof(value)));
        return this;
      }; // -x- rsocket* setsockopt -x-
 
      /*======================================================================*//**
      @brief
      Set socket option to the specific structure.
      @copydetails setsockopt(const int, const int, const linger&)
      @qualifier TLS
      *///=========================================================================
      rsocket* setsockopt(
      /// The level at which the option resides; typically @c SOL_SOCKET
      const int level,
      /// The name of the option, such as @c SO_REUSEADDR, @c SO_LINGER, etc.
      const int option,
      /// The structure that this socket option will be set to
      const ip_mreq_source& value) {
        if (__debug) __debug_sockopt("setsockopt(socket{0x", level, option, &value);
        __rc_check(::setsockopt(__socket_fd, level, option, &value, sizeof(value)));
        return this;
      }; // -x- rsocket* setsockopt -x-
 
      /*======================================================================*//**
      @brief
      Set socket option to the specific structure.
      @copydetails setsockopt(const int, const int, const linger&)
      @qualifier TLS
      *///=========================================================================
      rsocket* setsockopt(
      /// The level at which the option resides; typically @c SOL_SOCKET
      const int level,
      /// The name of the option, such as @c SO_REUSEADDR, @c SO_LINGER, etc.
      const int option,
      /// The structure that this socket option will be set to
      const icmp6_filter& value) {
        if (__debug) __debug_sockopt("setsockopt(socket{0x", level, option, &value);
        __rc_check(::setsockopt(__socket_fd, level, option, &value, sizeof(value)));
        return this;
      }; // -x- rsocket* setsockopt -x-
 
      /*======================================================================*//**
      @brief
      Set socket option to the specific structure.
      @copydetails setsockopt(const int, const int, const linger&)
      @qualifier TLS
      *///=========================================================================
      rsocket* setsockopt(
      /// The level at which the option resides; typically @c SOL_SOCKET
      const int level,
      /// The name of the option, such as @c SO_REUSEADDR, @c SO_LINGER, etc.
      const int option,
      /// The structure that this socket option will be set to
      const sockaddr_in6& value) {
        if (__debug) __debug_sockopt("setsockopt(socket{0x", level, option, &value);
        __rc_check(::setsockopt(__socket_fd, level, option, &value, sizeof(value)));
        return this;
      }; // -x- rsocket* setsockopt -x-
 
      /*======================================================================*//**
      @brief
      Set socket option to the specific structure.
      @copydetails setsockopt(const int, const int, const linger&)
      @qualifier TLS
      *///=========================================================================
      rsocket* setsockopt(
      /// The level at which the option resides; typically @c SOL_SOCKET
      const int level,
      /// The name of the option, such as @c SO_REUSEADDR, @c SO_LINGER, etc.
      const int option,
      /// The structure that this socket option will be set to
      const ip6_mtuinfo& value) {
        if (__debug) __debug_sockopt("setsockopt(socket{0x", level, option, &value);
        __rc_check(::setsockopt(__socket_fd, level, option, &value, sizeof(value)));
        return this;
      }; // -x- rsocket* setsockopt -x-
 
      /*======================================================================*//**
      @brief
      Set socket option to the specific structure.
      @copydetails setsockopt(const int, const int, const linger&)
      @qualifier TLS
      *///=========================================================================
      rsocket* setsockopt(
      /// The level at which the option resides; typically @c SOL_SOCKET
      const int level,
      /// The name of the option, such as @c SO_REUSEADDR, @c SO_LINGER, etc.
      const int option,
      /// The structure that this socket option will be set to
      const ipv6_mreq& value) {
        if (__debug) __debug_sockopt("setsockopt(socket{0x", level, option, &value);
        __rc_check(::setsockopt(__socket_fd, level, option, &value, sizeof(value)));
        return this;
      }; // -x- rsocket* setsockopt -x-
 
      /*======================================================================*//**
      @brief
      Set socket option to the specific structure.
      @copydetails setsockopt(const int, const int, const linger&)
      @qualifier TLS
      *///=========================================================================
      rsocket* setsockopt(
      /// The level at which the option resides; typically @c SOL_SOCKET
      const int level,
      /// The name of the option, such as @c SO_REUSEADDR, @c SO_LINGER, etc.
      const int option,
      /// The structure that this socket option will be set to
      const group_req& value) {
        if (__debug) __debug_sockopt("setsockopt(socket{0x", level, option, &value);
        __rc_check(::setsockopt(__socket_fd, level, option, &value, sizeof(value)));
        return this;
      }; // -x- rsocket* setsockopt -x-
 
      /*======================================================================*//**
      @brief
      Set socket option to the specific structure.
      @copydetails setsockopt(const int, const int, const linger&)
      @qualifier TLS
      *///=========================================================================
      rsocket* setsockopt(
      /// The level at which the option resides; typically @c SOL_SOCKET
      const int level,
      /// The name of the option, such as @c SO_REUSEADDR, @c SO_LINGER, etc.
      const int option,
      /// The structure that this socket option will be set to
      const group_source_req& value) {
        if (__debug) __debug_sockopt("setsockopt(socket{0x", level, option, &value);
        __rc_check(::setsockopt(__socket_fd, level, option, &value, sizeof(value)));
        return this;
      }; // -x- rsocket* setsockopt -x-
 
      /*======================================================================*//**
      @brief
      Shut down the underlying socket, partially or fully.
 
      <div style=padding-left:32px;>
        <table>
          <tr>
            <td valign=top>SHUT_RD:</td>
            <td>Further receives will be disallowed.</td>
          </tr>
          <tr>
            <td valign=top>SHUT_WR:</td>
            <td>Further sends will be disallowed (this may cause actions specific
                to the protocol family of the socket to occur).</td>
          </tr>
          <tr>
            <td valign=top>SHUT_RDWR:</td>
            <td>Further sends and receives will be disallowed (default).</td>
          </tr>
        </table>
      </div>
 
      @throws randolf::rex::xEBADF The underlying socket is not open
      @throws randolf::rex::xEINVAL Invalid argument passed
      @throws randolf::rex::xENOTCONN Underlying socket is not connected
      @throws randolf::rex::xENOTSOCK Underlying socket file descriptor (handle)
              doesn't refer to a socket
 
      @returns The same rsocket object so as to facilitate stacking
      @qualifier POSIX
      @qualifier TLS
      *///=========================================================================
      rsocket* shutdown(
      /// SHUT_RD@n
      /// SHUT_RW@n
      /// SHUT_RDWR (default)
      const int how = SHUT_RDWR,
      /// Shutdown the TLS connection too (but only if it's alrady enabled), which
      /// is the default (disabling this will usually result in errors for the
      /// endpoint upon raw socket shutdown)
      const bool tls_shutdown = true) {
        if (__debug) debug("shutdown(socket{0x" + randolf::rtools::to_hex(__socket_fd) + "}"
                         + ", " + std::to_string(how)
                         + ");");
 
        // --------------------------------------------------------------------------
        // Shut down TLS connections first, if TLS is enabled.
        //
        // If SSL_shutdown returns a 0, then it means a "bidirectional shutdown" is
        // needed which entails calling SSL_shutdown a second time.  The error codes
        // returned by SSL_shutdown are as follows:
        //
        //    1 = Shutdown completed normally
        //
        //    0 = Shutdown is not yet finished, and a second SSL_shutdown() is needed
        //
        //   -1 = Critical error, probably due to a connection problem, or because
        //        the endpoint already initiated a shutdown, etc.
        //
        // We don't really care what the second SSL_shutdown's return code is because
        // there's nothing we can do about it whatever it is.  This situation is rare
        // though, and what follows next closes the raw socket, which is OpenSSL's
        // lifeline to communicating with the endpoint.
        // --------------------------------------------------------------------------
        if (__tls && tls_shutdown) {
          if (SSL_shutdown(__tls_fd) == 0) {
            SSL_shutdown(__tls_fd);
          } // -x- if SSL_shutdown -x-
        } // -x- if __tls -x-
 
        // --------------------------------------------------------------------------
        // Shut down the raw socket.
        // --------------------------------------------------------------------------
        __rc_check(::shutdown(__socket_fd, how));
        //__socket_connected = false; // TODO: Figure out when to change this to false
        return this;
      }; // -x- rsocket* shutdown -x-
 
      /*======================================================================*//**
      @brief
      Complete the configuration of an rsocket that was previously initialized
      without any parameters (a.k.a., an "empty rsocket").
      @copydetails rsocket()
      @throws randolf::rex::xEACCES Elevated access is needed to open this socket
      @throws randolf::rex::xEAFNOSUPPORT Address family not implemented/supported
      @throws randolf::rex::xEALREADY If this socket() method was already used, or
              it was used after rsocket() initialized with at least one parameter
      @throws randolf::rex::xEINVAL Protocal family invalid or not available
      @throws randolf::rex::xEINVAL Invalid flags in type
      @throws randolf::rex::xEMFILE Per-process maximum open files limit reached
      @throws randolf::rex::xENFILE System-wide maximum open files limit reached
      @throws randolf::rex::xENOBUFS Insufficient memory
      @throws randolf::rex::xENOMEM Insufficient memory
      @throws randolf::rex::xEPROTONOSUPPORT Specified `type` or `protocol` is not
              supported within the specified family (a.k.a., communication domain)
      @returns The same rsocket object so as to facilitate stacking
      @see rsocket()
      @see socket_family()
      @see socket_fd()
      @see socket_protocol()
      @see socket_type()
      @qualifier POSIX
      @qualifier TLS
      *///=========================================================================
      rsocket* socket(
      /// Communication domain; usually one of:@n
      /// AF_INET (IPv4)@n
      /// AF_INET6 (IPv6)@n
      /// AF_UNIX (UNIX domain sockets)
      const int family,
      /// Communication semantics; usually one of:@n
      /// SOCK_STREAM (common for TCP)@n
      /// SOCK_DGRAM (common for UDP)
      const int type = SOCK_STREAM,
      /// Network protocol; usually one of:@n
      /// IPPROTO_TCP@n
      /// IPPROTO_UDP@n
      /// IPPROTO_IP@n
      /// PF_UNSPEC (auto-detect)
      const int protocol = PF_UNSPEC) {
        __socket(family, type, protocol);
        return this;
      }; // -x- rsocket* socket -x-
 
      /*======================================================================*//**
      @brief
      Get underlying socket family/domain constant (SO_DOMAIN).
      @returns socket family/domain constant
      @see port()
      @see socket()
      @see socket_fd()
      @see socket_protocol()
      @see socket_type()
      @qualifier TLS
      *///=========================================================================
      const int socket_family() noexcept { return __socket_addr.ss_family; }; // -x- int socket_family -x-
 
      /*======================================================================*//**
      @brief
      Get underlying socket descriptor/handle.
      @returns socket descriptor/handle
      @returns 0 = socket not yet allocated
      @see port()
      @see socket()
      @see socket_family()
      @see socket_protocol()
      @see socket_type()
      @qualifier TLS
      *///=========================================================================
      const int socket_fd() noexcept { return __socket_fd; }; // -x- int socket_fd -x-
 
      /*======================================================================*//**
      @brief
      Set underlying socket descriptor/handle (to one that is presumed to be open).
      @note
      This method is only available while an underlying socket has not been created
      or previously assigned, such as after an empty @ref rsocket instantiation.
      @throws randolf::rex::xEALREADY If this socket_fd() method was already used,
              or it was used after socket() initialized it, or if rsocket() had
              initialized with at least one parameter that resulted in the creation
              of an underlying socket
      @returns The same rsocket object so as to facilitate stacking
      @see socket()
      @see socket_family()
      @see socket_protocol()
      @see socket_type()
      @qualifier TLS
      *///=========================================================================
      rsocket* socket_fd(
      /// New socket descriptor/handle
      const int new_socket_fd) {
        if (__debug) debug("socket_fd(socket{0x" + randolf::rtools::to_hex(new_socket_fd) + "}"
                         + ");");
        if (__socket_fd != 0) throw randolf::rex::xEALREADY("EALREADY");
        __socket_fd             = new_socket_fd;
        __socket_addr.ss_family = getsockopt_int(SOL_SOCKET, SO_DOMAIN);
        __socket_type           = getsockopt_int(SOL_SOCKET, SO_TYPE);
        __socket_protocol       = getsockopt_int(SOL_SOCKET, SO_PROTOCOL);
        __socket_open           = true;
        return this;
      }; // -x- rsocket* socket_fd -x-
 
      /*======================================================================*//**
      @brief
      Get underlying socket protocol constant (SO_PROTOCOL).
      @returns socket protocol constant
      @see port()
      @see socket()
      @see socket_family()
      @see socket_fd()
      @see socket_type()
      @qualifier TLS
      *///=========================================================================
      const int socket_protocol() noexcept { return __socket_protocol; }; // -x- int socket_protocol -x-
 
      /*======================================================================*//**
      @brief
      Get underlying socket type constant (SO_TYPE).
      @returns socket type constant
      @see port()
      @see socket()
      @see socket_family()
      @see socket_fd()
      @see socket_protocol()
      @qualifier TLS
      *///=========================================================================
      const int socket_type() noexcept { return __socket_type; }; // -x- int socket_type -x-
 
      /*======================================================================*//**
      @brief
      Find out whether the underlying socket is at the out-of-band (OOB) mark.
 
      @throws randolf::rex::xEBADF The underlying socket is not open
      @throws randolf::rex::xEINVAL The underlying socket file descriptor is not a
              type to which @ref sockatmark() can be applied
 
      @returns TRUE = at OOB mark
      @returns FALSE = not at OOB mark
      @qualifier POSIX
      @qualifier TLS
      *///=========================================================================
      const bool sockatmark() {
        return __rc_check(::sockatmark(__socket_fd)) ? true : false;
      }; // -x- bool sockatmark -x-
 
      /*======================================================================*//**
      @brief
      Find out what the read timeout is set to on the current socket.
 
      Since getting the read timeout is such a common operation, this specialized
      method was created to ease software development efforts; internally we're
      just calling getsockopt_timeval(SOL_SOCKET, SO_RCVTIMEO).
 
      @throws randolf::rex::xEBADF The underlying socket is not open
      @throws randolf::rex::xEFAULT Address structure/memory is not in a writable
              part of the user address space
      @throws randolf::rex::xEINVAL Address length is incorrect, or address is not
              valid for this socket's family (a.k.a., communication domain)
      @throws randolf::rex::xENOPROTOOPT Either the level or the specified optname
              is not supported
      @throws randolf::rex::xENOTSOCK Underlying socket file descriptor (handle)
              doesn't refer to a socket
 
      @returns @c timeval socket option structure wrapped in std::shared_ptr
      @qualifier TLS
      *///=========================================================================
      std::shared_ptr<timeval> timeout() {
        return getsockopt_timeval(SOL_SOCKET, SO_RCVTIMEO);
      }; // -x- std::shared_ptr<timeval> timeout -x-
 
      /*======================================================================*//**
      @brief
      Set the recv timeout on the current socket.
 
      Since setting the read timeout is such a common operation, this specialized
      method was created to ease software development efforts; internally we're
      just calling setsockopt(SOL_SOCKET, SO_RCVTIMEO, timeval).
      @attention
      Although a timeout of 100,000 microseconds (1/10 of one second) may suffice
      in healthy and efficient networks, a more conservative setting of 1 second
      tends to minimally yield more reliable results.  Many end-user applications
      use defaults of 3 to 5 seconds to cover a wider variety of unpredictable
      network connections (such as over shared wireless connections that are slow),
      and this setting should ultimately be configurable by users/administrators.
 
      @note
      The default timeout for new sockets is normally 0 (no timeout).
 
      @throws randolf::rex::xEBADF The underlying socket is not open
      @throws randolf::rex::xEFAULT Address structure/memory is not in a writable
              part of the user address space
      @throws randolf::rex::xEINVAL Address length is incorrect, or address is not
              valid for this socket's family (a.k.a., communication domain)
      @throws randolf::rex::xENOPROTOOPT Either the level or the specified optname
              is not supported
      @throws randolf::rex::xENOTSOCK Underlying socket file descriptor (handle)
              doesn't refer to a socket
 
      @returns The same rsocket object so as to facilitate stacking
      @qualifier TLS
      *///=========================================================================
      rsocket* timeout(
      /// timeval structure
      const struct timeval tv) {
        return setsockopt(SOL_SOCKET, SO_RCVTIMEO, tv);
      }; // -x- rsocket* timeout -x-
 
      /*======================================================================*//**
      @copydoc timeout(struct timeval)
      @qualifier TLS
      *///=========================================================================
      rsocket* timeout(
      /// Timeout in seconds
      const int tv_sec = 0,
      /// Timeout in microseconds
      const long tv_usec = 0) {
        struct timeval tv{tv_sec, tv_usec};
        return setsockopt(SOL_SOCKET, SO_RCVTIMEO, tv);
      }; // -x- rsocket* timeout -x-
 
      /*======================================================================*//**
      @brief
      Find out what the read timeout is set to when using the @ref recvline()
      method.
 
      @returns @c long value (0 = no timeout)
      @see recvline
      @see timeout
      @see timeout_recvline(long)
      @qualifier TLS
      *///=========================================================================
      long timeout_recvline() {
        return __recvline_timeout;
      }; // -x- long timeout_recvline -x-
 
      /*======================================================================*//**
      @brief
      Set the read timeout for the @ref recvline() method (the @ref recvline()
      method's @c timeout parameter can override this setting).
 
      @note
      The default timeout for this recvline_timeout setting is 0 (no timeout).
 
      @throws randolf::rex::xERANGE if the timeout parameter is below 0
 
      @returns The same rsocket object so as to facilitate stacking
      @see recvline
      @see timeout
      @see timeout_recvline
      @qualifier TLS
      *///=========================================================================
      rsocket* timeout_recvline(
      /// timeval structure
      const long timeout) {
        if (timeout < 0) throw randolf::rex::xERANGE("timeout parameter of " + std::to_string(timeout) + " is below 0");
        __recvline_timeout = timeout;
        return this;
      }; // -x- rsocket* timeout_recvline -x-
 
      /*======================================================================*//**
      @brief
      Enable or disable encrypted communications (from the OpenSSL library).
 
      @warning
      TLS cannot be enabled before a non-encrypted rsocket is open (an rsocket is
      typically opened with the @ref socket() method, the @ref connect() method, or
      one of the @ref accept() methods).  If calling @c tls(true) on an rsocket
      that isn't open, an exception will be thrown.
 
      If needed, a new TLS context will be instantiated and TLS will be initialized
      (if this hasn't already been done).  TLS instantiation can be done first by
      calling the @ref tls_ctx() method (regardless of whether encryption is being
      enabled or disabled).  If the default @ref TLS_FLAGS aren't sufficient for
      the needs of your application, then the @ref tls_ctx() method facilitates
      this regardless of wehther rsocket is open.
 
      @note
      The reason a TLS context is instantiated and TLS is initialized even when the
      status is being set to FALSE is to facilitate TLS ingress from an unencrypted
      connection later in the session (see the @ref TLS_NO_INGRESS flag for more
      information).
 
      @post
      If a client attempts to upgrade a TLS connection to TLS (e.g., by using a
      command such as @c STARTTLS, which is commonly transmitted in unencrypted
      form, like @c telnet-ssl does -- using `telnet-ssl -z ssl` prevents this
      condition), the following error that's difficult to track down may be
      triggered when calling any of the @c recv methods (I hope that including this
      information here in this documentation will be helpful):
      @verbatim
      SSL_ERROR_UNKNOWN: error:0A00010B:SSL routines::wrong version number
      @endverbatim
      This is most likely not a programming error, but rather a problem with how
      users may attempt to mis-use a connection based on a misunderstanding of the
      communications requirements (e.g., connecting unencrypted and attempting to
      upgrade to TLS over a connection that's expecting TLS encrypted data from the
      very beginning, without involving any ingress).
 
      @throws randolf::rex::xALL Catch this exception for now (at this time, the
              OpenSSL library doesn't document which errors may be returned)
 
      @returns The same rsocket object so as to facilitate stacking
      @see is_tls
      @see tls_ctx
      @qualifier TLS
      *///=========================================================================
      rsocket* tls(
      /// TRUE = Enable encrypted communications@n FALSE = Disable encrypted communications
      const bool status = true,
      /// Configuration parameters
      const int flags = TLS_FLAGS::TLS_DEFAULT) { //  | TLS_FLAGS::TLS_CLIENT
        if (__debug) debug("tls(socket{0x" + randolf::rtools::to_hex(__socket_fd) + "}"
                         + ", " + (status ? "true" : "false")
                         + ");");
 
        // --------------------------------------------------------------------------
        // Create default context (with "flags" passthrough), unless it was already
        // created (usually by one of the tls_ctx() methods).
        // --------------------------------------------------------------------------
        if (__tls_ctx == nullptr) tls_ctx((SSL_CTX*)nullptr, flags);
 
        // --------------------------------------------------------------------------
        // Make sure tls_fd (ssl_fd) is allocated.  If not, then it needs to be
        // allocated and configured.
        // --------------------------------------------------------------------------
        if (status == true && __tls_fd == nullptr) {
          __tls_fd = SSL_new(__tls_ctx);
          if (__debug) debug("SSL_set_fd(<tls_fd>, socket{0x" + randolf::rtools::to_hex(__socket_fd) + "}"
                           + ");");
 
          // --------------------------------------------------------------------------
          // Associate OpenSSL file descriptor with underlying socket file descriptor.
          // --------------------------------------------------------------------------
          __rc_check_tls(SSL_set_fd(__tls_fd, __socket_fd));
 
          // --------------------------------------------------------------------------
          // Enable read-ahead so that SSL_peek will work properly.
          // --------------------------------------------------------------------------
          SSL_CTX_set_read_ahead(__tls_ctx, 1); // 0=disable / 1=enable
              SSL_set_read_ahead(__tls_fd,  1); // 0=disable / 1=enable
 
//          SSL_CTX_set_max_pipelines(__tls_ctx, SSL_MAX_PIPELINES); // SSL_MAX_PIPELINES = 32
//              SSL_set_max_pipelines(__tls_fd,  SSL_MAX_PIPELINES); // SSL_MAX_PIPELINES = 32
 
//          SSL_CTX_set_mode(__tls_ctx, SSL_MODE_AUTO_RETRY);
//              SSL_set_mode(__tls_fd,  SSL_MODE_AUTO_RETRY);
 
          // --------------------------------------------------------------------------
          // We're probably not going to use BIO because we don't need it, and it adds
          // unnecessary overhead for what we're doing.  Also, BIO doesn't provide an
          // alternative to the SSL_peek function, and also doesn't resolve the need
          // for the MSG_WAITALL flag that the ::recv() function supports.
          //
          // TODO:  Remove this completely, unless is can solve the problem of reading
          //        all incoming data (needed for readline, primarily)
          // --------------------------------------------------------------------------
          __tls_rbio = SSL_get_rbio(__tls_fd);
          __tls_wbio = SSL_get_wbio(__tls_fd);
 
        } // -x- if !__tls_fd -x-
        __tls = status;
        return this;
      }; // -x- rsocket* tls -x-
 
      /*======================================================================*//**
      @brief
      Return the current TLS context (multiple TLS contexts are supported, although
      typically needed to support SNI with inbound connections).
      @returns Pointer to OpenSSL's context (normally labelled @c SSL_CTX* in the
               documentation for OpenSSL), or nullptr if this context was never
               assigned to (or created by) this rsocket
      @see tls_ctx
      @qualifier TLS
      *///=========================================================================
      SSL_CTX* tls_ctx() noexcept {
        return __tls_ctx;
      }; // -x- SSL_CTX* tls_ctx -x-
 
      /*======================================================================*//**
      @brief
      Copy the source rsocket's TLS context map and add it to this rsocket's
      collection; or, if the source doesn't have any TLS contexts and this rsocket
      doesn't have any TLS contexts in its collection, then initialize TLS and
      instantiate a new TLS context.  In either scenario, the source rsocket will
      be treated as a template as all TLS flags duplicated to enable encrypted
      socket I/O for use in this rsocket().
 
      @note
      At least one TLS context is needed to enable encrypted socket I/O for use in
      this rsocket().
 
      @post
      Encrypted socket I/O is only possible after a TLS context has been
      initialized (this is not a global setting as it has per-rsocket specificity).
 
      @note
      The only @ref TLS_FLAGS flag that doesn't get transferred is @ref TLS_SERVER
      when no flags are specified.  Specifying any flag(s) will cause this method
      to ignore the source rsocket's TLS flags so as to defer to this override.
 
      @throws randolf::rex::xALL Catch this exception for now (at this time, the
              OpenSSL library doesn't document which errors may be returned)
 
      @returns The same rsocket object so as to facilitate stacking
      @see tls_sni
      @qualifier TLS
      *///=========================================================================
      rsocket* tls_ctx(
      /// OpenSSL's TLS context to use (if not provided, a new context will be
      /// created automatically using OpenSSL's defaults)
      rsocket* rtemplate,
      /// Configuration parameters
      const int flags = TLS_FLAGS::TLS_DEFAULT) {
        if (__debug) debug("tls_ctx(socket{0x" + randolf::rtools::to_hex(__socket_fd) + "}"
                         + ", <rsocket>"
                         + ", " + std::to_string(flags)
                         + ");");
 
        // --------------------------------------------------------------------------
        // TLS-related variables (OpenSSL).
        //
        // Note:  The __tls_fd variable cannot be allocated until after __socket_fd
        //        has been, hence the "post" note in the documentation.
        // --------------------------------------------------------------------------
        __tls             = (bool)rtemplate->__tls; // Preserve TLS mode setting
        if (rtemplate->__tls_ctx != nullptr) { // If TLS context is defined, then do these important things:
          __tls_ctx       = rtemplate->__tls_ctx;   // 1. copy the pointer to SSL_CTX
          SSL_CTX_up_ref(__tls_ctx);                      // 2. increment SSL_CTX's internal reference count
        } // -x- if __tlx_ctx -x-
 
        // --------------------------------------------------------------------------
        // Copy or override TLS flags.
        // --------------------------------------------------------------------------
        if (flags == TLS_FLAGS::TLS_DEFAULT) {
          __tls_exclusive = rtemplate->__tls_exclusive; // TLS policy
          __tls_egress    = rtemplate->__tls_egress;    // TLS policy
          __tls_ingress   = rtemplate->__tls_ingress;   // TLS policy
        } else { // Save flags
        __tls_exclusive   =   flags & TLS_FLAGS::TLS_EXCLUSIVE;
        __tls_ingress     = !(flags & TLS_FLAGS::TLS_NO_INGRESS);
        __tls_egress      = !(flags & TLS_FLAGS::TLS_NO_EGRESS);
        __tls_server_mode =  (flags & TLS_FLAGS::TLS_SERVER);
        } // -x- if flags -x-
 
        return this;
      }; // -x- rsocket* tls_ctx -x-
 
      /*======================================================================*//**
      @brief
      Initialize TLS and instantiate a TLS context, and add it to this rsocket's
      current collection of TLS contexts, and set it as the currently active TLS
      context (so that a certificate chain and private key may be added to it).
      @note
      At least one TLS context is needed to enable encrypted socket I/O for use in
      this rsocket().
      @post
      Encrypted socket I/O is only possible after a TLS context has been
      initialized (this is not a global setting as it has per-rsocket specificity).
      @note
      This is the default TLS context for this @c rsocket, which will also be used
      for non-SNI handshakes.
 
      @throws randolf::rex::xALL Catch this exception for now (at this time, the
              OpenSSL library doesn't document which errors may be returned)
 
      @returns The same rsocket object so as to facilitate stacking
      @see tls_sni
      @qualifier TLS
      *///=========================================================================
      rsocket* tls_ctx(
      /// OpenSSL's TLS context to use (if not provided, a new context will be
      /// created using OpenSSL's defaults)
      SSL_CTX* ctx,
      /// Configuration parameters
      const int flags = TLS_FLAGS::TLS_DEFAULT) {
        if (__debug) debug("tls_ctx(socket{0x" + randolf::rtools::to_hex(__socket_fd) + "}"
                         + ", <ctx>"
                         + ", " + std::to_string(flags)
                         + ");");
 
        // --------------------------------------------------------------------------
        // Ignore repeated calls to this method.
        // --------------------------------------------------------------------------
        if (__tls_ctx != nullptr) return this;
 
        // --------------------------------------------------------------------------
        // Fire up OpenSSL's algorithms and pre-load its error strings.
        //
        // These two functions have been deprecated since OpenSSL v1.1.0, so we don't
        // need to call them.  If someone needs them, then they can always call them
        // in their own code anyway.
        // --------------------------------------------------------------------------
        //OpenSSL_add_all_algorithms(); // Load and register cryptography algorithms
        //SSL_load_error_strings();     // Load all error messages into memory
 
        // --------------------------------------------------------------------------
        // Save (ctx != nullptr) or create (ctx == nullptr) OpenSSL context.
        // --------------------------------------------------------------------------
        __tls_ctx = ctx == nullptr ? SSL_CTX_new(flags & TLS_FLAGS::TLS_SERVER ? TLS_server_method() : TLS_client_method()) // Create anew (default)
                                   : ctx; // Use OpenSSL context that was provided
        if (__tls_ctx == nullptr) randolf::rex::mk_exception("Cannot create TLS context", 0, rex::rex::REX_FLAGS::REX_FIND_ERRNO | rex::rex::REX_FLAGS::REX_TLS);
 
        // --------------------------------------------------------------------------
        // Enable read-ahead so that SSL_peek will work properly.
        // --------------------------------------------------------------------------
        SSL_CTX_set_read_ahead(__tls_ctx, 1); // 0=disable / 1=enable
 
        // --------------------------------------------------------------------------
        // Save flags.
        // --------------------------------------------------------------------------
        __tls_exclusive   =   flags & TLS_FLAGS::TLS_EXCLUSIVE;
        __tls_ingress     = !(flags & TLS_FLAGS::TLS_NO_INGRESS);
        __tls_egress      = !(flags & TLS_FLAGS::TLS_NO_EGRESS);
        __tls_server_mode =  (flags & TLS_FLAGS::TLS_SERVER);
 
        return this;
      }; // -x- rsocket* tls_ctx -x-
 
      /*======================================================================*//**
      @brief
      Check the private key it to ensure it's consistent with the corresponding TLS
      certificate chain.
 
      @throws randolf::rex::xALL Catch this exception for now (at this time, the
              OpenSSL library doesn't document which errors may be returned)
 
      @returns The same rsocket object so as to facilitate stacking
      @see tls_ctx_use_privatekey_file
      @see tls_ctx_use_privatekey_pem
      @qualifier TLS
      *///=========================================================================
      rsocket* tls_ctx_check_privatekey() {
        if (__debug) debug("tls_ctx_check_privatekey();");
        if (!SSL_CTX_check_private_key(__tls_ctx)) randolf::rex::mk_exception("Cannot validate consistency between certificate chain and private key", 0, rex::rex::REX_FLAGS::REX_FIND_ERRNO | rex::rex::REX_FLAGS::REX_TLS);
        return this;
      }; // -x- rsocket* tls_ctx_check_privatekey -x-
 
      /*======================================================================*//**
      @brief
      Load a TLS certificate chain and private key in PEM format from text files
      and use them in the TLS context.
 
      @throws randolf::rex::xALL Catch this exception for now (at this time, the
              OpenSSL library doesn't document which errors may be returned)
 
      @returns The same rsocket object so as to facilitate stacking
      @see tls_ctx_use_certificate_chain_and_privatekey_pems
      @see tls_ctx_use_certificate_chain_file
      @see tls_ctx_use_certificate_chain_pem
      @see tls_ctx_use_privatekey_file
      @see tls_ctx_use_privatekey_pem
      @see tls_ctx_check_privatekey
      @qualifier TLS
      *///=========================================================================
      rsocket* tls_ctx_use_certificate_chain_and_privatekey_files(
      /// Pointer to ASCIIZ path and filename to certificate chain file (@c nullptr
      /// will simply be ignored)
      const char* chain_file,
      /// Pointer to ASCIIZ path and filename to private key file (@c nullptr will
      /// simply be ignored)
      const char* key_file) {
        if (__debug) debug("tls_ctx_use_certificate_chain_and_privatekey_files("
                         +        std::string(chain_file)
                         + ", " + std::string(  key_file)
                         + ");");
        if (chain_file != nullptr) tls_ctx_use_certificate_chain_file(chain_file);
        if (  key_file != nullptr) tls_ctx_use_privatekey_file(         key_file);
        return this;
      }; // -x- rsocket* tls_ctx_use_certificate_chain_and_privatekey_files -x-
 
      /*======================================================================*//**
      @brief
      Load a TLS certificate chain and private key in PEM format from text files
      and use them in the TLS context.
 
      @throws randolf::rex::xALL Catch this exception for now (at this time, the
              OpenSSL library doesn't document which errors may be returned)
 
      @returns The same rsocket object so as to facilitate stacking
      @see tls_ctx_use_certificate_chain_and_privatekey_pems
      @see tls_ctx_use_certificate_chain_file
      @see tls_ctx_use_certificate_chain_pem
      @see tls_ctx_use_privatekey_file
      @see tls_ctx_use_privatekey_pem
      @see tls_ctx_check_privatekey
      @qualifier TLS
      *///=========================================================================
      rsocket* tls_ctx_use_certificate_chain_and_privatekey_files(
      /// Pointer to ASCIIZ path and filename to certificate chain file (an empty
      /// string will simply be ignored)
      const std::string chain_file,
      /// Pointer to ASCIIZ path and filename to private key file (an empty string
      /// will simply be ignored)
      const std::string key_file) {
        if (__debug) debug("tls_ctx_use_certificate_chain_and_privatekey_files("
                         +      chain_file
                         + ", " + key_file
                         + ");");
        if (!chain_file.empty()) tls_ctx_use_certificate_chain_file(chain_file);
        if (  !key_file.empty()) tls_ctx_use_privatekey_file(         key_file);
        return this;
      }; // -x- rsocket* tls_ctx_use_certificate_chain_and_privatekey_files -x-
 
      /*======================================================================*//**
      @brief
      Load a TLS certificate chain and a TLS private key in PEM format from memory
      and use them in the TLS context.
 
      Although this functionality doesn't exist in OpenSSL (at the time of writing
      this method), it's provided here in a manner that has exactly the same effect
      as the @ref tls_ctx_use_certificate_chain_and_privatekey_files() methods, but
      without needing the PEM-formatted certificate chain stored in files
      beforehand.
 
      @note
      The @c cert_pem_data and key_pem_data parameters are pointers to the memory
      locations that holds the PEM formatted certificate chain data and private key
      data, respectively.  If the corresponding lengths of each of these data aren't
      specified or are set to zero (default), then they will be treated as multiline
      ASCIIZ strings.
 
      Behind the scenes, we're just writing the cert_pem_data and key_pem_data
      memory to temporary files with severely-limited permissions (), then
      optionally overwriting those temporary files with random data prior to
      deleting them (this is the default, since better security practices should be
      the default, but on a secured system it may not be necessary and so this
      option can also be disabled to save CPU cycles and reduce overall disk-write
      I/O operations).
 
      @throws randolf::rex::xALL Catch this exception for now (at this time, the
              OpenSSL library doesn't document which errors may be returned)
 
      @returns The same rsocket object so as to facilitate stacking
      @see tls_ctx_use_certificate_chain_and_privatekey_files
      @see tls_ctx_use_certificate_chain_file
      @see tls_ctx_use_certificate_chain_pem
      @see tls_ctx_use_privatekey_file
      @see tls_ctx_use_privatekey_pem
      @see tls_ctx_check_privatekey
      @qualifier TLS
      *///=========================================================================
      rsocket* tls_ctx_use_certificate_chain_and_privatekey_pems(
      /// Pointer to certificate chain data in PEM format
      const char* cert_pem_data,
      /// Pointer to private key data in PEM format
      const char* key_pem_data,
      /// Length of cert_pem_data (in bytes), or 0 to auto-detect length if cert_pem_data is an ASCIIZ string
      size_t cert_len = 0,
      /// Length of key_pem_data (in bytes), or 0 to auto-detect length if key_pem_data is an ASCIIZ string
      size_t key_len = 0,
      /// Whether to overwrite the temporary files with random data before deleting them
      const bool random_fill = true) {
        tls_ctx_use_certificate_chain_pem(cert_pem_data, cert_len, random_fill);
        tls_ctx_use_privatekey_pem(        key_pem_data,  key_len, random_fill);
        return this;
      }; // -x- rsocket* tls_ctx_use_certificate_chain_and_privatekey_pems -x-
 
      /*======================================================================*//**
      @brief
      Load a TLS certificate chain in PEM format from a text file and use it in the
      TLS context.
 
      @throws randolf::rex::xALL Catch this exception for now (at this time, the
              OpenSSL library doesn't document which errors may be returned)
 
      @returns The same rsocket object so as to facilitate stacking
      @see tls_ctx_use_certificate_chain_file
      @see tls_ctx_use_certificate_chain_pem
      @see tls_ctx_check_privatekey
      @qualifier TLS
      *///=========================================================================
      rsocket* tls_ctx_use_certificate_chain_file(
      /// Pointer to ASCIIZ path and filename to certificate chain file
      const char* file) {
        if (__debug) debug("tls_ctx_use_certificate_chain_file("
                         + std::string(file)
                         + ");");
        if (SSL_CTX_use_certificate_chain_file(__tls_ctx, file) != 1) randolf::rex::mk_exception(std::string("Cannot use certificate chain file ") + file, 0, rex::rex::REX_FLAGS::REX_FIND_ERRNO | rex::rex::REX_FLAGS::REX_TLS);
        return this;
      }; // -x- rsocket* tls_ctx_use_certificate_chain_file -x-
 
      /*======================================================================*//**
      @brief
      Load a TLS certificate chain in PEM format from a text file and use it in the
      TLS context.
 
      @throws randolf::rex::xALL Catch this exception for now (at this time, the
              OpenSSL library doesn't document which errors may be returned)
 
      @returns The same rsocket object so as to facilitate stacking
      @see tls_ctx_use_certificate_chain_file
      @see tls_ctx_use_certificate_chain_pem
      @see tls_ctx_check_privatekey
      @qualifier TLS
      *///=========================================================================
      rsocket* tls_ctx_use_certificate_chain_file(
      /// Path and filename to certificate chain file
      const std::string file) {
        if (__debug) debug("tls_ctx_use_certificate_chain_file("
                         + file
                         + ");");
        if (SSL_CTX_use_certificate_chain_file(__tls_ctx, file.c_str()) != 1) randolf::rex::mk_exception("Cannot use certificate chain file " + file, 0, rex::rex::REX_FLAGS::REX_FIND_ERRNO | rex::rex::REX_FLAGS::REX_TLS);
        return this;
      }; // -x- rsocket* tls_ctx_use_certificate_chain_file -x-
 
      /*======================================================================*//**
      @brief
      Load a TLS certificate chain in PEM format from memory and use it in the TLS
      context.
 
      Although this functionality doesn't exist in OpenSSL (at the time of writing
      this method), it's provided here in a manner that has exactly the same effect
      as the @ref tls_ctx_use_certificate_chain_file() methods, but without needing
      the PEM-formatted certificate chain stored in a file beforehand.
 
      @note
      The @c pem_data parameter is a pointer to the memory location that holds
      the PEM formatted certificate chain data.  If the length of this data isn't
      specified or is set to zero (default), then it will be treated as a multiline
      ASCIIZ string.
 
      Behind the scenes, we're just writing the pem_data memory to a temporary
      file with severely-limited permissions (), then optionally overwriting that
      temporary file with random data prior to deleting it (this is the default,
      since better security practices should be the default, but on a secured
      system it may not be necessary and so this option can also be disabled to
      save CPU cycles and reduce overall disk-write I/O operations).
 
      @throws randolf::rex::xALL Catch this exception for now (at this time, the
              OpenSSL library doesn't document which errors may be returned)
 
      @returns The same rsocket object so as to facilitate stacking
      @see tls_ctx_use_certificate_chain_file
      @see tls_ctx_check_privatekey
      @qualifier TLS
      *///=========================================================================
      rsocket* tls_ctx_use_certificate_chain_pem(
      /// Pointer to certificate chain data in PEM format
      const char* pem_data,
      /// Length of pem_data (in bytes), or 0 to auto-detect length if pem_data is an ASCIIZ string
      size_t len = 0,
      /// Whether to overwrite the temporary file with random data before deleting it
      const bool random_fill = true) {
        if (__debug) debug("tls_ctx_use_certificate_chain_pem(<buf>, " + std::to_string(len)
                         + ", " + (random_fill ? "true" : "false")
                         + ");");
 
        // --------------------------------------------------------------------------
        // Measure size of certificate chain if an ASCIIZ string was indicated.
        // --------------------------------------------------------------------------
        if (len == 0) len = std::strlen(pem_data);
 
        // --------------------------------------------------------------------------
        // Generate filename for temporary use.
        // --------------------------------------------------------------------------
        std::string file = std::filesystem::temp_directory_path();
        file.append("/rsocket.")
            .append(std::to_string(::getpid()))
            .append(".")
            .append(std::to_string(__fn_counter.fetch_add(1, std::memory_order_relaxed)));
 
        // --------------------------------------------------------------------------
        // Open temporary file.
        // --------------------------------------------------------------------------
        FILE* fp = fopen(file.c_str(), "w+");
        if (fp == nullptr) randolf::rex::mk_exception("Cannot open temporary file (to use certificate chain) " + file, 0, rex::rex::REX_FLAGS::REX_FIND_ERRNO);
        { int attr;
          ioctl(fileno(fp), FS_IOC_GETFLAGS, &attr);
          attr |= FS_NOATIME_FL // Don't update access time attribute
               |  FS_NODUMP_FL  // Don't include in filesystem backup dumps
               |  FS_SECRM_FL;  // Mark file for secure deletion (where supported)
          ioctl(fileno(fp), FS_IOC_SETFLAGS, &attr);
        }
        fchmod(fileno(fp), S_IRUSR | S_IWUSR);
        if (fputs(pem_data, fp) == EOF) {
          fclose(fp);
          randolf::rex::mk_exception("Cannot write to temporary file (to use certificate chain) " + file, 0, rex::rex::REX_FLAGS::REX_FIND_ERRNO);
        } // -x- if !fputs -x-
        fflush(fp);
 
        // --------------------------------------------------------------------------
        // Attempt to load certificate chain file, but save the error code for later
        // because we need to clean up the temporary file before possibly throwing an
        // exception.
        // --------------------------------------------------------------------------
        int rc = SSL_CTX_use_certificate_chain_file(__tls_ctx, file.c_str());
 
        // --------------------------------------------------------------------------
        // Overwrite the contenst of the temporary file before deleting it so as to
        // sabotage a simple attempt to undelete the file and access the certificate.
        //
        // We're also re-using the "len" local variable because it's not needed once
        // we get the loop started, and it's more optimal to not allocate yet another
        // local variable while "len" goes to waste.  :D
        // --------------------------------------------------------------------------
        if (random_fill) { // This option is configurable
          fseek(fp, 0, SEEK_SET);                         // File file position pointer to the beginning
          ::srand(::time(0) + __fn_counter);              // Current time + atomic __fn_counter value helps add variety
          for (int i = len / sizeof(int) + (::rand() & 127); i >= 0; i--) {  // Fill contents of file with random data
            len = ::rand() + (len >> (sizeof(int) >> 2)); // Bias random data toward containing more set bits (more 1's)
            fwrite(&len, sizeof(int), 1, fp);             // Write one integer at a time
          } // -x- for i -x-
        } // -x- if randfill -x-
        fchmod(fileno(fp), 0);                            // Remove all permissions
        fclose(fp);                                       // Close file handle
        unlink(file.c_str());                              // Delete temporary file
 
        // --------------------------------------------------------------------------
        // Error check ... was delayed here until after temporary file cleanup.
        // --------------------------------------------------------------------------
        if (rc != 1) randolf::rex::mk_exception("Cannot use certificate chain file " + file, 0, rex::rex::REX_FLAGS::REX_FIND_ERRNO | rex::rex::REX_FLAGS::REX_TLS);
 
        return this;
      }; // -x- rsocket* tls_ctx_use_certificate_chain_pem -x-
 
      /*======================================================================*//**
      @brief
      Load a TLS private key in PEM format from a text file and use it in the TLS
      context.
 
      @throws randolf::rex::xALL Catch this exception for now (at this time, the
              OpenSSL library doesn't document which errors may be returned)
 
      @returns The same rsocket object so as to facilitate stacking
      @see tls_ctx_use_privatekey_file
      @see tls_ctx_use_privatekey_pem
      @see tls_ctx_check_privatekey
      @qualifier TLS
      *///=========================================================================
      rsocket* tls_ctx_use_privatekey_file(
      /// Pointer to ASCIIZ path-and-filename of private key file
      const char* file) {
        if (__debug) debug("tls_ctx_use_privatekey_file("
                         + std::string(file)
                         + ");");
        if (SSL_CTX_use_PrivateKey_file(__tls_ctx, file, SSL_FILETYPE_PEM) != 1) randolf::rex::mk_exception(std::string("Cannot use private key file ") + file, 0, rex::rex::REX_FLAGS::REX_FIND_ERRNO | rex::rex::REX_FLAGS::REX_TLS);
 
        return this;
      }; // -x- rsocket* tls_ctx_use_privatekey_file -x-
 
      /*======================================================================*//**
      @brief
      Load a TLS private key in PEM format from a text file and use it in the TLS
      context.
 
      @throws randolf::rex::xALL Catch this exception for now (at this time, the
              OpenSSL library doesn't document which errors may be returned)
 
      @returns The same rsocket object so as to facilitate stacking
      @see tls_ctx_use_privatekey_file
      @see tls_ctx_use_privatekey_pem
      @see tls_ctx_check_privatekey
      @qualifier TLS
      *///=========================================================================
      rsocket* tls_ctx_use_privatekey_file(
      /// Path and filename to private key file
      const std::string file) {
        if (__debug) debug("tls_ctx_use_privatekey_file("
                         + file
                         + ");");
        if (SSL_CTX_use_PrivateKey_file(__tls_ctx, file.c_str(), SSL_FILETYPE_PEM) != 1) randolf::rex::mk_exception("Cannot use private key file " + file, 0, rex::rex::REX_FLAGS::REX_FIND_ERRNO | rex::rex::REX_FLAGS::REX_TLS);
 
        return this;
      }; // -x- rsocket* tls_ctx_use_privatekey_file -x-
 
      /*======================================================================*//**
      @brief
      Load a TLS private key in PEM format from memory and use it in the TLS
      context.
 
      Although this functionality doesn't exist in OpenSSL (at the time of writing
      this method), it's provided here in a manner that has exactly the same effect
      as the @ref tls_ctx_use_privatekey_file() methods, but without needing the
      PEM-formatted private key stored in a file beforehand.
 
      @note
      The @c pem_data parameter is a pointer to the memory location that holds the
      PEM formatted private key data.  If the length of this data isn't specified
      or is set to zero (default), then it will be treated as a multiline ASCIIZ
      string.
 
      Behind the scenes, we're just writing the pem_data memory to a temporary
      file (with severely-limited permissions), then optionally overwriting that
      temporary file with random data prior to deleting it (this is the default,
      since better security practices should be the default, but on a secured
      system it may not be necessary and so this option can also be disabled to
      save CPU cycles and reduce overall disk-write I/O operations).
 
      @throws randolf::rex::xALL Catch this exception for now (at this time, the
              OpenSSL library doesn't document which errors may be returned)
 
      @returns The same rsocket object so as to facilitate stacking
      @see tls_ctx_use_privatekey_file
      @see tls_ctx_check_privatekey
      @qualifier TLS
      *///=========================================================================
      rsocket* tls_ctx_use_privatekey_pem(
      /// Pointer to private key data in PEM format
      const char* pem_data,
      /// Length of pem_data (in bytes), or 0 to auto-detect length if pem_data is an ASCIIZ string
      size_t len = 0,
      /// Whether to overwrite the temporary file with random data before deleting it
      const bool random_fill = true) {
        if (__debug) debug("tls_ctx_use_privatekey_pem(<buf>, " + std::to_string(len)
                         + ", " + (random_fill ? "true" : "false")
                         + ");");
 
        // --------------------------------------------------------------------------
        // Measure size of private key if an ASCIIZ string was indicated.
        // --------------------------------------------------------------------------
        if (len == 0) len = std::strlen(pem_data);
 
        // --------------------------------------------------------------------------
        // Generate filename for temporary use.
        // --------------------------------------------------------------------------
        std::string file = std::filesystem::temp_directory_path();
        file.append("/rsocket.")
            .append(std::to_string(::getpid()))
            .append(".")
            .append(std::to_string(__fn_counter.fetch_add(1, std::memory_order_relaxed)));
 
        // --------------------------------------------------------------------------
        // Open temporary file.
        // --------------------------------------------------------------------------
        FILE* fp = fopen(file.c_str(), "w+");
        if (fp == nullptr) randolf::rex::mk_exception("Cannot cannot open temporary file (to use private key) " + file, 0, rex::rex::REX_FLAGS::REX_FIND_ERRNO);
        fchmod(fileno(fp), S_IRUSR | S_IWUSR);
        if (fputs(pem_data, fp) == EOF) {
          fclose(fp);
          randolf::rex::mk_exception("Cannot cannot write to temporary file (to use private key) " + file, 0, rex::rex::REX_FLAGS::REX_FIND_ERRNO);
        } // -x- if !fputs -x-
        fflush(fp);
 
        // --------------------------------------------------------------------------
        // Attempt to load private key file, but save the error code for later
        // because we need to clean up the temporary file before possibly throwing an
        // exception.
        // --------------------------------------------------------------------------
        int rc = SSL_CTX_use_PrivateKey_file(__tls_ctx, file.c_str(), SSL_FILETYPE_PEM);
 
        // --------------------------------------------------------------------------
        // Overwrite the contenst of the temporary file before deleting it so as to
        // sabotage a simple attempt to undelete the file and access the certificate.
        //
        // We're also re-using the "len" local variable because it's not needed once
        // we get the loop started, and it's more optimal to not allocate yet another
        // local variable while "len" goes to waste.  :D
        // --------------------------------------------------------------------------
        if (random_fill) { // This option is configurable
          fseek(fp, 0, SEEK_SET);                         // File file position pointer to the beginning
          ::srand(::time(0) + __fn_counter);              // Current time + atomic __fn_counter value helps add variety
          for (int i = len / sizeof(int) + (::rand() & 127); i >= 0; i--) {  // Fill contents of file with random data
            len = ::rand() + (len >> (sizeof(int) >> 2)); // Bias random data toward containing more set bits (more 1's)
            fwrite(&len, sizeof(int), 1, fp);             // Write one integer at a time
          } // -x- for i -x-
        } // -x- if randfill -x-
        fchmod(fileno(fp), 0);                            // Remove all permissions
        fclose(fp);                                       // Close file handle
        unlink(file.c_str());                              // Delete temporary file
 
        // --------------------------------------------------------------------------
        // Error check ... was delayed here until after temporary file cleanup.
        // --------------------------------------------------------------------------
        if (rc != 1) randolf::rex::mk_exception("Cannot use private key file " + file, 0, rex::rex::REX_FLAGS::REX_FIND_ERRNO | rex::rex::REX_FLAGS::REX_TLS);
 
        return this;
      }; // -x- rsocket* tls_ctx_use_privatekey_pem -x-
 
      /*======================================================================*//**
      @brief
      Initiate the TLS handshake with the endpoint (which is presumed to be a
      server).
      This method makes it easier to support application-level commands such as @c
      STARTTLS (which are implemented in protocols like SMTP, POP3, IMAP4, MEOW,
      FTP, NNTP, LDAP, XMPP, etc.).
 
      @throws randolf::rex::xALL Catch this exception for now (at this time, the
              OpenSSL library doesn't document which errors may be returned)
 
      @returns The same rsocket object so as to facilitate stacking
      @see connect()
      @see connect(std::string, int)
      @see TLS_NO_INGRESS
      @qualifier TLS
      *///=========================================================================
      rsocket* tls_do_handshake() {
        if (__debug) debug("tls_handshake(socket{0x" + randolf::rtools::to_hex(__socket_fd) + "}"
                         + ");");
        __rc_check_tls(SSL_do_handshake(__tls_fd));
        return this;
      }; // -x- rsocket* tls_do_handshake -x-
 
      /*======================================================================*//**
      @brief
      Get OpenSSL's TLS structure.
      @returns TLS structure
      @returns nullptr = TLS structure not yet allocated
      @qualifier TLS
      *///=========================================================================
      const SSL* tls_fd() noexcept {
        return __tls_fd;
      }; // -x- int tls_fd -x-
 
      /*======================================================================*//**
      @brief
      Return the current @ref rsocket_sni object that this @c rsocket will use when
      accepting incoming encrypted connections.
      @returns Pointer to @c rsocket_sni object
      @returns nullptr = SNI is not assigned
      @see name_sni
      @see tls_sni(rsocket_sni*)
      @qualifier TLS
      *///=========================================================================
      rsocket_sni* tls_sni() noexcept {
        return __tls_sni;
      }; // -x- rsocket_sni* tls_sni -x-
 
      /*======================================================================*//**
      @brief
      Set the current @ref rsocket_sni object that this @c rsocket will use when
      accepting incoming encrypted connections.
 
      Use the @ref name() method to find out which server name was supplied by the
      endpoint that triggered the SNI callback, regardless of whether it matches
      any of the TLS certificates used with this rsocket object or the rsocket_sni
      object that's associated with this rsocket object.  If an SNI callback wasn't
      triggered, or if the endpoint didn't provide a server name, then it will
      remain unaffected (and the default {empty string} will remain unchanged).
      @returns The same rsocket object so as to facilitate stacking
      @see name_sni
      @see tls_sni
      @see is_tls_sni_match
      @qualifier TLS
      *///=========================================================================
      rsocket* tls_sni(
      /// Pointer to the @ref rsocket_sni object to use, or specify @c nullptr to
      /// remove SNI support from this rsocket object
      rsocket_sni* sni) noexcept {
 
        // --------------------------------------------------------------------------
        // Remove SNI support.
        // --------------------------------------------------------------------------
        if (sni == nullptr) {
          if (__tls_sni != nullptr) SSL_CTX_set_client_hello_cb(__tls_ctx, nullptr, this);
 
        // --------------------------------------------------------------------------
        // Add or set SNI support.
        // --------------------------------------------------------------------------
        } else {
          SSL_CTX_set_client_hello_cb(__tls_ctx, tls_sni_callback, this); // Configure SNI callbacks for TLS.
          //SSL_CTX_set_tlsext_servername_callback(__tls_ctx, tls_sni_callback); // Don't use this anymore; it's outdated
          //SSL_CTX_set_tlsext_servername_arg(__tls_ctx, this); // Don't use this anymore; it's outdated
 
        } // -x- if !sni -x-
 
        // --------------------------------------------------------------------------
        // Update internal pointer to the SNI map.
        // --------------------------------------------------------------------------
        __tls_sni = sni;
 
        return this;
      }; // -x- rsocket_sni* tls_sni -x-
 
private:
      /*======================================================================*//**
      @brief
      Get OpenSSL's TLS structure.
      @returns TLS structure
      @returns nullptr = TLS structure not yet allocated
      @qualifier TLS
      *///=========================================================================
      int static tls_sni_callback(
      /// OpenSSL's socket descriptor/handle
      SSL* tls_fd,
      /// Where to store the @c alert value
      int* al,
      /// Context-specific argument
      void* arg) noexcept {
 
        // --------------------------------------------------------------------------
        // Internal variables.
        // --------------------------------------------------------------------------
        rsocket*             r        = (rsocket*)arg; // We may be updating the TLS context (this is normally the new client's rsocket object)
        const unsigned char* out      = nullptr;
              size_t         out_size = 0;
 
        // --------------------------------------------------------------------------
        // Obtain a pointer to newly-allocated ClientHello fields data.  If *out is
        // nullptr, it means that no TLSEXT_TYPE_server_name was received from the
        // client, and so the default TLS context will suffice.  If out_size is less
        // than or equal to 2, then it also won't have what we need.
        // --------------------------------------------------------------------------
        if (!SSL_client_hello_get0_ext(tls_fd, TLSEXT_TYPE_server_name, &out, &out_size)
          || out == nullptr || out_size <= 2) return SSL_CLIENT_HELLO_SUCCESS; // 1
 
        // --------------------------------------------------------------------------
        // Scan for TLSEXT_NAMETYPE_host_name, but if we can't find it then we'll
        // just leave the default TLS context as is.
        // --------------------------------------------------------------------------
        unsigned char* p   = (unsigned char*)out;
                size_t len = (*(p++) << 8);
                       len += *(p++);
        if (len + 2 != out_size) goto finish;
 
        // --------------------------------------------------------------------------
        // We're taking a shortcut by examining only the first element in the list,
        // but in the future we need to make this more robust in case other types of
        // elements precede what we're looking for.
        //
        // Unfortunately, there's no documentation that properly-explains the format
        // of the list, so some deeper research into OpenSSL's source code will be
        // needed (a cursory look so far has not yielded the necessary insight).
        //
        // TODO:  Turn this into a loop that supports future clients that provide
        //        multiple SNI server names in their requests.  (Although this isn't
        //        occuring at present with common end-user tools such as web browsers
        //        and eMail software, it may happen in the future as client/server
        //        software becomes more savvy.)
        // --------------------------------------------------------------------------
        if (out_size == 0 || *p++ != TLSEXT_NAMETYPE_host_name) goto finish;
 
        // --------------------------------------------------------------------------
        // Avoid buffer overrun caused by corrupt or prematurely-truncated data.
        // --------------------------------------------------------------------------
        if (--out_size <= 2) goto finish;
 
        // --------------------------------------------------------------------------
        // Extract and use the hostname (SNI server name) that was supplied by the
        // endpoint so that the correct TLS certificate can be selected and assigned.
        // --------------------------------------------------------------------------
        len = (*(p++) << 8);
        len += *(p++);
        if (!(len + 2 > out_size)) { // Only process SNI server name string if it's at least 2 bytes long
          // Debug: std::cout << "Server name: " << (const char*)p << std::endl; // Debug
 
          // --------------------------------------------------------------------------
          // Obtain the correct TLS context (wildcards supported) that is associated
          // with the hostname (SNI server name) that was supplied by the endpoint.
          // --------------------------------------------------------------------------
          const char* sni_name = (const char*)p;
          SSL_CTX* new_ctx = r->__tls_sni->get_ctx(sni_name, true, r->tls_ctx());
 
          // --------------------------------------------------------------------------
          // Change TLS context so that encryption with the endpoint uses the correct
          // TLS certificate (otherwise the endpoint will indicate security risk errors
          // to end users, log files, etc., and may {should} reject the connection).
          // --------------------------------------------------------------------------
//std::cout << "SNI setup... " << sni_name << std::endl;
          SSL_set_SSL_CTX(tls_fd, new_ctx);
//std::cout << "---1--- " << r->__tls_new_endpoint << std::endl;
          r->__tls_new_endpoint->tls_ctx(new_ctx);
//std::cout << "---2---" << std::endl;
          r->__tls_new_endpoint->__name_sni.assign(sni_name);
//std::cout << "SNI name() = " << r->__tls_new_endpoint->name() << std::endl;
          r->__tls_new_endpoint->__tls_sni_match = true;
 
        } // -x- if len+2 -x-
 
      finish:
        // --------------------------------------------------------------------------
        // Free the ClientHello fields data, then return SSL_CLIENT_HELLO_SUCCESS.
        // Even if we encountered a problem with the ClientHello fields data, we
        // still return SSL_CLIENT_HELLO_SUCCESS so that the TLS context will be
        // accepted as valid.
        //
        // If we return SSL_CLIENT_HELLO_ERROR the connection will fail unnecessarily
        // for valid TLS certificates.  If the ClientHello fields data is malformed
        // to a degree that doesn't satisfy OpenSSL, then OpenSSL will reject it, so
        // there's really no point in duplicating what OpenSSL already does properly,
        // which OpenSSL will pass through the standard error channels with normal
        // error details-and-diagnostics anyway.
        // --------------------------------------------------------------------------
        //OPENSSL_free((char*)out); // OpenSSL documentation says to do this, but it fails and crashes the program
 
        return SSL_CLIENT_HELLO_SUCCESS; // 1
      }; // -x- int tls_sni_callback -x-
 
public:
      /*======================================================================*//**
      @brief
      Convert a 48-bit integer to a machine address in the form of @c
      xx:xx:xx:xx:xx:xx where every instance of @c xx is a hexadecimal
      representation of each respective 8-bit byte portion.
 
      This method is needed because we don't want to bring in the heavy fmt::format
      class as a dependency.
      @returns Mac address as 17-character in the typical format expected by system
               administrators
      @qualifier TLS
      *///=========================================================================
      static std::string to_mac(
      /// Pointer to 48-bit integer
      const void* addr) noexcept {
        std::string h;
        h.resize(18); // 48-bit mac address needs 6 hexadecimal pairs of nybbles delimited by colons plus a NULL terminator
        h.resize(snprintf(h.data(),
                          h.size(),
                          "%02x:%02x:%02x:%02x:%02x:%02x",
                          ((u_char*)addr)[0],
                          ((u_char*)addr)[1],
                          ((u_char*)addr)[2],
                          ((u_char*)addr)[3],
                          ((u_char*)addr)[4],
                          ((u_char*)addr)[5])); // Convert, and truncate NULL terminator
        return h;
      }; // -x- std::string to_mac -x-
 
      /*======================================================================*//**
      @brief
      Convert a 48-bit integer to a node address in the form of @c xxxx:xxxx:xxxx
      where every instance of @c xxxx is a hexadecimal representation of each
      respective 16-bit word portion.
 
      This method is needed because we don't want to bring in the heavy fmt::format
      class as a dependency.
      @returns Node address as 14-character in the typical format expected by
               network administrators
      @qualifier TLS
      *///=========================================================================
      static std::string to_node(
      /// Pointer to 48-bit integer
      const void* addr) noexcept {
        std::string h;
        h.resize(15); // 48-bit node address needs 3 hexadecimal sets of words delimited by colons plus a NULL terminator
        h.resize(snprintf(h.data(),
                          h.size(),
                          "%04x:%04x:%04x",
                          ((u_int16_t*)addr)[0],
                          ((u_int16_t*)addr)[1],
                          ((u_int16_t*)addr)[2])); // Convert, and truncate NULL terminator
        return h;
      }; // -x- std::string to_node -x-
 
      /*======================================================================*//**
      @brief
      Send a formatted string to the @ref rsocket endpoint.
 
      The @c format is described in the documentation for the POSIX or Standard C
      Library @c printf() function.
      @throws randolf::rex::xEBADF The underlying socket is not open
      @throws randolf::rex::xEILSEQ An invalid wide-character code was detected
      @throws randolf::rex::xEOVERFLOW The value returned is greater than {INT_MAX}
      @throws randolf::rex::xEMFILE Per-process maximum open files limit reached
      @throws randolf::rex::xENOMEM Insufficient memory
      @returns The same rsocket object so as to facilitate stacking
      @see eol_fix_printf
      @see is_eol_fix_printf
      @see net_io
      @see printf
      @see printfline
      @see vprintfline
      @qualifier POSIX
      @qualifier TLS
      *///=========================================================================
      rsocket* vprintf(
      /// Format string to use
      const char* format,
      /// Variadic arguments in @c va_list format
      va_list args) {
        char* buf;
        int rc = ::vasprintf(&buf, format, args);
        __rc_check(rc); // Check for error, and throw exception (buf was not allocated, so does not need to be freed)
        if (__eol_fix_printf && !__eol.empty()) {
          std::string str = std::regex_replace(buf, std::regex("\n"), __eol);
          ::free(buf);
          __send(str.c_str(), str.length());
        } else {
          try {
            __send(buf, rc);
          } catch (std::exception& e) { // Free buf then re-throw the exception
            ::free(buf); // Prevent memory leak when an exception is thrown
            throw;
          }
        } // -x- if __eol_fix_printf -x-
        return this;
      }; // -x- rsocket* vprintf -x-
 
      /*======================================================================*//**
      @brief
      Send a formatted string to the @ref rsocket endpoint, and append an EoL
      sequence.
 
      The @c format is described in the documentation for the POSIX or Standard C
      Library @c printf() function.
      @throws randolf::rex::xEBADF The underlying socket is not open
      @throws randolf::rex::xEILSEQ An invalid wide-character code was detected
      @throws randolf::rex::xEOVERFLOW The value returned is greater than {INT_MAX}
      @throws randolf::rex::xEMFILE Per-process maximum open files limit reached
      @throws randolf::rex::xENOMEM Insufficient memory
      @returns The same rsocket object so as to facilitate stacking
      @see eol
      @see eol_fix_printf
      @see is_eol_fix_printf
      @see net_io
      @see printf
      @see printfline
      @see sendline
      @see vprintf
      @qualifier TLS
      *///=========================================================================
      rsocket* vprintfline(
      /// Format string to use
      const char* format,
      /// Variadic arguments in @c va_list format
      va_list args) {
        char* buf;
        int rc = ::vasprintf(&buf, format, args);
        __rc_check(rc); // Check for error, and throw exception (buf was not allocated, so does not need to be freed)
        if (__eol_fix_printf && !__eol.empty()) {
          std::string str = std::regex_replace(buf, std::regex("\n"), __eol)
                           .append(__eol);
          ::free(buf);
          __send(str.c_str(), str.length());
        } else {
          try {
            __sendline(buf, rc);
          } catch (std::exception& e) { // Free buf then re-throw the exception
            ::free(buf); // Prevent memory leak when an exception is thrown
            throw;
          }
        } // -x- if __eol_fix_printf -x-
        return this;
      }; // -x- rsocket* vprintfline -x-
 
    private:
      /*======================================================================*//**
      Track unencrypted bytes received.  When the number of bytes is negative or
      zero, it isn't recorded.
      This is an internal function.
      @returns same value provided in @ref n
      @qualifier TLS
      *///=========================================================================
      int __track_bytes_rx(
      /// Number of bytes transferred
      const int n) {
        if (n > 0) __bytes_rx.fetch_add(n, std::memory_order_relaxed);
        return n;
      }; // -x- __track_bytes_rx -x-
 
      /*======================================================================*//**
      Track unencrypted bytes transmitted.  When the number of bytes is negative or
      zero, it isn't recorded.
      This is an internal function.
      @returns same value provided in @ref n
      @qualifier TLS
      *///=========================================================================
      int __track_bytes_tx(
      /// Number of bytes transferred
      const int n) {
        if (n > 0) __bytes_tx.fetch_add(n, std::memory_order_relaxed);
        return n;
      }; // -x- __track_bytes_tx -x-
 
      /*======================================================================*//**
      Track encrypted bytes received.  When the number of bytes is negative or
      zero, it isn't recorded.
      This is an internal function.
      @returns same value provided in @ref n
      @qualifier TLS
      *///=========================================================================
      int __track_crypt_rx(
      /// Number of bytes transferred
      const int n) {
        if (n > 0) __crypt_rx.fetch_add(n, std::memory_order_relaxed);
        return n;
      }; // -x- __track_crypt_rx -x-
 
      /*======================================================================*//**
      Track encrypted bytes transmitted.  When the number of bytes is negative or
      zero, it isn't recorded.
      This is an internal function.
      @returns same value provided in @ref n
      @qualifier TLS
      *///=========================================================================
      int __track_crypt_tx(
      /// Number of bytes transferred
      const int n) {
        if (n > 0) __crypt_tx.fetch_add(n, std::memory_order_relaxed);
        return n;
      }; // -x- __track_crypt_tx -x-
 
  }; // -x- class rsocket -x-
 
}; // -x- namespace randolf -x-
 
// Save this for a future sendlines() methods.
//      const void*                   msg_ptr = msg.c_str();  // Prevent repeated calls to c_str() method
//      const int                     len     = msg.length(); // Prevent repeated calls to length() method