randolf.ca
1.00
Randolf Richardson's C++ classes
|
This 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. More...
#include <rsocket>
Public Types | |
enum | RECVLINE_FLAGS : int { RECVLINE_DEFAULT = 0 , RECVLINE_KEEP_ON_OVERFLOW = 1 , RECVLINE_PARTIAL = 2 } |
Optional flags used with rsocket's recvline() and recv_rline() methods to specify relevant text-line reading policies/semantics. More... | |
enum | TIMEOUT_BEHAVIOUR : bool { TIMEOUT_EXCEPTION = true , TIMEOUT_EMPTY = false , TIMEOUT_NULL = false , TIMEOUT_ZERO = false } |
Optional flags used with various methods to determine whether they will throw an randolf::rex::xETIMEDOUT exception or merely return a nullptr , an empty set, or a 0 (zero) when a timeout duration elapses. More... | |
enum | TLS_FLAGS : int { TLS_DEFAULT = 0 , TLS_EXCLUSIVE = 1 , TLS_NO_INGRESS = 2 , TLS_NO_EGRESS = 4 , TLS_CLIENT = 0 , TLS_SERVER = 8 } |
Optional flags used with rsocket's tls() and tls_ctx() methods to specify relevant policies/semantics. More... | |
Public Member Functions | |
rsocket () noexcept | |
Instantiate an empty rsocket without actually opening a socket, and therefore also without throwing any exceptions (useful in header-file definitions). | |
rsocket (const int family, const int type=SOCK_STREAM, const int protocol=PF_UNSPEC) | |
Instantiate an rsocket with IP/host address and [optional] port number. | |
rsocket (const rsocket *rtemplate, const bool flag_create_socket=true) | |
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. | |
~rsocket () noexcept | |
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 net_io_final() method). | |
rsocket * | accept () |
Accept new [inbound] socket connetions. (This is typically used in a loop.) | |
rsocket * | accept4 (const int posix_flags=0) |
Accept new [inbound] socket connetions, with socket flags specified. (This is typically used in a loop.) | |
std::shared_ptr< rsocket > | accept4_sp (const int posix_flags=0) |
Accept new [inbound] socket connetions, with socket flags specified. (This is typically used in a loop.) | |
std::shared_ptr< rsocket > | accept_sp () |
Accept new [inbound] socket connetions. (This is typically used in a loop.) | |
int | backlog () noexcept |
Find out what this rsocket's default listen backlog is. | |
rsocket * | backlog (int backlog=0) noexcept |
Override the default listen backlog for this rsocket. | |
rsocket * | bind (const std::string address, const int port=0) |
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 connect() method (this bound address is address from which the endpoint will recieve your connection). | |
rsocket * | bind (const struct sockaddr *addr, const socklen_t addrlen=sizeof(sockaddr)) |
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 connect() method (this bound address is the address from which the endpoint will recieve your connection). | |
const size_t | buffer_size () noexcept |
Find out what buffer size is used by the various recv() methods. | |
rsocket * | buffer_size (const size_t nbytes) |
Override the default buffer size (typically 1024) used by the various recv() methods. | |
rsocket * | buffer_size_reset () |
Reset the default buffer size (typically 1024) used by the various recv() methods. | |
rsocket * | close () |
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.) | |
int | close_passive () noexcept |
Close this rsocket without throwing any exceptions (an error code is returned instead, which is useful while calling close_passive() from within a destructor). | |
rsocket * | connect (const std::string address, const int port=0) |
Connect this socket to a specific endpoint (which may differ from this rsocket's address that was previously configured by the bind() method). | |
const bool | debug () noexcept |
Find out whether debug mode is enabled. | |
const int | debug (const bool debug_flag, std::FILE *fd=stderr) noexcept |
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). | |
const int | debug (const char *msg) noexcept |
Send the specified message as debug output (as long as debug mode is enabled; if disabled, no debug output will be sent). | |
const int | debug (const std::string msg) noexcept |
Send the specified message as debug output (as long as debug mode is enabled; if disabled, no debug output will be sent). | |
const std::FILE * | debug_fd () noexcept |
Find out which file descriptor/handle is used for debug output. | |
const int | debug_fd (std::FILE *fd) noexcept |
Specify a different file descriptor/handle to use for debug output. | |
const std::string | debug_prefix () noexcept |
Find out what the current prefix is set to that's used in debug output. | |
rsocket * | debug_prefix (const std::string prefix) noexcept |
Change the prefix used in debug output. | |
int | discard (int nbytes, int posix_flags=0, const size_t memory_size=0) |
Discards the specified number of 8-bit bytes efficiently, and without closing the stream, and without consuming excessive quantities of memory. | |
int | discard_line (int nbytes=-1, int posix_flags=0, long timeout=0, const size_t memory_size=0) |
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 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. | |
const std::string | eol () noexcept |
Find out what the current EoL (End of Line) sequence is set to. | |
rsocket * | eol (const char *eol) noexcept |
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. | |
rsocket * | eol (const std::string eol) noexcept |
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. | |
rsocket * | eol_adoption (const bool flag) noexcept |
Configure EoL adoption policy for the recvline() and recv_rline() methods. By default, rsocket is configured with the EoL adoption policy enabled alongside an empty 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 recvline() or recv_rline method. | |
const std::string | eol_consumed_seq () noexcept |
Returns a String containing the EoL character sequence that was consumed by the most recent successful call to the recvline() or 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). | |
rsocket * | eol_fix_printf (const bool flag) noexcept |
Configure EoL substitution policy for the printf(), printfline(), vprintf(), and vprintfline() methods. By default, rsocket substitutes printf's \n sequence with the EoL sequence (if defined), but this method can be used to disable this behaviour. | |
const int | eol_index (const std::string buffer, int *with_eol_size) noexcept |
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). | |
const bool | eos (const int timeout=0) |
Find out if the stream is at its end and that this rsocket's internal buffer (if one had been set up by the 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). | |
const std::shared_ptr< sockaddr_storage > | getpeername () |
Get peer name returns the address of the socket as a sockaddr_storage structure. | |
const std::string | getpeername_ntop () |
Get peer name returns the address of the socket as a std::string object. | |
const std::shared_ptr< sockaddr_storage > | getsockname () |
Get socket name returns the address of the socket as a "sockaddr_storage" structure. | |
const std::string | getsockname_ntop () |
Get socket name returns the name of the socket as a std::string object. | |
std::shared_ptr< group_req > | getsockopt_group_req (const int level, const int option) |
Get socket option details in the form of a structure. | |
std::shared_ptr< group_source_req > | getsockopt_group_source_req (const int level, const int option) |
Get socket option details in the form of a structure. | |
std::shared_ptr< icmp6_filter > | getsockopt_icmp6_filter (const int level, const int option) |
Get socket option details in the form of a structure. | |
std::shared_ptr< in_addr > | getsockopt_in_addr (const int level, const int option) |
Get socket option details in the form of a structure. | |
int | getsockopt_int (const int level, const int option) |
Get socket option details in the form of an integer. | |
std::shared_ptr< ip6_mtuinfo > | getsockopt_ip6_mtuinfo (const int level, const int option) |
Get socket option details in the form of a structure. | |
std::shared_ptr< ip_mreq > | getsockopt_ip_mreq (const int level, const int option) |
Get socket option details in the form of a structure. | |
std::shared_ptr< ip_mreq_source > | getsockopt_ip_mreq_source (const int level, const int option) |
Get socket option details in the form of a structure. | |
std::shared_ptr< ipv6_mreq > | getsockopt_ipv6_mreq (const int level, const int option) |
Get socket option details in the form of a structure. | |
std::shared_ptr< linger > | getsockopt_linger (const int level, const int option) |
Get socket option details in the form of a structure. | |
template<class T > | |
std::shared_ptr< T > | getsockopt_other (const int level, const int option) |
Get socket option details in the form of a structure. | |
std::shared_ptr< sockaddr_in6 > | getsockopt_sockaddr_in6 (const int level, const int option) |
Get socket option details in the form of a structure. | |
std::shared_ptr< timeval > | getsockopt_timeval (const int level, const int option) |
Get socket option details in the form of a structure. | |
u_char | getsockopt_u_char (const int level, const int option) |
Get socket option details in the form of an unsigned character. | |
u_int | getsockopt_u_int (const int level, const int option) |
Get socket option details in the form of an unsigned integer. | |
const std::string | inet_ntop () |
Get underlying socket's address as a std::string, for sockets in one of the supported families: | |
const bool | is_buffered () noexcept |
Find out whether an internal read buffer was allocated (this is most likely triggered by an attempt to read a line of text). | |
const bool | is_closed () noexcept |
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). | |
const bool | is_connected () noexcept |
Find out whether the underlying socket is connected with/to an endpoint. | |
const bool | is_endian_lsb () noexcept |
Find out whether the default byte order for this host is LSB (small endian). | |
const bool | is_endian_msb () noexcept |
Find out whether the default byte order for this host is MSB (big endian). | |
const bool | is_eol_adoption () noexcept |
Find out if the EoL adoption policy is enabled for the recvline() method (see the eol_adoption method to find out how the dynamically-detected EoL sequence gets adopted, and under what conditions). | |
const bool | is_eol_fix_printf () noexcept |
Find out if the EoL substitution policy is enabled for the printf(), printfline(), vprintf(), and vprintfline() methods. | |
const bool | is_open () noexcept |
Find out whether the underlying socket is open. | |
const bool | is_tls () noexcept |
Find out whether encrypted communications is enabled or disabled. | |
const bool | is_tls_client_mode () noexcept |
Find out whether TLS context is in TLS_CLIENT mode. | |
const bool | is_tls_egress_okay () noexcept |
Find out whether egress from encryption (to unencrypted mode) is allowed. | |
const bool | is_tls_exclusive () noexcept |
Find out whether encrypted communications is exclusive. | |
const bool | is_tls_ingress_okay () noexcept |
Find out whether ingress to encryption (from unencrypted mode) is allowed. | |
const bool | is_tls_server_mode () noexcept |
Find out whether TLS context is in TLS_SERVER mode. | |
const bool | is_tls_sni () noexcept |
Find out whether SNI (Server Name Identifier) is enabled (configured, which implies that an internal callback function was also set up). | |
const bool | is_tls_sni_match () noexcept |
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 rsocket_sni object as separate TLS contexts. | |
rsocket * | listen (int backlog=0) |
Enable listening mode for this rsocket to prepare it to accept() new inbound connections. | |
std::string | name () noexcept |
Find out what this rsocket's name is. | |
rsocket * | name (const std::string name) noexcept |
Specify a name for this rsocket. | |
std::string | name_sni () noexcept |
Find out what this rsocket's actual TLS SNI hostname is. | |
std::shared_ptr< rsocket_io > | net_io () noexcept |
Get socket I/O statistics from internally-tracked socket I/O counters. | |
std::string | net_io (const char *format, size_t len=0, rsocket_io *addr=nullptr) noexcept |
Get socket I/O statistics from internally-tracked socket I/O counters as a pre-formatted std::string object. | |
rsocket * | net_io_final (rsocket_io *addr) noexcept |
Where the destructor should save final I/O statistics before this rsocket's resources are completely freed/deallocated. | |
rsocket * | net_io_update (rsocket_io *addr) noexcept |
Where the destructor should save current I/O statistics. | |
short | poll (const short events=POLLIN, const int timeout=0, const bool timeout_behaviour=TIMEOUT_EXCEPTION) |
Poll the underlying socket using the poll() method for data that's ready for receiving (default), etc. | |
const uint16_t | port () noexcept |
Get port number associated with underlying socket descriptor/handle. | |
short | ppoll (const short events=POLLIN, const int tv_sec=0, const long tv_nsec=0, const sigset_t *sigmask=nullptr, const bool timeout_behaviour=TIMEOUT_EXCEPTION) |
Poll the underlying socket using the ppoll() method for data that's ready for receiving (default), etc. | |
short | ppoll (const short events=POLLIN, const struct timespec *tmo_p=nullptr, const sigset_t *sigmask=nullptr, const bool timeout_behaviour=TIMEOUT_EXCEPTION) |
Poll the underlying socket using the ppoll() method for data that's ready for receiving (default), etc. | |
rsocket * | printf (const char *format,...) |
Send a formatted string to the rsocket endpoint. | |
rsocket * | printfline (const char *format,...) |
Send a formatted string to the rsocket endpoint, and append an EoL sequence. | |
std::vector< char > | recv (const size_t nbytes=0, const int posix_flags=0) |
Receive data from the endpoint into a std::vector<char> that is allocated on-the-fly. | |
std::vector< char > | recv (std::vector< char > buf, const int posix_flags=0) |
Receive data from the endpoint into the std::vector object supplied in the buf parameter. | |
std::string | recv_as_string (const size_t nbytes=0, const int posix_flags=0) |
Receive data from the endpoint into a std::string object that is allocated on-the-fly. | |
char * | recv_asciiz (const size_t nbytes=0, const int posix_flags=0) |
Receive an ASCIIZ string from the endpoint, including the NULL terminator. | |
u_char | recv_byte (const int posix_flags=0) |
Receive one byte (unsigned 8-bit byte) of data from the endpoint. | |
char | recv_char (const int posix_flags=0) |
Receive one character (signed 8-bit byte) of data from the endpoint. | |
randolf::rline | recv_rline (const size_t nbytes=0, const int posix_flags=0, long timeout=0, const int recvline_flags=RECVLINE_FLAGS::RECVLINE_DEFAULT) |
Receive a line of data from the endpoint, into an 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 recv() and recvz() methods tend to be better-suited). | |
template<typename T > | |
T | recv_struct (const int posix_flags=0) |
Receive a data structure from the endpoint. | |
uint16_t | recv_uint16_lsb (const int posix_flags=0) |
Receive one 16-bit unsigned integer of data in LSB (little endian) order from the endpoint. | |
uint16_t | recv_uint16_msb (const int posix_flags=0) |
Receive one 16-bit unsigned integer of data in MSB (big endian) order from the endpoint. | |
uint32_t | recv_uint32_lsb (const int posix_flags=0) |
Receive one 32-bit unsigned integer of data in LSB (little endian) order from the endpoint. | |
uint32_t | recv_uint32_msb (const int posix_flags=0) |
Receive one 32-bit unsigned integer of data in MSB (big endian) order from the endpoint. | |
uint64_t | recv_uint64_lsb (const int posix_flags=0) |
Receive one 64-bit unsigned integer of data in LSB (little endian) order from the endpoint. | |
uint64_t | recv_uint64_msb (const int posix_flags=0) |
Receive one 64-bit unsigned integer of data in MSB (big endian) order from the endpoint. | |
std::vector< char > | recvfrom (const size_t nbytes, const int posix_flags, struct sockaddr *from, socklen_t fromlen=sizeof(sockaddr)) |
Receive data from a specific endpoint. | |
std::string | recvline (const size_t nbytes=0, const int posix_flags=0, long timeout=0, const int recvline_flags=RECVLINE_FLAGS::RECVLINE_DEFAULT) |
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 recv() and recvz() methods tend to be better-suited). | |
mmsghdr * | recvmmsg (struct mmsghdr *mmsg, const unsigned int vlen=sizeof(mmsghdr), const int posix_flags=0, struct timespec *timeout={0}) |
Receive data in the form of an "mmsghdr" structure. | |
msghdr * | recvmsg (msghdr *msg, const int posix_flags=0) |
Receive data in the form of a "msghdr" structure. | |
std::vector< char > | recvz (const size_t nbytes=0, const int posix_flags=0) |
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. | |
rsocket * | send (const char *msg, size_t len=0, const int posix_flags=0) |
Send data in the form of a C-string to the endpoint. | |
rsocket * | send (const std::string msg, const int posix_flags=0) |
Send data in the form of a std::string to the endpoint. | |
rsocket * | send (const std::vector< char > msg, const int posix_flags=0) |
Send data in the form of a std::vector<char> to the endpoint. | |
rsocket * | send_asciiz (const char *msg, const int posix_flags=0) |
Send data in the form of an ASCIIZ string to the endpoint, including the terminating NULL character. | |
rsocket * | send_byte (const u_char value, const int posix_flags=0) |
Send one 8-bit byte (one unsigned character) of data to the endpoint. | |
rsocket * | send_char (const char value, const int posix_flags=0) |
Send one signed character (one 8-bit byte) of data to the endpoint. | |
rsocket * | send_eol (const int posix_flags=0) |
Send the EoL sequence to the endpoint. | |
template<typename T > | |
rsocket * | send_struct (const T value, const int posix_flags=0) |
Send a data structure to the endpoint. | |
rsocket * | send_uint16_lsb (const uint16_t value, const int posix_flags=0) |
Send one 16-bit unsigned integer of data in LSB (little endian) order to the endpoint. | |
rsocket * | send_uint16_msb (const uint16_t value, const int posix_flags=0) |
Send one 16-bit integer of data in MSB (big endian) order to the endpoint. | |
rsocket * | send_uint32_lsb (const uint32_t value, const int posix_flags=0) |
Send one 32-bit unsigned integer of data in LSB (little endian) order to the endpoint. | |
rsocket * | send_uint32_msb (const uint32_t value, const int posix_flags=0) |
Send one 32-bit unsigned integer of data in MSB (big endian) order to the endpoint. | |
rsocket * | send_uint64_lsb (const uint64_t value, const int posix_flags=0) |
Send one 64-bit unsigned integer of data in LSB (little endian) order to the endpoint. | |
rsocket * | send_uint64_msb (const uint64_t value, const int posix_flags=0) |
Send one 64-bit unsigned integer of data in MSB (big endian) order to the endpoint. | |
rsocket * | sendline (const std::string msg=std::string(), const int posix_flags=0) |
Send data in the form of a std::string to the endpoint, with an EoL sequence appended. | |
rsocket * | sendmmsg (struct mmsghdr *mmsg, const unsigned int vlen=sizeof(mmsghdr), const int posix_flags=0) |
Send data in the form of a "mmsghdr" structure to a specific endpoint. | |
rsocket * | sendmsg (const struct msghdr *msg, const int posix_flags=0) |
Send data in the form of a "msghdr" structure to a specific endpoint. | |
rsocket * | sendto (const char *msg, const size_t len, const int posix_flags, const struct sockaddr *to, socklen_t tolen=sizeof(sockaddr)) |
Send data in the form of a C-string to a specific endpoint. | |
rsocket * | sendto (const std::string msg, const int posix_flags, const struct sockaddr *to, socklen_t tolen=sizeof(sockaddr)) |
Send data in the form of a std::string to a specific endpoint. | |
rsocket * | sendz (const char *msg, const int posix_flags=0) |
Send data in the form of an ASCIIZ string to the endpoint. The terminating NULL character won't be transmitted. | |
rsocket * | sendzto (const char *msg, const int posix_flags, const struct sockaddr *to, socklen_t tolen=sizeof(sockaddr)) |
Send data in the form of an ASCIIZ string to a specific endpoint. The terminating NULL character won't be transmitted. | |
rsocket * | setsockopt (const int level, const int option, const group_req &value) |
Set socket option to the specific structure. | |
rsocket * | setsockopt (const int level, const int option, const group_source_req &value) |
Set socket option to the specific structure. | |
rsocket * | setsockopt (const int level, const int option, const icmp6_filter &value) |
Set socket option to the specific structure. | |
rsocket * | setsockopt (const int level, const int option, const in_addr &value) |
Set socket option to the specific structure. | |
rsocket * | setsockopt (const int level, const int option, const int value) |
Set socket option to the specific integer. | |
rsocket * | setsockopt (const int level, const int option, const ip6_mtuinfo &value) |
Set socket option to the specific structure. | |
rsocket * | setsockopt (const int level, const int option, const ip_mreq &value) |
Set socket option to the specific structure. | |
rsocket * | setsockopt (const int level, const int option, const ip_mreq_source &value) |
Set socket option to the specific structure. | |
rsocket * | setsockopt (const int level, const int option, const ipv6_mreq &value) |
Set socket option to the specific structure. | |
rsocket * | setsockopt (const int level, const int option, const linger &value) |
Set socket option to the specific structure. | |
rsocket * | setsockopt (const int level, const int option, const sockaddr_in6 &value) |
Set socket option to the specific structure. | |
rsocket * | setsockopt (const int level, const int option, const timeval &value) |
Set socket option to the specific structure. | |
rsocket * | setsockopt (const int level, const int option, const u_char value) |
Set socket option to the specific unsigned character. | |
rsocket * | setsockopt (const int level, const int option, const u_int value) |
Set socket option to the specific unsigned integer. | |
rsocket * | shutdown (const int how=SHUT_RDWR, const bool tls_shutdown=true) |
Shut down the underlying socket, partially or fully. | |
const bool | sockatmark () |
Find out whether the underlying socket is at the out-of-band (OOB) mark. | |
rsocket * | socket (const int family, const int type=SOCK_STREAM, const int protocol=PF_UNSPEC) |
Complete the configuration of an rsocket that was previously initialized without any parameters (a.k.a., an "empty rsocket"). | |
const int | socket_family () noexcept |
Get underlying socket family/domain constant (SO_DOMAIN). | |
const int | socket_fd () noexcept |
Get underlying socket descriptor/handle. | |
rsocket * | socket_fd (const int new_socket_fd) |
Set underlying socket descriptor/handle (to one that is presumed to be open). | |
const int | socket_protocol () noexcept |
Get underlying socket protocol constant (SO_PROTOCOL). | |
const int | socket_type () noexcept |
Get underlying socket type constant (SO_TYPE). | |
std::shared_ptr< timeval > | timeout () |
Find out what the read timeout is set to on the current socket. | |
rsocket * | timeout (const int tv_sec=0, const long tv_usec=0) |
Set the recv timeout on the current socket. | |
rsocket * | timeout (const struct timeval tv) |
Set the recv timeout on the current socket. | |
long | timeout_recvline () |
Find out what the read timeout is set to when using the recvline() method. | |
rsocket * | timeout_recvline (const long timeout) |
Set the read timeout for the recvline() method (the recvline() method's timeout parameter can override this setting). | |
rsocket * | tls (const bool status=true, const int flags=TLS_FLAGS::TLS_DEFAULT) |
Enable or disable encrypted communications (from the OpenSSL library). | |
SSL_CTX * | tls_ctx () noexcept |
Return the current TLS context (multiple TLS contexts are supported, although typically needed to support SNI with inbound connections). | |
rsocket * | tls_ctx (rsocket *rtemplate, const int flags=TLS_FLAGS::TLS_DEFAULT) |
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(). | |
rsocket * | tls_ctx (SSL_CTX *ctx, const int flags=TLS_FLAGS::TLS_DEFAULT) |
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). | |
rsocket * | tls_ctx_check_privatekey () |
Check the private key it to ensure it's consistent with the corresponding TLS certificate chain. | |
rsocket * | tls_ctx_use_certificate_chain_and_privatekey_files (const char *chain_file, const char *key_file) |
Load a TLS certificate chain and private key in PEM format from text files and use them in the TLS context. | |
rsocket * | tls_ctx_use_certificate_chain_and_privatekey_files (const std::string chain_file, const std::string key_file) |
Load a TLS certificate chain and private key in PEM format from text files and use them in the TLS context. | |
rsocket * | tls_ctx_use_certificate_chain_and_privatekey_pems (const char *cert_pem_data, const char *key_pem_data, size_t cert_len=0, size_t key_len=0, const bool random_fill=true) |
Load a TLS certificate chain and a TLS private key in PEM format from memory and use them in the TLS context. | |
rsocket * | tls_ctx_use_certificate_chain_file (const char *file) |
Load a TLS certificate chain in PEM format from a text file and use it in the TLS context. | |
rsocket * | tls_ctx_use_certificate_chain_file (const std::string file) |
Load a TLS certificate chain in PEM format from a text file and use it in the TLS context. | |
rsocket * | tls_ctx_use_certificate_chain_pem (const char *pem_data, size_t len=0, const bool random_fill=true) |
Load a TLS certificate chain in PEM format from memory and use it in the TLS context. | |
rsocket * | tls_ctx_use_privatekey_file (const char *file) |
Load a TLS private key in PEM format from a text file and use it in the TLS context. | |
rsocket * | tls_ctx_use_privatekey_file (const std::string file) |
Load a TLS private key in PEM format from a text file and use it in the TLS context. | |
rsocket * | tls_ctx_use_privatekey_pem (const char *pem_data, size_t len=0, const bool random_fill=true) |
Load a TLS private key in PEM format from memory and use it in the TLS context. | |
rsocket * | tls_do_handshake () |
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 STARTTLS (which are implemented in protocols like SMTP, POP3, IMAP4, MEOW, FTP, NNTP, LDAP, XMPP, etc.). | |
const SSL * | tls_fd () noexcept |
Get OpenSSL's TLS structure. | |
rsocket_sni * | tls_sni () noexcept |
Return the current rsocket_sni object that this rsocket will use when accepting incoming encrypted connections. | |
rsocket * | tls_sni (rsocket_sni *sni) noexcept |
Set the current rsocket_sni object that this rsocket will use when accepting incoming encrypted connections. | |
rsocket * | vprintf (const char *format, va_list args) |
Send a formatted string to the rsocket endpoint. | |
rsocket * | vprintfline (const char *format, va_list args) |
Send a formatted string to the rsocket endpoint, and append an EoL sequence. | |
Static Public Member Functions | |
static int | family (const std::string address, const int preferred_family=AF_UNSPEC) |
Find out what the specified IP address string's family (SO_DOMAIN ) is. | |
static sockaddr * | getsockaddr (const sockaddr_storage *sa) |
Get specified "sockaddr_storage" structure's address as a "sockaddr" structure, for sockets in one of the supported families: | |
static const std::string | inet_ntop (sockaddr_storage *sa) |
Get specified "sockaddr_storage" structure's address as a std::string, for sockets in one of the supported families: | |
static std::shared_ptr< sockaddr_storage > | mk_sockaddr_storage (const char *node_name, const char *service_name=nullptr, const addrinfo *hints=nullptr) |
Convert an IPv4 address, IPv6 address, ethernet packet, or UNIX domain socket to a sockaddr_storage structure. | |
static std::shared_ptr< sockaddr_storage > | mk_sockaddr_storage (const char *node_name, const u_int16_t service_name, const addrinfo *hints=nullptr) |
Convert an IPv4 address, IPv6 address, ethernet packet, or UNIX domain socket to a sockaddr_storage structure. | |
static std::shared_ptr< sockaddr_storage > | mk_sockaddr_storage (const std::string node_name, const std::string service_name, const addrinfo *hints=nullptr) |
Convert an IPv4 address, IPv6 address, ethernet packet, or UNIX domain socket to a sockaddr_storage structure. | |
static std::shared_ptr< sockaddr_storage > | mk_sockaddr_storage (const std::string node_name, const u_int16_t service_name, const addrinfo *hints=nullptr) |
Convert an IPv4 address, IPv6 address, ethernet packet, or UNIX domain socket to a sockaddr_storage structure. | |
static std::string | to_mac (const void *addr) noexcept |
Convert a 48-bit integer to a machine address in the form of xx:xx:xx:xx:xx:xx where every instance of xx is a hexadecimal representation of each respective 8-bit byte portion. | |
static std::string | to_node (const void *addr) noexcept |
Convert a 48-bit integer to a node address in the form of xxxx:xxxx:xxxx where every instance of xxxx is a hexadecimal representation of each respective 16-bit word portion. | |
Friends | |
class | rsocket_group |
This 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:
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.
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<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 size_t
separately.
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:
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 rsocket and POSIX functions)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)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.
Parameter stacking is supported (with methods that return rsocket*
); in this example, notice that semicolons (";") and "r." references are omittted (when compared with the above):
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:
#include
lines as needed)std::string
(which tracks its own string length)Additional features that are not part of the typical POSIX standard, but deserve special mention because they are needed so often:
net_io_final()
method for details)Some advanced features are planned that exceed what the basic socket I/O functions provide, but are also needed:
Other features that are not a high priority:
__time_t
structure must be 64-bit (or larger). This becomes espcially important for the recvline method, in addition to Year 2038 compliance.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 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:
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.
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 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.
clang++
compilerPOSIX
and TLS
qualifiers to all applicable methods (Doxygen incorporates into the documentation)enum randolf::rsocket::RECVLINE_FLAGS : int |
Optional flags used with rsocket's recvline() and recv_rline() methods to specify relevant text-line reading policies/semantics.
Enumerator | |
---|---|
RECVLINE_DEFAULT | 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_KEEP_ON_OVERFLOW | The RECVLINE_NO_DISCARD_ON_OVERFLOW flag prevents data from being discarded when an randolf::rex::xEOVERFLOW exception is thrown (which is caused when a line of text exceeds the specified maximum line length).
By default, when the 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.
|
RECVLINE_PARTIAL | The RECVLINE_PARTIAL flag receives an incomplete line of text and returns it instead of throwing the randolf::rex::xEOVERFLOW exception, and causes the eol_consumed_seq() method to return an empty string (which indicates that no EoL sequence was consumed).
|
enum randolf::rsocket::TIMEOUT_BEHAVIOUR : bool |
Optional flags used with various methods to determine whether they will throw an randolf::rex::xETIMEDOUT exception or merely return a nullptr
, an empty set, or a 0 (zero) when a timeout duration elapses.
If you're not sure of whether to use TIMEOUT_EMPTY, TIMEOUT_NULL, or TIMEOUT_ZERO in your code, then I suggest using TIMEOUT_NULL since NULL
will likely be the most recognizable in most code reviews.
Enumerator | |
---|---|
TIMEOUT_EXCEPTION | Indicate that an randolf::rex::xETIMEDOUT exception should be thrown when the timeout duration elapses. |
TIMEOUT_EMPTY | Indicate that a |
TIMEOUT_NULL | Indicate that a |
TIMEOUT_ZERO | Indicate that a |
enum randolf::rsocket::TLS_FLAGS : int |
Optional flags used with rsocket's tls() and tls_ctx() methods to specify relevant policies/semantics.
Enumerator | |
---|---|
TLS_DEFAULT | 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_EXCLUSIVE | 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."
|
TLS_NO_INGRESS | Mid-stream upgrades to encrypted connections are not permitted (e.g., via application-level initiations like the
|
TLS_NO_EGRESS | Mid-stream downgrades to unencrypted connections are not permitted (e.g., via application-level initiations like a hypothetical
|
TLS_CLIENT | This is a convenience flag that provides an option for developers to be more clear in their use of the tls() and tls_ctx() methods to indicate intent to rely on what is already the default.
|
TLS_SERVER | 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
The absence of this flag has the same effect as specifying the TLS_CLIENT flag.
|
|
inlinenoexceptTLS |
Instantiate an empty rsocket without actually opening a socket, and therefore also without throwing any exceptions (useful in header-file definitions).
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 before setting the socket's configuration with one of the socket() methods; for example:
The built-in defaults, when not provided, are as follows ("family" is also known as the "communication domain"):
family
= AF_INETtype
= SOCK_STREAMprotocol
= PF_UNSPECYou 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.)
|
inlineTLS |
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.
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):
tls_ctx(r->tls_ctx())
)tls_sni(r->tls_sni())
)When flag_create_socket
is set to FALSE, no exceptions will be thrown.
rtemplate | Source rsocket object to use as a template to absorb settings from |
flag_create_socket | TRUE = create a new socket handle (default) FALSE = don't create a new socket because a new one will be assigned or created later (all variants of the accept() methods do this) |
|
inlineTLS |
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.
The built-in defaults, when not provided, are as follows ("family" is also known as the "communication domain"):
family
= AF_INETtype
= SOCK_STREAMprotocol
= PF_UNSPECThe 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.
randolf::rex::xEACCES | Elevated access is needed to open this socket |
randolf::rex::xEAFNOSUPPORT | Address family not implemented/supported |
randolf::rex::xEINVAL | Protocal family invalid or not available |
randolf::rex::xEINVAL | Invalid flags in type |
randolf::rex::xEMFILE | Per-process maximum open files limit reached |
randolf::rex::xENFILE | System-wide maximum open files limit reached |
randolf::rex::xENOBUFS | Insufficient memory |
randolf::rex::xENOMEM | Insufficient memory |
randolf::rex::xEPROTONOSUPPORT | Specified type or protocol is not supported within the specified family (a.k.a., communication domain) |
family | Communication domain; usually one of: AF_INET (IPv4) AF_INET6 (IPv6) AF_UNIX (UNIX domain sockets) |
type | Communication semantics; usually one of: SOCK_STREAM (common for TCP) SOCK_DGRAM (common for UDP) |
protocol | Network protocol; usually one of: IPPROTO_TCP IPPROTO_UDP IPPROTO_IP PF_UNSPEC (auto-detect) |
|
inlinenoexceptTLS |
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 net_io_final() method).
TRUE
prior to relying on the results of the 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).
|
inlinePOSIXTLS |
Accept new [inbound] socket connetions. (This is typically used in a loop.)
accept()
function.randolf::rex::xEBADF | The underlying socket is not open |
randolf::rex::xECONNABORTED | The connection was aborted |
randolf::rex::xEFAULT | Address structure/memory is not in a writable part of the user address space |
randolf::rex::xEHOSTDOWN | Host is down or its network is disconnected |
randolf::rex::xEHOSTUNREACH | No route to host |
randolf::rex::xEINTR | Interrupted by a signal |
randolf::rex::xEINVAL | Socket is not in listen() mode or the length of the address is invalid |
randolf::rex::xEMFILE | Per-process maximum open files limit reached |
randolf::rex::xENETDOWN | Network is disconnected or router is down |
randolf::rex::xENETUNREACH | No route to network |
randolf::rex::xENFILE | System-wide maximum open files limit reached |
randolf::rex::xENOBUFS | Insufficient memory |
randolf::rex::xENOMEM | Insufficient memory |
randolf::rex::xENONET | Requested host is not reachable on the network |
randolf::rex::xENOPROTOOPT | Either the level or the specified optname is not supported |
randolf::rex::xENOSR | System ran out of stream resources |
randolf::rex::xENOTSOCK | Underlying socket file descriptor (handle) doesn't refer to a socket |
randolf::rex::xEOPNOTSUPP | Underlying socket is no of type SOCK_STREAM |
randolf::rex::xEPERM | Connection forbidden/denied by firewall rules |
randolf::rex::xEPROTO | Protocol error |
randolf::rex::xEPROTONOSUPPORT | Specified type or protocol is not supported within the specified family (a.k.a., communication domain) |
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) |
randolf::rex::xESOCKTNOSUPPORT | Specified socket type is not supported within the specified family (a.k.a., communication domain) |
randolf::rex::xETIMEDOUT | Timeout period elapsed |
randolf::rex::xEWOULDBLOCK | The underlying socket is non-blocking and no inbound connections are waiting |
|
inlineTLS |
Accept new [inbound] socket connetions. (This is typically used in a loop.)
accept()
function.randolf::rex::xEBADF | The underlying socket is not open |
randolf::rex::xECONNABORTED | The connection was aborted |
randolf::rex::xEFAULT | Address structure/memory is not in a writable part of the user address space |
randolf::rex::xEHOSTDOWN | Host is down or its network is disconnected |
randolf::rex::xEHOSTUNREACH | No route to host |
randolf::rex::xEINTR | Interrupted by a signal |
randolf::rex::xEINVAL | Socket is not in listen() mode or the length of the address is invalid |
randolf::rex::xEMFILE | Per-process maximum open files limit reached |
randolf::rex::xENETDOWN | Network is disconnected or router is down |
randolf::rex::xENETUNREACH | No route to network |
randolf::rex::xENFILE | System-wide maximum open files limit reached |
randolf::rex::xENOBUFS | Insufficient memory |
randolf::rex::xENOMEM | Insufficient memory |
randolf::rex::xENONET | Requested host is not reachable on the network |
randolf::rex::xENOPROTOOPT | Either the level or the specified optname is not supported |
randolf::rex::xENOSR | System ran out of stream resources |
randolf::rex::xENOTSOCK | Underlying socket file descriptor (handle) doesn't refer to a socket |
randolf::rex::xEOPNOTSUPP | Underlying socket is no of type SOCK_STREAM |
randolf::rex::xEPERM | Connection forbidden/denied by firewall rules |
randolf::rex::xEPROTO | Protocol error |
randolf::rex::xEPROTONOSUPPORT | Specified type or protocol is not supported within the specified family (a.k.a., communication domain) |
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) |
randolf::rex::xESOCKTNOSUPPORT | Specified socket type is not supported within the specified family (a.k.a., communication domain) |
randolf::rex::xETIMEDOUT | Timeout period elapsed |
randolf::rex::xEWOULDBLOCK | The underlying socket is non-blocking and no inbound connections are waiting |
|
inlinePOSIXTLS |
Accept new [inbound] socket connetions, with socket flags specified. (This is typically used in a loop.)
accept4()
function.randolf::rex::xEBADF | The underlying socket is not open |
randolf::rex::xECONNABORTED | The connection was aborted |
randolf::rex::xEFAULT | Address structure/memory is not in a writable part of the user address space |
randolf::rex::xEHOSTDOWN | Host is down or its network is disconnected |
randolf::rex::xEHOSTUNREACH | No route to host |
randolf::rex::xEINTR | Interrupted by a signal |
randolf::rex::xEINVAL | Socket is not in listen() mode or the length of the address is invalid |
randolf::rex::xEINVAL | Invalid value in flags |
randolf::rex::xEMFILE | Per-process maximum open files limit reached |
randolf::rex::xENETDOWN | Network is disconnected or router is down |
randolf::rex::xENETUNREACH | No route to network |
randolf::rex::xENFILE | System-wide maximum open files limit reached |
randolf::rex::xENOBUFS | Insufficient memory |
randolf::rex::xENOMEM | Insufficient memory |
randolf::rex::xENONET | Requested host is not reachable on the network |
randolf::rex::xENOPROTOOPT | Either the level or the specified optname is not supported |
randolf::rex::xENOSR | System ran out of stream resources |
randolf::rex::xENOTSOCK | Underlying socket file descriptor (handle) doesn't refer to a socket |
randolf::rex::xEOPNOTSUPP | Underlying socket is no of type SOCK_STREAM |
randolf::rex::xEPERM | Connection forbidden/denied by firewall rules |
randolf::rex::xEPROTO | Protocol error |
randolf::rex::xEPROTONOSUPPORT | Specified type or protocol is not supported within the specified family (a.k.a., communication domain) |
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) |
randolf::rex::xESOCKTNOSUPPORT | Specified socket type is not supported within the specified family (a.k.a., communication domain) |
randolf::rex::xETIMEDOUT | Timeout period elapsed |
randolf::rex::xEWOULDBLOCK | The underlying socket is non-blocking and no inbound connections are waiting |
posix_flags | SOCK_NONBLOCK SOCK_CLOEXEC |
|
inlineTLS |
Accept new [inbound] socket connetions, with socket flags specified. (This is typically used in a loop.)
accept4()
function.randolf::rex::xEBADF | The underlying socket is not open |
randolf::rex::xECONNABORTED | The connection was aborted |
randolf::rex::xEFAULT | Address structure/memory is not in a writable part of the user address space |
randolf::rex::xEHOSTDOWN | Host is down or its network is disconnected |
randolf::rex::xEHOSTUNREACH | No route to host |
randolf::rex::xEINTR | Interrupted by a signal |
randolf::rex::xEINVAL | Socket is not in listen() mode or the length of the address is invalid |
randolf::rex::xEINVAL | Invalid value in flags |
randolf::rex::xEMFILE | Per-process maximum open files limit reached |
randolf::rex::xENETDOWN | Network is disconnected or router is down |
randolf::rex::xENETUNREACH | No route to network |
randolf::rex::xENFILE | System-wide maximum open files limit reached |
randolf::rex::xENOBUFS | Insufficient memory |
randolf::rex::xENOMEM | Insufficient memory |
randolf::rex::xENONET | Requested host is not reachable on the network |
randolf::rex::xENOPROTOOPT | Either the level or the specified optname is not supported |
randolf::rex::xENOSR | System ran out of stream resources |
randolf::rex::xENOTSOCK | Underlying socket file descriptor (handle) doesn't refer to a socket |
randolf::rex::xEOPNOTSUPP | Underlying socket is no of type SOCK_STREAM |
randolf::rex::xEPERM | Connection forbidden/denied by firewall rules |
randolf::rex::xEPROTO | Protocol error |
randolf::rex::xEPROTONOSUPPORT | Specified type or protocol is not supported within the specified family (a.k.a., communication domain) |
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) |
randolf::rex::xESOCKTNOSUPPORT | Specified socket type is not supported within the specified family (a.k.a., communication domain) |
randolf::rex::xETIMEDOUT | Timeout period elapsed |
randolf::rex::xEWOULDBLOCK | The underlying socket is non-blocking and no inbound connections are waiting |
posix_flags | SOCK_NONBLOCK SOCK_CLOEXEC |
|
inlinenoexceptTLS |
Override the default listen backlog for this rsocket.
backlog | Backlog queue size (0 = use SOMAXCONN, which is the system default of 4096 on Linux, and 128 on older systems) |
|
inlinenoexceptTLS |
Find out what this rsocket's default listen backlog is.
|
inlinePOSIXTLS |
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 connect() method (this bound address is the address from which the endpoint will recieve your connection).
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 |
randolf::rex::xEACCES | If binding to an interface on systems that require elevated access for direct interface binding in absence of said elevated access |
randolf::rex::xEADDRINUSE | Address and/or port number already in use |
randolf::rex::xEADDRNOTAVAIL | The interface doesn't exist or the address is not available on any local interface |
randolf::rex::xEBADF | The underlying socket is not open |
randolf::rex::xEFAULT | Address structure/memory is not in a writable part of the user address space |
randolf::rex::xEINVAL | Socket is already bound |
randolf::rex::xEINVAL | Address length is incorrect, or address is not valid for this socket's family (a.k.a., communication domain) |
randolf::rex::xENOMEM | Insufficient memory |
randolf::rex::xENOTSOCK | Underlying socket file descriptor (handle) doesn't refer to a socket The following exceptions are specific to AF_UNIX family sockets... |
randolf::rex::xEACCES | Write permission or search permission denied on a component of the path prefix (AF_UNIX family) |
randolf::rex::xELOOP | Too many symbolic links encountered while resolving address (AF_UNIX family) |
randolf::rex::xENAMETOOLONG | Address is too long (AF_UNIX family) |
randolf::rex::xENOENT | One of the path's directory components doesn't exist (AF_UNIX family) |
randolf::rex::xENOTDIR | One of the path's diretory components is not a directory (AF_UNIX family) |
randolf::rex::xEROFS | Read-only file system (AF_UNIX family) |
addr | Socket address structure |
addrlen | Length of socket structure |
|
inlineTLS |
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 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:
AF_INET
)x.x.x.x
where each "x" represents an octet in the range of 0
through 255
(e.g., 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):
0.0.0.1
may be abbreviated to 1
4.0.0.1
may be abbrevaited to 4.1
4.3.0.1
may be abbreviated to 4.3.1
4.3.2.1
is not abbreviated (this is the most common usage)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. 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.AF_INET6
)x:x:x:x:x:x:x:x
where each "x" represents a segment in the range of 0
through 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 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::
will bind to all IPv6 addresses that are assigned to all of the host machine's network interfaces with IPv6 bindings. ::1
(localhost) is useful for serving only those applications that are running on the local host and use an IPv6 socket to communicate.AF_INET
and AF_INET6
)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 adapterif=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 adapterif=eth0
typical for the first ethernet network adapterif=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 adapterSO_BINDTODEVICE
option, and then the bind() function is called with the IPv4 address 0.0.0.0
if the underlying socket was initialized to the AF_INET
family, or the IPv6 address ::
if the underlying socket was initialized to the AF_INET6
family. 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.AF_UNIX
)/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).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 |
randolf::rex::xEACCES | If binding to an interface on systems that require elevated access for direct interface binding in absence of said elevated access |
randolf::rex::xEADDRINUSE | Address and/or port number already in use |
randolf::rex::xEADDRNOTAVAIL | The interface doesn't exist or the address is not available on any local interface |
randolf::rex::xEBADF | The underlying socket is not open |
randolf::rex::xEFAULT | Address structure/memory is not in a writable part of the user address space |
randolf::rex::xEINVAL | Socket is already bound |
randolf::rex::xEINVAL | Address length is incorrect, or address is not valid for this socket's family (a.k.a., communication domain) |
randolf::rex::xENOMEM | Insufficient memory |
randolf::rex::xENOTSOCK | Underlying socket file descriptor (handle) doesn't refer to a socket The following exceptions are specific to AF_UNIX family sockets... |
randolf::rex::xEACCES | Write permission or search permission denied on a component of the path prefix (AF_UNIX family) |
randolf::rex::xELOOP | Too many symbolic links encountered while resolving address (AF_UNIX family) |
randolf::rex::xENAMETOOLONG | Address is too long (AF_UNIX family) |
randolf::rex::xENOENT | One of the path's directory components doesn't exist (AF_UNIX family) |
randolf::rex::xENOTDIR | One of the path's diretory components is not a directory (AF_UNIX family) |
randolf::rex::xEROFS | Read-only file system (AF_UNIX family) |
address | IPv4 address, IPv6 address, hostname, UNIX domain sockets path, or specialized variant (see notes, above) |
port | TCP or UDP port number ranging 1-65535 (0 = ephemeral port; a.k.a., automatic assignment) |
|
inlinenoexceptTLS |
Find out what buffer size is used by the various recv() methods.
|
inlineTLS |
Override the default buffer size (typically 1024) 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.
std::overflow_error | If the new size exceeds the amount of data that's already present in the ring buffer |
nbytes | Size of the new buffer (in bytes) |
|
inlineTLS |
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.
std::overflow_error | If the new size exceeds the amount of data that's already present in the ring buffer |
|
inlinePOSIXTLS |
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.)
randolf::rex::xEBADF | The underlying socket is not open |
randolf::rex::xEINTR | Interrupted by a signal |
randolf::rex::xEIO | An I/O error occurred |
|
inlinenoexceptTLS |
Close this rsocket without throwing any exceptions (an error code is returned instead, which is useful while calling close_passive() from within a destructor).
|
inlinePOSIXTLS |
Connect this socket to a specific endpoint (which may differ from this rsocket's address that was previously configured by the bind() method).
randolf::rex::xEADDRINUSE | Address and/or port number already in use |
randolf::rex::xEADDRNOTAVAIL | No ephemeral ports are available for assignment to unbound socket |
randolf::rex::xEAFNOSUPPORT | Address family not implemented/supported |
randolf::rex::xEAGAIN | Insufficient entries in the routing cache |
randolf::rex::xEALREADY | Previous connection attempt not completed on nonblocking socket |
randolf::rex::xEBADF | The underlying socket is not open |
randolf::rex::xECONNREFUSED | Remote address is not listening for new connections |
randolf::rex::xEFAULT | Address structure/memory is not in a writable part of the user address space |
randolf::rex::xEINPROGRESS | Connection cannot be completed immediately on nonblocking socket (AF_UNIX family fails with xEAGAIN instead) |
randolf::rex::xEINTR | Interrupted by a signal |
randolf::rex::xEISCONN | Socket is already connected |
randolf::rex::xENETUNREACH | No route to network |
randolf::rex::xENOTSOCK | Underlying socket file descriptor (handle) doesn't refer to a socket |
randolf::rex::xEPERM | Connection forbidden/denied by firewall rules |
randolf::rex::xEPERM | Can't connect to a broadcast address when the socket's broadcast flag isn't enabled |
randolf::rex::xEPROTOTYPE | Socket type doesn't support the requested communications protocol (e.g., connecting a UNIX domain socket of type SOCK_STREAM to an endpoint expecting type SOCK_DGRAM ) |
randolf::rex::xETIMEDOUT | Timeout period elapsed The following exceptions are specific to AF_UNIX family sockets... |
randolf::rex::xEACCES | Write permission or search permission denied on a component of the path prefix (AF_UNIX family) |
randolf::rex::xEAGAIN | Connection cannot be completed immediately on nonblocking socket (AF_UNIX family) |
address | IPv4 address, IPv6 address, hostname, or UNIX domain sockets path |
port | TCP or UDP port number ranging 1-65535 (0 = ephemeral port; a.k.a., automatic assignment) |
|
inlinenoexceptTLS |
Find out whether debug mode is enabled.
|
inlinenoexceptTLS |
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.
debug_flag | TRUE = enable debug mode FALSE = disable debug mode (does not close any file handles) |
fd | File descriptor/handle to use for debug output |
|
inlinenoexceptTLS |
Send the specified message as debug output (as long as debug mode is enabled; if disabled, no debug output will be sent).
msg | Debug message as an ASCIIZ string |
|
inlinenoexceptTLS |
Send the specified message as debug output (as long as debug mode is enabled; if disabled, no debug output will be sent).
msg | Debug message as an ASCIIZ string |
msg | Debug message as an std::string object |
|
inlinenoexcept |
Find out which file descriptor/handle is used for debug output.
|
inlinenoexcept |
Specify a different file descriptor/handle to use for debug output.
fd | File descriptor/handle to use for debug output |
|
inlinenoexceptTLS |
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.
|
inlinenoexceptTLS |
Change the prefix used in debug output.
prefix | New debug prefix string |
|
inlineTLS |
Discards the specified number of 8-bit bytes efficiently, and without closing the stream, and without consuming excessive quantities of memory.
randolf::rex::xERANGE | An invalid value was specified for either the nbytes or memory_size parameter (e.g., a negative value, except for -1 with the nbytes parameter) |
nbytes | Number of bytes to discard 0 = use internal buffer_size() -1 = all remaining data waiting to be received (in other words, this method will repeatedly consume all data until encountering eos) |
posix_flags | MSG_OOB MSG_PEEK (ignored, to prevent an endless loop) MSG_WAITALL MSG_DONTWAIT MSG_CMSG_CLOEXEC |
memory_size | Maximum internal read size 0 = default to buffer_size (when 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 nbytes parameter) |
|
inlineTLS |
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 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.
randolf::rex::xERANGE | An invalid value was specified for either the nbytes or memory_size parameter (e.g., a negative value, except for -1 with the nbytes parameter) |
nbytes | Number of bytes to discard 0 = use internal buffer_size() -1 = all remaining data waiting to be received (in other words, this method will repeatedly consume all data until encountering eos) |
posix_flags | MSG_OOB MSG_PEEK (ignored, to prevent an endless loop) MSG_WAITALL MSG_DONTWAIT MSG_CMSG_CLOEXEC |
timeout | Line timeout (in seconds) 0 = no timeout (default), unless it was configured by way of the timeout_recvline(long) method |
memory_size | Maximum internal read size 0 = default to buffer_size (when 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 nbytes parameter) |
|
inlinenoexceptTLS |
Find out what the current EoL (End of Line) sequence is set to.
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.""
), the specialized send_eol() method is the most efficient option for sending an EoL sequence separately. CR
, CRLF
, LF
, and LFCR
.
|
inlinenoexceptTLS |
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.
""
(empty string) = automatically detect on-the-fly (default)\r\n
(CRLF) = Carriage Return + Linefeed (typical for DOS)\r
(CR) = Carriage Return (typical for MacOS)\n
(LF) = Linefeed (typical for UNIX/Linux)\r\n
) is used by most internet protocols (e.g., HTTP, SMTP, POP3, IMAP4, FINGER, NICNAME/WHOIS, etc.). eol | EoL sequence as an ASCIIZ string |
|
inlinenoexceptTLS |
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.
""
(empty string) = automatically detect on-the-fly (default)\r\n
(CRLF) = Carriage Return + Linefeed (typical for DOS)\r
(CR) = Carriage Return (typical for MacOS)\n
(LF) = Linefeed (typical for UNIX/Linux)\r\n
) is used by most internet protocols (e.g., HTTP, SMTP, POP3, IMAP4, FINGER, NICNAME/WHOIS, etc.). eol | EoL sequence as an std::string object |
|
inlinenoexceptTLS |
Configure EoL adoption policy for the recvline() and recv_rline() methods. By default, rsocket is configured with the EoL adoption policy enabled alongside an empty 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 recvline() or recv_rline method.
The EoL adoption policy is only effective when the 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.
flag | TRUE = enable EoL adoption (default) FALSE = disable EoL adoption |
|
inlinenoexceptTLS |
Returns a String containing the EoL character sequence that was consumed by the most recent successful call to the recvline() or 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).
|
inlinenoexceptTLS |
Configure EoL substitution policy for the printf(), printfline(), vprintf(), and vprintfline() methods. By default, rsocket substitutes printf's \n
sequence with the EoL sequence (if defined), but this method can be used to disable this behaviour.
\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 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. flag | TRUE = enable EoL substitution (default) FALSE = disable EoL substitution |
|
inlinenoexceptTLS |
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).
buffer | Buffer that probably contains at least one EoL sequence |
with_eol_size | Size of string with EoL character sequence included (will be updated by this method) |
|
inlineTLS |
Find out if the stream is at its end and that this rsocket's internal buffer (if one had been set up by the 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 true
to implicitly indicate that there's no data pending to be received.
It's better (more efficient) to use this method instead of the MSG_PEEK
flag (with the various 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 recv
methods yet) because this method is specialized in handling this particular condition and responds with an easy-to-use boolean flag.
randolf::rex::xEBADF | The underlying socket is not open |
randolf::rex::xEFAULT | Address structure/memory is not in a writable part of the user address space |
randolf::rex::xEINTR | Interrupted by a signal |
randolf::rex::xENOMEM | Insufficient memory |
randolf::rex::xENOTSOCK | Underlying socket file descriptor (handle) doesn't refer to a socket |
randolf::rex::xETIMEDOUT | Timeout period elapsed (even if the TIMEOUT_BEHAVIOUR flag is not set to 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) |
randolf::rex::xEWOULDBLOCK | The underlying socket is non-blocking and there's no new data |
timeout | Number of milliseconds to wait |
|
inlinestaticTLS |
Find out what the specified IP address string's family (SO_DOMAIN
) is.
randolf::rex::xEADDRNOTAVAIL | The interface doesn't exist or the address is not available on any local interface |
randolf::rex::xEAI_NONAME | If address is an empty string |
AF_UNSPEC
(if family couldn't be determined) AF_INET
(IPv4 address) AF_INET6
(IPv6 address) AF_UNIX
(UNIX Domain address) address | Address, similar to bind() addressing, including non-standard "if=" variant that names a network interface |
preferred_family | Preferred family to return first (used only with interface mode where the network interface is specified after the "if=" prefix); the default value of AF_UNSPEC will return the first family interface found |
|
inlinePOSIXTLS |
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).
randolf::rex::xEBADF | The underlying socket is not open |
randolf::rex::xEFAULT | Address structure/memory is not in a writable part of the user address space |
randolf::rex::xEINVAL | Address length is incorrect, or address is not valid for this socket's family (a.k.a., communication domain) |
randolf::rex::xENOBUFS | Insufficient memory |
randolf::rex::xENOTCONN | Underlying socket is not connected |
randolf::rex::xENOTSOCK | Underlying socket file descriptor (handle) doesn't refer to a socket |
|
inlineTLS |
Get peer name returns the address of the socket as a std::string object.
randolf::rex::xEAI_ADDRFAMILY | if the address can't be determined (e.g., because the family doesn't utilize or support an address {or the format isn't known} |
randolf::rex::xEAFNOSUPPORT | Address family not implemented/supported |
randolf::rex::xEBADF | The underlying socket is not open |
randolf::rex::xEFAULT | Address structure/memory is not in a writable part of the user address space |
randolf::rex::xEINVAL | Address length is incorrect, or address is not valid for this socket's family (a.k.a., communication domain) |
randolf::rex::xENOBUFS | Insufficient memory |
randolf::rex::xENOSPC | Resulting address string exceeds maximum size |
randolf::rex::xENOTCONN | Underlying socket is not connected |
randolf::rex::xENOTSOCK | Underlying socket file descriptor (handle) doesn't refer to a socket |
|
inlinestaticPOSIXTLS |
Get specified "sockaddr_storage" structure's address as a "sockaddr" structure, for sockets in one of the supported families:
randolf::rex::xEAI_ADDRFAMILY | if the address can't be determined (e.g., because the family doesn't utilize or support an address {or the format isn't known} |
sa | The sockaddr_storage structure wherein sockaddr will be referenced from |
|
inlinePOSIXTLS |
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).
randolf::rex::xEBADF | The underlying socket is not open |
randolf::rex::xEFAULT | Address structure/memory is not in a writable part of the user address space |
randolf::rex::xEINVAL | Address length is incorrect, or address is not valid for this socket's family (a.k.a., communication domain) |
randolf::rex::xENOBUFS | Insufficient memory |
randolf::rex::xENOTSOCK | Underlying socket file descriptor (handle) doesn't refer to a socket |
|
inlineTLS |
Get socket name returns the name of the socket as a std::string object.
randolf::rex::xEAI_ADDRFAMILY | if the address can't be determined (e.g., because the family doesn't utilize or support an address {or the format isn't known} |
randolf::rex::xEAFNOSUPPORT | Address family not implemented/supported |
randolf::rex::xEBADF | The underlying socket is not open |
randolf::rex::xEFAULT | Address structure/memory is not in a writable part of the user address space |
randolf::rex::xEINVAL | Address length is incorrect, or address is not valid for this socket's family (a.k.a., communication domain) |
randolf::rex::xENOBUFS | Insufficient memory |
randolf::rex::xENOSPC | Resulting address string exceeds maximum size |
randolf::rex::xENOTSOCK | Underlying socket file descriptor (handle) doesn't refer to a socket |
|
inlineTLS |
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.
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.)
randolf::rex::xEBADF | The underlying socket is not open |
randolf::rex::xEFAULT | Address structure/memory is not in a writable part of the user address space |
randolf::rex::xEINVAL | Address length is incorrect, or address is not valid for this socket's family (a.k.a., communication domain) |
randolf::rex::xENOPROTOOPT | Either the level or the specified optname is not supported |
randolf::rex::xENOTSOCK | Underlying socket file descriptor (handle) doesn't refer to a socket |
level | The level at which the option resides; typically SOL_SOCKET |
option | The name of the option, such as SO_REUSEADDR , SO_LINGER , etc. |
|
inlineTLS |
Get socket option details in the form of an unsigned 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.
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.)
randolf::rex::xEBADF | The underlying socket is not open |
randolf::rex::xEFAULT | Address structure/memory is not in a writable part of the user address space |
randolf::rex::xEINVAL | Address length is incorrect, or address is not valid for this socket's family (a.k.a., communication domain) |
randolf::rex::xENOPROTOOPT | Either the level or the specified optname is not supported |
randolf::rex::xENOTSOCK | Underlying socket file descriptor (handle) doesn't refer to a socket |
level | The level at which the option resides; typically SOL_SOCKET |
option | The name of the option, such as SO_REUSEADDR , SO_LINGER , etc. |
level | The level at which the option resides; typically SOL_SOCKET |
option | The name of the option, such as SO_REUSEADDR , SO_LINGER , etc. |
|
inlineTLS |
Get socket option details in the form of an unsigned character.
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.
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.)
randolf::rex::xEBADF | The underlying socket is not open |
randolf::rex::xEFAULT | Address structure/memory is not in a writable part of the user address space |
randolf::rex::xEINVAL | Address length is incorrect, or address is not valid for this socket's family (a.k.a., communication domain) |
randolf::rex::xENOPROTOOPT | Either the level or the specified optname is not supported |
randolf::rex::xENOTSOCK | Underlying socket file descriptor (handle) doesn't refer to a socket |
level | The level at which the option resides; typically SOL_SOCKET |
option | The name of the option, such as SO_REUSEADDR , SO_LINGER , etc. |
level | The level at which the option resides; typically SOL_SOCKET |
option | The name of the option, such as SO_REUSEADDR , SO_LINGER , etc. |
|
inlineTLS |
Get socket option details in the form of a structure.
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.
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.)
randolf::rex::xEBADF | The underlying socket is not open |
randolf::rex::xEFAULT | Address structure/memory is not in a writable part of the user address space |
randolf::rex::xEINVAL | Address length is incorrect, or address is not valid for this socket's family (a.k.a., communication domain) |
randolf::rex::xENOPROTOOPT | Either the level or the specified optname is not supported |
randolf::rex::xENOTSOCK | Underlying socket file descriptor (handle) doesn't refer to a socket |
level | The level at which the option resides; typically SOL_SOCKET |
option | The name of the option, such as SO_REUSEADDR , SO_LINGER , etc. |
level | The level at which the option resides; typically SOL_SOCKET |
option | The name of the option, such as SO_REUSEADDR , SO_LINGER , etc. |
|
inlineTLS |
Get socket option details in the form of a structure.
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.
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.)
randolf::rex::xEBADF | The underlying socket is not open |
randolf::rex::xEFAULT | Address structure/memory is not in a writable part of the user address space |
randolf::rex::xEINVAL | Address length is incorrect, or address is not valid for this socket's family (a.k.a., communication domain) |
randolf::rex::xENOPROTOOPT | Either the level or the specified optname is not supported |
randolf::rex::xENOTSOCK | Underlying socket file descriptor (handle) doesn't refer to a socket |
level | The level at which the option resides; typically SOL_SOCKET |
option | The name of the option, such as SO_REUSEADDR , SO_LINGER , etc. |
level | The level at which the option resides; typically SOL_SOCKET |
option | The name of the option, such as SO_REUSEADDR , SO_LINGER , etc. |
level | The level at which the option resides; typically SOL_SOCKET |
option | The name of the option, such as SO_REUSEADDR , SO_LINGER , etc. |
|
inlineTLS |
Get socket option details in the form of a structure.
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.
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.)
randolf::rex::xEBADF | The underlying socket is not open |
randolf::rex::xEFAULT | Address structure/memory is not in a writable part of the user address space |
randolf::rex::xEINVAL | Address length is incorrect, or address is not valid for this socket's family (a.k.a., communication domain) |
randolf::rex::xENOPROTOOPT | Either the level or the specified optname is not supported |
randolf::rex::xENOTSOCK | Underlying socket file descriptor (handle) doesn't refer to a socket |
level | The level at which the option resides; typically SOL_SOCKET |
option | The name of the option, such as SO_REUSEADDR , SO_LINGER , etc. |
level | The level at which the option resides; typically SOL_SOCKET |
option | The name of the option, such as SO_REUSEADDR , SO_LINGER , etc. |
level | The level at which the option resides; typically SOL_SOCKET |
option | The name of the option, such as SO_REUSEADDR , SO_LINGER , etc. |
|
inlineTLS |
Get socket option details in the form of a structure.
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.
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.)
randolf::rex::xEBADF | The underlying socket is not open |
randolf::rex::xEFAULT | Address structure/memory is not in a writable part of the user address space |
randolf::rex::xEINVAL | Address length is incorrect, or address is not valid for this socket's family (a.k.a., communication domain) |
randolf::rex::xENOPROTOOPT | Either the level or the specified optname is not supported |
randolf::rex::xENOTSOCK | Underlying socket file descriptor (handle) doesn't refer to a socket |
level | The level at which the option resides; typically SOL_SOCKET |
option | The name of the option, such as SO_REUSEADDR , SO_LINGER , etc. |
level | The level at which the option resides; typically SOL_SOCKET |
option | The name of the option, such as SO_REUSEADDR , SO_LINGER , etc. |
level | The level at which the option resides; typically SOL_SOCKET |
option | The name of the option, such as SO_REUSEADDR , SO_LINGER , etc. |
|
inlineTLS |
Get socket option details in the form of a structure.
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.
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.)
randolf::rex::xEBADF | The underlying socket is not open |
randolf::rex::xEFAULT | Address structure/memory is not in a writable part of the user address space |
randolf::rex::xEINVAL | Address length is incorrect, or address is not valid for this socket's family (a.k.a., communication domain) |
randolf::rex::xENOPROTOOPT | Either the level or the specified optname is not supported |
randolf::rex::xENOTSOCK | Underlying socket file descriptor (handle) doesn't refer to a socket |
level | The level at which the option resides; typically SOL_SOCKET |
option | The name of the option, such as SO_REUSEADDR , SO_LINGER , etc. |
level | The level at which the option resides; typically SOL_SOCKET |
option | The name of the option, such as SO_REUSEADDR , SO_LINGER , etc. |
level | The level at which the option resides; typically SOL_SOCKET |
option | The name of the option, such as SO_REUSEADDR , SO_LINGER , etc. |
|
inlineTLS |
Get socket option details in the form of a structure.
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.
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.)
randolf::rex::xEBADF | The underlying socket is not open |
randolf::rex::xEFAULT | Address structure/memory is not in a writable part of the user address space |
randolf::rex::xEINVAL | Address length is incorrect, or address is not valid for this socket's family (a.k.a., communication domain) |
randolf::rex::xENOPROTOOPT | Either the level or the specified optname is not supported |
randolf::rex::xENOTSOCK | Underlying socket file descriptor (handle) doesn't refer to a socket |
level | The level at which the option resides; typically SOL_SOCKET |
option | The name of the option, such as SO_REUSEADDR , SO_LINGER , etc. |
level | The level at which the option resides; typically SOL_SOCKET |
option | The name of the option, such as SO_REUSEADDR , SO_LINGER , etc. |
level | The level at which the option resides; typically SOL_SOCKET |
option | The name of the option, such as SO_REUSEADDR , SO_LINGER , etc. |
|
inlineTLS |
Get socket option details in the form of a structure.
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.
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.)
randolf::rex::xEBADF | The underlying socket is not open |
randolf::rex::xEFAULT | Address structure/memory is not in a writable part of the user address space |
randolf::rex::xEINVAL | Address length is incorrect, or address is not valid for this socket's family (a.k.a., communication domain) |
randolf::rex::xENOPROTOOPT | Either the level or the specified optname is not supported |
randolf::rex::xENOTSOCK | Underlying socket file descriptor (handle) doesn't refer to a socket |
level | The level at which the option resides; typically SOL_SOCKET |
option | The name of the option, such as SO_REUSEADDR , SO_LINGER , etc. |
level | The level at which the option resides; typically SOL_SOCKET |
option | The name of the option, such as SO_REUSEADDR , SO_LINGER , etc. |
level | The level at which the option resides; typically SOL_SOCKET |
option | The name of the option, such as SO_REUSEADDR , SO_LINGER , etc. |
|
inlineTLS |
Get socket option details in the form of a structure.
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.
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.)
randolf::rex::xEBADF | The underlying socket is not open |
randolf::rex::xEFAULT | Address structure/memory is not in a writable part of the user address space |
randolf::rex::xEINVAL | Address length is incorrect, or address is not valid for this socket's family (a.k.a., communication domain) |
randolf::rex::xENOPROTOOPT | Either the level or the specified optname is not supported |
randolf::rex::xENOTSOCK | Underlying socket file descriptor (handle) doesn't refer to a socket |
level | The level at which the option resides; typically SOL_SOCKET |
option | The name of the option, such as SO_REUSEADDR , SO_LINGER , etc. |
level | The level at which the option resides; typically SOL_SOCKET |
option | The name of the option, such as SO_REUSEADDR , SO_LINGER , etc. |
level | The level at which the option resides; typically SOL_SOCKET |
option | The name of the option, such as SO_REUSEADDR , SO_LINGER , etc. |
|
inlineTLS |
Get socket option details in the form of a structure.
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.
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.)
randolf::rex::xEBADF | The underlying socket is not open |
randolf::rex::xEFAULT | Address structure/memory is not in a writable part of the user address space |
randolf::rex::xEINVAL | Address length is incorrect, or address is not valid for this socket's family (a.k.a., communication domain) |
randolf::rex::xENOPROTOOPT | Either the level or the specified optname is not supported |
randolf::rex::xENOTSOCK | Underlying socket file descriptor (handle) doesn't refer to a socket |
level | The level at which the option resides; typically SOL_SOCKET |
option | The name of the option, such as SO_REUSEADDR , SO_LINGER , etc. |
level | The level at which the option resides; typically SOL_SOCKET |
option | The name of the option, such as SO_REUSEADDR , SO_LINGER , etc. |
level | The level at which the option resides; typically SOL_SOCKET |
option | The name of the option, such as SO_REUSEADDR , SO_LINGER , etc. |
|
inlineTLS |
Get socket option details in the form of a structure.
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.
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.)
randolf::rex::xEBADF | The underlying socket is not open |
randolf::rex::xEFAULT | Address structure/memory is not in a writable part of the user address space |
randolf::rex::xEINVAL | Address length is incorrect, or address is not valid for this socket's family (a.k.a., communication domain) |
randolf::rex::xENOPROTOOPT | Either the level or the specified optname is not supported |
randolf::rex::xENOTSOCK | Underlying socket file descriptor (handle) doesn't refer to a socket |
level | The level at which the option resides; typically SOL_SOCKET |
option | The name of the option, such as SO_REUSEADDR , SO_LINGER , etc. |
level | The level at which the option resides; typically SOL_SOCKET |
option | The name of the option, such as SO_REUSEADDR , SO_LINGER , etc. |
level | The level at which the option resides; typically SOL_SOCKET |
option | The name of the option, such as SO_REUSEADDR , SO_LINGER , etc. |
|
inlineTLS |
Get socket option details in the form of a structure.
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.
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.)
randolf::rex::xEBADF | The underlying socket is not open |
randolf::rex::xEFAULT | Address structure/memory is not in a writable part of the user address space |
randolf::rex::xEINVAL | Address length is incorrect, or address is not valid for this socket's family (a.k.a., communication domain) |
randolf::rex::xENOPROTOOPT | Either the level or the specified optname is not supported |
randolf::rex::xENOTSOCK | Underlying socket file descriptor (handle) doesn't refer to a socket |
level | The level at which the option resides; typically SOL_SOCKET |
option | The name of the option, such as SO_REUSEADDR , SO_LINGER , etc. |
level | The level at which the option resides; typically SOL_SOCKET |
option | The name of the option, such as SO_REUSEADDR , SO_LINGER , etc. |
level | The level at which the option resides; typically SOL_SOCKET |
option | The name of the option, such as SO_REUSEADDR , SO_LINGER , etc. |
|
inlineTLS |
Get socket option details in the form of a structure.
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.
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.)
randolf::rex::xEBADF | The underlying socket is not open |
randolf::rex::xEFAULT | Address structure/memory is not in a writable part of the user address space |
randolf::rex::xEINVAL | Address length is incorrect, or address is not valid for this socket's family (a.k.a., communication domain) |
randolf::rex::xENOPROTOOPT | Either the level or the specified optname is not supported |
randolf::rex::xENOTSOCK | Underlying socket file descriptor (handle) doesn't refer to a socket |
level | The level at which the option resides; typically SOL_SOCKET |
option | The name of the option, such as SO_REUSEADDR , SO_LINGER , etc. |
level | The level at which the option resides; typically SOL_SOCKET |
option | The name of the option, such as SO_REUSEADDR , SO_LINGER , etc. |
level | The level at which the option resides; typically SOL_SOCKET |
option | The name of the option, such as SO_REUSEADDR , SO_LINGER , etc. |
|
inlinePOSIXTLS |
Get underlying socket's address as a std::string, for sockets in one of the supported families:
randolf::rex::xEAI_ADDRFAMILY | if the address can't be determined (e.g., because the family doesn't utilize or support an address {or the format isn't known} |
randolf::rex::xEAFNOSUPPORT | Address family not implemented/supported |
randolf::rex::xENOSPC | Resulting address string exceeds maximum size |
|
inlinestaticPOSIXTLS |
Get specified "sockaddr_storage" structure's address as a std::string, for sockets in one of the supported families:
randolf::rex::xEAI_ADDRFAMILY | if the address can't be determined (e.g., because the family doesn't utilize or support an address {or the format isn't known} |
randolf::rex::xEAFNOSUPPORT | Address family not implemented/supported |
randolf::rex::xENOSPC | Resulting address string exceeds maximum size |
sa | Source structure that [should] contain address data |
|
inlinenoexceptTLS |
Find out whether an internal read buffer was allocated (this is most likely triggered by an attempt to read a line of text).
|
inlinenoexceptTLS |
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).
|
inlinenoexceptTLS |
Find out whether the underlying socket is connected with/to an endpoint.
|
inlinenoexceptTLS |
Find out whether the default byte order for this host is LSB (small endian).
|
inlinenoexceptTLS |
Find out whether the default byte order for this host is MSB (big endian).
|
inlinenoexceptTLS |
Find out if the EoL adoption policy is enabled for the recvline() method (see the eol_adoption method to find out how the dynamically-detected EoL sequence gets adopted, and under what conditions).
|
inlinenoexceptTLS |
Find out if the EoL substitution policy is enabled for the printf(), printfline(), vprintf(), and vprintfline() methods.
|
inlinenoexceptTLS |
Find out whether the underlying socket is open.
|
inlinenoexceptTLS |
Find out whether encrypted communications is enabled or disabled.
|
inlinenoexceptTLS |
Find out whether TLS context is in TLS_CLIENT mode.
|
inlinenoexceptTLS |
Find out whether egress from encryption (to unencrypted mode) is allowed.
|
inlinenoexceptTLS |
Find out whether encrypted communications is exclusive.
|
inlinenoexceptTLS |
Find out whether ingress to encryption (from unencrypted mode) is allowed.
|
inlinenoexceptTLS |
Find out whether TLS context is in TLS_SERVER mode.
|
inlinenoexceptTLS |
Find out whether SNI (Server Name Identifier) is enabled (configured, which implies that an internal callback function was also set up).
|
inlinenoexceptTLS |
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 rsocket_sni object as separate TLS contexts.
When this method returns TRUE
, it means the OpenSSL
callback (which occurs during the TLS handshake process) completed the TLS handshake with one of the TLS certificates that's included in this rsocket's
rsocket_sni object instead of the primary TLS certificate assigned to this rsocket
, and this rsocket
is using the respective TLS context instead of the primary (default) one.
|
inlinePOSIXTLS |
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 kern.somaxconn
, the kernel will automatically override the backlog with the value stored in kern.somaxconn
without generating any errors or warnings.
randolf::rex::xEADDRINUSE | Address and/or port number already in use |
randolf::rex::xEADDRINUSE | No ephemeral ports are available for assignment to unbound socket (should be randolf::rex::xEADDRNOTAVAIL, but it really isn't) |
randolf::rex::xEBADF | The underlying socket is not open |
randolf::rex::xENOTSOCK | Underlying socket file descriptor (handle) doesn't refer to a socket |
randolf::rex::xEOPNOTSUPP | Underlying socket is no of type SOCK_STREAM |
backlog | Backlog queue size (0 = uses rsocket's default; see 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) |
|
inlinestatic |
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.
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).
randolf::rex::xEAI_ADDRFAMILY | If specified network host doesn't have any addresses in the specified address family |
randolf::rex::xEAI_AGAIN | Temporary failure code from DNS server (try again later) |
randolf::rex::xEAI_BADFLAGS | Invalid flags in hints.ai_flags (or hints.ai_flags included AI_CANONNAME with nullptr as name ) |
randolf::rex::xEAI_FAIL | Permanent failure code from DNS server |
randolf::rex::xEAI_FAMILY | The specified family is not supported |
randolf::rex::xEAI_MEMORY | Out of memory |
randolf::rex::xEAI_NONAME | If node_name is nullptr or an empty string |
randolf::rex::xEAI_SERVICE | The specified service is not available for the specified socket type |
randolf::rex::xEAI_SOCKTYPE | The specified socket type is not supported |
randolf::rex::xEAI_SYSTEM | Other system error (use errno to determine what the error is, then run use randolf::rex::rex::mk_exception to throw the correct exception) |
node_name | IP address or UNIX domain socket address to convert |
service_name | Port number (or service name used by some other families) |
hints | Optional pointer to a helpful addrinfo structure |
|
inlinestatic |
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.
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).
randolf::rex::xEAI_ADDRFAMILY | If specified network host doesn't have any addresses in the specified address family |
randolf::rex::xEAI_AGAIN | Temporary failure code from DNS server (try again later) |
randolf::rex::xEAI_BADFLAGS | Invalid flags in hints.ai_flags (or hints.ai_flags included AI_CANONNAME with nullptr as name ) |
randolf::rex::xEAI_FAIL | Permanent failure code from DNS server |
randolf::rex::xEAI_FAMILY | The specified family is not supported |
randolf::rex::xEAI_MEMORY | Out of memory |
randolf::rex::xEAI_NONAME | If node_name is nullptr or an empty string |
randolf::rex::xEAI_SERVICE | The specified service is not available for the specified socket type |
randolf::rex::xEAI_SOCKTYPE | The specified socket type is not supported |
randolf::rex::xEAI_SYSTEM | Other system error (use errno to determine what the error is, then run use randolf::rex::rex::mk_exception to throw the correct exception) |
node_name | IP address or UNIX domain socket address to convert |
service_name | Port number (or service name used by some other families) |
hints | Optional pointer to a helpful addrinfo structure |
node_name | IP address or UNIX domain socket address to convert |
service_name | Port number |
hints | Optional pointer to a helpful addrinfo structure |
|
inlinestatic |
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.
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).
randolf::rex::xEAI_ADDRFAMILY | If specified network host doesn't have any addresses in the specified address family |
randolf::rex::xEAI_AGAIN | Temporary failure code from DNS server (try again later) |
randolf::rex::xEAI_BADFLAGS | Invalid flags in hints.ai_flags (or hints.ai_flags included AI_CANONNAME with nullptr as name ) |
randolf::rex::xEAI_FAIL | Permanent failure code from DNS server |
randolf::rex::xEAI_FAMILY | The specified family is not supported |
randolf::rex::xEAI_MEMORY | Out of memory |
randolf::rex::xEAI_NONAME | If node_name is nullptr or an empty string |
randolf::rex::xEAI_SERVICE | The specified service is not available for the specified socket type |
randolf::rex::xEAI_SOCKTYPE | The specified socket type is not supported |
randolf::rex::xEAI_SYSTEM | Other system error (use errno to determine what the error is, then run use randolf::rex::rex::mk_exception to throw the correct exception) |
node_name | IP address or UNIX domain socket address to convert |
service_name | Port number (or service name used by some other families) |
hints | Optional pointer to a helpful addrinfo structure |
node_name | IP address or UNIX domain socket address to convert |
service_name | Port number |
hints | Optional pointer to a helpful addrinfo structure |
|
inlinestatic |
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.
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).
randolf::rex::xEAI_ADDRFAMILY | If specified network host doesn't have any addresses in the specified address family |
randolf::rex::xEAI_AGAIN | Temporary failure code from DNS server (try again later) |
randolf::rex::xEAI_BADFLAGS | Invalid flags in hints.ai_flags (or hints.ai_flags included AI_CANONNAME with nullptr as name ) |
randolf::rex::xEAI_FAIL | Permanent failure code from DNS server |
randolf::rex::xEAI_FAMILY | The specified family is not supported |
randolf::rex::xEAI_MEMORY | Out of memory |
randolf::rex::xEAI_NONAME | If node_name is nullptr or an empty string |
randolf::rex::xEAI_SERVICE | The specified service is not available for the specified socket type |
randolf::rex::xEAI_SOCKTYPE | The specified socket type is not supported |
randolf::rex::xEAI_SYSTEM | Other system error (use errno to determine what the error is, then run use randolf::rex::rex::mk_exception to throw the correct exception) |
node_name | IP address or UNIX domain socket address to convert |
service_name | Port number (or service name used by some other families) |
hints | Optional pointer to a helpful addrinfo structure |
node_name | IP address or UNIX domain socket address to convert |
service_name | Port number (or server name used by some other families) |
hints | Optional pointer to a helpful addrinfo structure |
|
inlinenoexcept |
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.
name | Name to assign to this rsocket |
|
inlinenoexcept |
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 name_sni() method to find out which hostname is actually being used by TLS.
std::string
if this rsocket doesn't have a name)
|
inlinenoexceptTLS |
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 rsocket_sni object.
|
inlinenoexceptTLS |
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.
|
inlinenoexceptTLS |
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.
Command | Replacement text | Data source (rsocket_io) |
---|---|---|
$$ | One dollar sign ("$") | N/A |
$aR | Total (all) bytes received | bytes_rx + crypt_rx |
$aT | Total (all) bytes transmitted | bytes_tx + crypt_tx |
$bR | Unencrypted bytes received | bytes_rx |
$bT | Unencrypted bytes transmitted | bytes_tx |
$cR | Encrypted bytes recevied | crypt_rx |
$cT | Encrypted bytes transmitted | crypt_tx |
Command | Replacement text | Data source (rsocket_io) |
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.
format | Format string |
len | Length of format string (in bytes), or 0 to auto-detect length if format string is an ASCIIZ string |
addr | Pointer to an rsocket_io structure to read the statistics from (nullptr = use internal copy of current statistics) |
|
inlinenoexceptTLS |
Where the destructor should save final I/O statistics before this rsocket's resources are completely freed/deallocated.
TRUE
prior to relying on the results of the 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). addr | Pointer to rsocket_io structure (nullptr = disabled) |
|
inlinenoexceptTLS |
Where the destructor should save current I/O statistics.
addr | Pointer to rsocket_io structure (nullptr = do nothing) |
|
inlinePOSIXTLS |
Poll the underlying socket using the poll() method for data that's ready for receiving (default), etc.
randolf::rex::xEFAULT | Address structure/memory is not in a writable part of the user address space |
randolf::rex::xEINTR | Interrupted by a signal |
randolf::rex::xENOMEM | Insufficient memory |
randolf::rex::xENOTSOCK | Underlying socket file descriptor (handle) doesn't refer to a socket |
randolf::rex::xETIMEDOUT | Timeout period elapsed (even if the TIMEOUT_BEHAVIOUR flag is not set to 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) |
randolf::rex::xEWOULDBLOCK | The underlying socket is non-blocking and there's no new data |
timeout_behaviour
is set to TIMEOUT_ZERO events | Events bitfield (e.g., POLLIN , POLLOUT , and POLLERR ) |
timeout | Number of milliseconds to wait |
timeout_behaviour | Timeout behaviour (see TIMEOUT_BEHAVIOUR for details) |
|
inlinenoexceptTLS |
Get port number associated with underlying socket descriptor/handle.
Returns 0 if:
The port number can be set in most constructors, or via one of the socket() or bind() methods.
|
inlinePOSIXTLS |
Poll the underlying socket using the ppoll() method for data that's ready for receiving (default), etc.
randolf::rex::xEFAULT | Address structure/memory is not in a writable part of the user address space |
randolf::rex::xEINTR | Interrupted by a signal |
randolf::rex::xENOMEM | Insufficient memory |
randolf::rex::xENOTSOCK | Underlying socket file descriptor (handle) doesn't refer to a socket |
randolf::rex::xETIMEDOUT | Timeout period elapsed (even if the TIMEOUT_BEHAVIOUR flag is not set to 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) |
randolf::rex::xEWOULDBLOCK | The underlying socket is non-blocking and there's no new data |
events | Events bitfield (e.g., POLLIN , POLLOUT , and POLLERR ) |
tmo_p | Timeout |
sigmask | Signal mask |
timeout_behaviour | Timeout behaviour (see TIMEOUT_BEHAVIOUR for details) |
|
inlineTLS |
Poll the underlying socket using the ppoll() method for data that's ready for receiving (default), etc.
randolf::rex::xEFAULT | Address structure/memory is not in a writable part of the user address space |
randolf::rex::xEINTR | Interrupted by a signal |
randolf::rex::xENOMEM | Insufficient memory |
randolf::rex::xENOTSOCK | Underlying socket file descriptor (handle) doesn't refer to a socket |
randolf::rex::xETIMEDOUT | Timeout period elapsed (even if the TIMEOUT_BEHAVIOUR flag is not set to 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) |
randolf::rex::xEWOULDBLOCK | The underlying socket is non-blocking and there's no new data |
events | Events bitfield (e.g., POLLIN , POLLOUT , and POLLERR ) |
tv_sec | Timeout in seconds |
tv_nsec | Timeout in nanoseconds |
sigmask | Signal mask |
timeout_behaviour | Timeout behaviour (see TIMEOUT_BEHAVIOUR for details) |
|
inlinePOSIXTLS |
Send a formatted string to the rsocket endpoint.
The format
is described in the documentation for the POSIX or Standard C Library printf()
function.
randolf::rex::xEBADF | The underlying socket is not open |
randolf::rex::xEILSEQ | An invalid wide-character code was detected |
randolf::rex::xEOVERFLOW | The value returned is greater than {INT_MAX} |
randolf::rex::xEMFILE | Per-process maximum open files limit reached |
randolf::rex::xENOMEM | Insufficient memory |
format | Format string to use |
... | Variadic arguments |
|
inlineTLS |
Send a formatted string to the rsocket endpoint, and append an EoL sequence.
The format
is described in the documentation for the POSIX or Standard C Library printf()
function.
randolf::rex::xEBADF | The underlying socket is not open |
randolf::rex::xEILSEQ | An invalid wide-character code was detected |
randolf::rex::xEOVERFLOW | The value returned is greater than {INT_MAX} |
randolf::rex::xEMFILE | Per-process maximum open files limit reached |
randolf::rex::xENOMEM | Insufficient memory |
format | Format string to use |
... | Variadic arguments |
|
inlineTLS |
Receive data from the endpoint into a std::vector<char>
that is allocated on-the-fly.
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.
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.randolf::rex::xEBADF | The underlying socket is not open |
randolf::rex::xECONNREFUSED | Remote address is not listening for new connections |
randolf::rex::xEFAULT | Address structure/memory is not in a writable part of the user address space |
randolf::rex::xEINTR | Interrupted by a signal |
randolf::rex::xEINVAL | Invalid argument passed |
randolf::rex::xENOMEM | Insufficient memory |
randolf::rex::xENOTCONN | Underlying socket is not connected |
randolf::rex::xENOTSOCK | Underlying socket file descriptor (handle) doesn't refer to a socket |
randolf::rex::xEWOULDBLOCK | The underlying socket is non-blocking and there's no new data |
nbytes | Maximum number of bytes to receive |
posix_flags | MSG_OOB MSG_PEEK MSG_WAITALL MSG_DONTWAIT MSG_CMSG_CLOEXEC |
|
inlinePOSIXTLS |
Receive data from the endpoint into the std::vector
object supplied in the buf
parameter.
The maximum number of bytes that can be received won't exceed the number of bytes that the supplied std::vector<char>
was initialized or resized to.
std::vector
it's important that the resize()
method is used to pre-allocate the underlying char[] array, instead of the unfortunately-named reserve()
method that doesn't pre-allocate, to avoid causing segmentation faults or other undefined behaviours.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.randolf::rex::xEBADF | The underlying socket is not open |
randolf::rex::xECONNREFUSED | Remote address is not listening for new connections |
randolf::rex::xEFAULT | Address structure/memory is not in a writable part of the user address space |
randolf::rex::xEINTR | Interrupted by a signal |
randolf::rex::xEINVAL | Invalid argument passed |
randolf::rex::xENOMEM | Insufficient memory |
randolf::rex::xENOTCONN | Underlying socket is not connected |
randolf::rex::xENOTSOCK | Underlying socket file descriptor (handle) doesn't refer to a socket |
randolf::rex::xEWOULDBLOCK | The underlying socket is non-blocking and there's no new data |
buf
parameter buf | Target std::vector<char> to receive data into |
posix_flags | MSG_OOB MSG_PEEK MSG_WAITALL MSG_DONTWAIT MSG_CMSG_CLOEXEC |
|
inlineTLS |
Receive data from the endpoint into a std::string
object that is allocated on-the-fly.
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.
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.randolf::rex::xEBADF | The underlying socket is not open |
randolf::rex::xECONNREFUSED | Remote address is not listening for new connections |
randolf::rex::xEFAULT | Address structure/memory is not in a writable part of the user address space |
randolf::rex::xEINTR | Interrupted by a signal |
randolf::rex::xEINVAL | Invalid argument passed |
randolf::rex::xENOMEM | Insufficient memory |
randolf::rex::xENOTCONN | Underlying socket is not connected |
randolf::rex::xENOTSOCK | Underlying socket file descriptor (handle) doesn't refer to a socket |
randolf::rex::xEWOULDBLOCK | The underlying socket is non-blocking and there's no new data |
nbytes | Maximum number of bytes to receive |
posix_flags | MSG_OOB MSG_PEEK MSG_WAITALL MSG_DONTWAIT MSG_CMSG_CLOEXEC |
|
inlineTLS |
Receive an ASCIIZ string from the endpoint, including the NULL terminator.
randolf::rex::xEBADF | The underlying socket is not open |
randolf::rex::xECONNREFUSED | Remote address is not listening for new connections |
randolf::rex::xEFAULT | Address structure/memory is not in a writable part of the user address space |
randolf::rex::xEINTR | Interrupted by a signal |
randolf::rex::xEINVAL | Invalid argument passed |
randolf::rex::xENOMEM | Insufficient memory |
randolf::rex::xENOTCONN | Underlying socket is not connected |
randolf::rex::xENOTSOCK | Underlying socket file descriptor (handle) doesn't refer to a socket |
randolf::rex::xERANGE | if no NULL terminator is detected (this may occur before the underlying ASCIIZ string char* array is allocated) |
randolf::rex::xEWOULDBLOCK | The underlying socket is non-blocking and there's no new data |
nbytes | Maximum number of bytes to receive |
posix_flags | MSG_OOB MSG_PEEK MSG_WAITALL MSG_DONTWAIT MSG_CMSG_CLOEXEC |
|
inlineTLS |
Receive one byte (unsigned 8-bit byte) of data from the endpoint.
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.randolf::rex::xEBADF | The underlying socket is not open |
randolf::rex::xECONNREFUSED | Remote address is not listening for new connections |
randolf::rex::xEFAULT | Address structure/memory is not in a writable part of the user address space |
randolf::rex::xEINTR | Interrupted by a signal |
randolf::rex::xEINVAL | Invalid argument passed |
randolf::rex::xENOMEM | Insufficient memory |
randolf::rex::xENOTCONN | Underlying socket is not connected |
randolf::rex::xENOTSOCK | Underlying socket file descriptor (handle) doesn't refer to a socket |
randolf::rex::xEWOULDBLOCK | The underlying socket is non-blocking and there's no new data |
posix_flags | MSG_OOB MSG_PEEK MSG_WAITALL MSG_DONTWAIT MSG_CMSG_CLOEXEC |
|
inlineTLS |
Receive one character (signed 8-bit byte) of data from the endpoint.
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.randolf::rex::xEBADF | The underlying socket is not open |
randolf::rex::xECONNREFUSED | Remote address is not listening for new connections |
randolf::rex::xEFAULT | Address structure/memory is not in a writable part of the user address space |
randolf::rex::xEINTR | Interrupted by a signal |
randolf::rex::xEINVAL | Invalid argument passed |
randolf::rex::xENOMEM | Insufficient memory |
randolf::rex::xENOTCONN | Underlying socket is not connected |
randolf::rex::xENOTSOCK | Underlying socket file descriptor (handle) doesn't refer to a socket |
randolf::rex::xEWOULDBLOCK | The underlying socket is non-blocking and there's no new data |
posix_flags | MSG_OOB MSG_PEEK MSG_WAITALL MSG_DONTWAIT MSG_CMSG_CLOEXEC |
|
inlineTLS |
Receive a line of data from the endpoint, into an 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 recv() and 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 randolf::rline object.
randolf::rex::xEAGAIN | If timeout occurs before EoL |
randolf::rex::xEBADF | The underlying socket is not open |
randolf::rex::xECONNREFUSED | Remote address is not listening for new connections |
randolf::rex::xEFAULT | Address structure/memory is not in a writable part of the user address space |
randolf::rex::xEINTR | Interrupted by a signal |
randolf::rex::xEINVAL | Invalid argument passed |
randolf::rex::xENOMEM | Insufficient memory |
randolf::rex::xENOTCONN | Underlying socket is not connected |
randolf::rex::xENOTSOCK | Underlying socket file descriptor (handle) doesn't refer to a socket |
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 MSG_PEEK flag set}, including recvline() with a larger buffer {see the nbytes parameter}) |
randolf::rex::xERANGE | if the timeout parameter is below 0 |
randolf::rex::xEWOULDBLOCK | The underlying socket is non-blocking and there's no new data |
nbytes | Maximum number of bytes to receive (including EoL character sequence) |
posix_flags | MSG_OOB MSG_PEEK MSG_WAITALL MSG_DONTWAIT MSG_CMSG_CLOEXEC |
timeout | Line timeout (in seconds) 0 = no timeout (default), unless it was configured by way of the timeout_recvline(long) method |
recvline_flags | Configuration parameters |
|
inlineTLS |
Receive a data structure from the endpoint.
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.randolf::rex::xEBADF | The underlying socket is not open |
randolf::rex::xECONNREFUSED | Remote address is not listening for new connections |
randolf::rex::xEFAULT | Address structure/memory is not in a writable part of the user address space |
randolf::rex::xEINTR | Interrupted by a signal |
randolf::rex::xEINVAL | Invalid argument passed |
randolf::rex::xENOMEM | Insufficient memory |
randolf::rex::xENOTCONN | Underlying socket is not connected |
randolf::rex::xENOTSOCK | Underlying socket file descriptor (handle) doesn't refer to a socket |
randolf::rex::xEWOULDBLOCK | The underlying socket is non-blocking and there's no new data |
posix_flags | MSG_OOB MSG_PEEK MSG_WAITALL MSG_DONTWAIT MSG_CMSG_CLOEXEC |
|
inlineTLS |
Receive one 16-bit unsigned integer of data in LSB (little endian) order from the endpoint.
MSG_WAITALL
flag is used behind-the-scenes to prevent premature data reception, which implements temporary blocking while waiting for data.randolf::rex::xEBADF | The underlying socket is not open |
randolf::rex::xECONNREFUSED | Remote address is not listening for new connections |
randolf::rex::xEFAULT | Address structure/memory is not in a writable part of the user address space |
randolf::rex::xEINTR | Interrupted by a signal |
randolf::rex::xEINVAL | Invalid argument passed |
randolf::rex::xENOMEM | Insufficient memory |
randolf::rex::xENOTCONN | Underlying socket is not connected |
randolf::rex::xENOTSOCK | Underlying socket file descriptor (handle) doesn't refer to a socket |
randolf::rex::xEWOULDBLOCK | The underlying socket is non-blocking and there's no new data |
posix_flags | MSG_OOB MSG_PEEK MSG_WAITALL MSG_DONTWAIT MSG_CMSG_CLOEXEC |
|
inlineTLS |
Receive one 16-bit unsigned integer of data in MSB (big endian) order from the endpoint.
MSG_WAITALL
flag is used behind-the-scenes to prevent premature data reception, which implements temporary blocking while waiting for data.randolf::rex::xEBADF | The underlying socket is not open |
randolf::rex::xECONNREFUSED | Remote address is not listening for new connections |
randolf::rex::xEFAULT | Address structure/memory is not in a writable part of the user address space |
randolf::rex::xEINTR | Interrupted by a signal |
randolf::rex::xEINVAL | Invalid argument passed |
randolf::rex::xENOMEM | Insufficient memory |
randolf::rex::xENOTCONN | Underlying socket is not connected |
randolf::rex::xENOTSOCK | Underlying socket file descriptor (handle) doesn't refer to a socket |
randolf::rex::xEWOULDBLOCK | The underlying socket is non-blocking and there's no new data |
posix_flags | MSG_OOB MSG_PEEK MSG_WAITALL MSG_DONTWAIT MSG_CMSG_CLOEXEC |
|
inlineTLS |
Receive one 32-bit unsigned integer of data in LSB (little endian) order from the endpoint.
MSG_WAITALL
flag is used behind-the-scenes to prevent premature data reception, which implements temporary blocking while waiting for data.randolf::rex::xEBADF | The underlying socket is not open |
randolf::rex::xECONNREFUSED | Remote address is not listening for new connections |
randolf::rex::xEFAULT | Address structure/memory is not in a writable part of the user address space |
randolf::rex::xEINTR | Interrupted by a signal |
randolf::rex::xEINVAL | Invalid argument passed |
randolf::rex::xENOMEM | Insufficient memory |
randolf::rex::xENOTCONN | Underlying socket is not connected |
randolf::rex::xENOTSOCK | Underlying socket file descriptor (handle) doesn't refer to a socket |
randolf::rex::xEWOULDBLOCK | The underlying socket is non-blocking and there's no new data |
posix_flags | MSG_OOB MSG_PEEK MSG_WAITALL MSG_DONTWAIT MSG_CMSG_CLOEXEC |
|
inlineTLS |
Receive one 32-bit unsigned integer of data in MSB (big endian) order from the endpoint.
MSG_WAITALL
flag is used behind-the-scenes to prevent premature data reception, which implements temporary blocking while waiting for data.randolf::rex::xEBADF | The underlying socket is not open |
randolf::rex::xECONNREFUSED | Remote address is not listening for new connections |
randolf::rex::xEFAULT | Address structure/memory is not in a writable part of the user address space |
randolf::rex::xEINTR | Interrupted by a signal |
randolf::rex::xEINVAL | Invalid argument passed |
randolf::rex::xENOMEM | Insufficient memory |
randolf::rex::xENOTCONN | Underlying socket is not connected |
randolf::rex::xENOTSOCK | Underlying socket file descriptor (handle) doesn't refer to a socket |
randolf::rex::xEWOULDBLOCK | The underlying socket is non-blocking and there's no new data |
posix_flags | MSG_OOB MSG_PEEK MSG_WAITALL MSG_DONTWAIT MSG_CMSG_CLOEXEC |
|
inlineTLS |
Receive one 64-bit unsigned integer of data in LSB (little endian) order from the endpoint.
MSG_WAITALL
flag is used behind-the-scenes to prevent premature data reception, which implements temporary blocking while waiting for data.randolf::rex::xEBADF | The underlying socket is not open |
randolf::rex::xECONNREFUSED | Remote address is not listening for new connections |
randolf::rex::xEFAULT | Address structure/memory is not in a writable part of the user address space |
randolf::rex::xEINTR | Interrupted by a signal |
randolf::rex::xEINVAL | Invalid argument passed |
randolf::rex::xENOMEM | Insufficient memory |
randolf::rex::xENOTCONN | Underlying socket is not connected |
randolf::rex::xENOTSOCK | Underlying socket file descriptor (handle) doesn't refer to a socket |
randolf::rex::xEWOULDBLOCK | The underlying socket is non-blocking and there's no new data |
posix_flags | MSG_OOB MSG_PEEK MSG_WAITALL MSG_DONTWAIT MSG_CMSG_CLOEXEC |
|
inlineTLS |
Receive one 64-bit unsigned integer of data in MSB (big endian) order from the endpoint.
MSG_WAITALL
flag is used behind-the-scenes to prevent premature data reception, which implements temporary blocking while waiting for data.randolf::rex::xEBADF | The underlying socket is not open |
randolf::rex::xECONNREFUSED | Remote address is not listening for new connections |
randolf::rex::xEFAULT | Address structure/memory is not in a writable part of the user address space |
randolf::rex::xEINTR | Interrupted by a signal |
randolf::rex::xEINVAL | Invalid argument passed |
randolf::rex::xENOMEM | Insufficient memory |
randolf::rex::xENOTCONN | Underlying socket is not connected |
randolf::rex::xENOTSOCK | Underlying socket file descriptor (handle) doesn't refer to a socket |
randolf::rex::xEWOULDBLOCK | The underlying socket is non-blocking and there's no new data |
posix_flags | MSG_OOB MSG_PEEK MSG_WAITALL MSG_DONTWAIT MSG_CMSG_CLOEXEC |
|
inlinePOSIX |
Receive data from a specific endpoint.
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.randolf::rex::xEBADF | The underlying socket is not open |
randolf::rex::xECONNREFUSED | Remote address is not listening for new connections |
randolf::rex::xEFAULT | Address structure/memory is not in a writable part of the user address space |
randolf::rex::xEINTR | Interrupted by a signal |
randolf::rex::xEINVAL | Invalid argument passed |
randolf::rex::xENOMEM | Insufficient memory |
randolf::rex::xENOTCONN | Underlying socket is not connected |
randolf::rex::xENOTSOCK | Underlying socket file descriptor (handle) doesn't refer to a socket |
randolf::rex::xEWOULDBLOCK | The underlying socket is non-blocking and there's no new data |
nbytes | Maximum number of bytes to receive |
posix_flags | MSG_OOB MSG_PEEK MSG_WAITALL MSG_DONTWAIT MSG_CMSG_CLOEXEC |
from | Target endpoint address structure |
fromlen | Size of target endpoint structure |
|
inlineTLS |
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 recv() and recvz() methods tend to be better-suited).
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. The total number of bytes received, including the EoL sequence, will not exceed the total number of byte specified with the nbytes
parameter.
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 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 eol methods.
timeout
parameter with this method, or by using the timeout_recvline(long) method), you may also need to set the socket timeout beforehand using the timeout() method, because recvline
doesn't do this... timeout_recvline sets the overall total timeout for an entire line to be entered
timeout sets the timeout between individual characters received (such as keystrokes from a live end-user)
The 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.
randolf::rex::xEAGAIN
), or a line is too long because there's too much data (longer than a line) without an EoL sequence (randolf::rex::xOVERFLOW
), then that data will not be discarded or consumed, and will remain ready for receiving (recv) or for discarding discard).randolf::rex::xEAGAIN | If timeout occurs before EoL |
randolf::rex::xEBADF | The underlying socket is not open |
randolf::rex::xECONNREFUSED | Remote address is not listening for new connections |
randolf::rex::xEFAULT | Address structure/memory is not in a writable part of the user address space |
randolf::rex::xEINTR | Interrupted by a signal |
randolf::rex::xEINVAL | Invalid argument passed |
randolf::rex::xENOMEM | Insufficient memory |
randolf::rex::xENOTCONN | Underlying socket is not connected |
randolf::rex::xENOTSOCK | Underlying socket file descriptor (handle) doesn't refer to a socket |
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 MSG_PEEK flag set}, including recvline() with a larger buffer {see the nbytes parameter}) |
randolf::rex::xERANGE | if the timeout parameter is below 0 |
randolf::rex::xEWOULDBLOCK | The underlying socket is non-blocking and there's no new data |
nbytes | Maximum number of bytes to receive (including EoL character sequence) 0 = use internal buffer_size() |
posix_flags | MSG_OOB MSG_PEEK MSG_WAITALL MSG_DONTWAIT MSG_CMSG_CLOEXEC |
timeout | Line timeout (in seconds) 0 = no timeout (default), unless it was configured by way of the timeout_recvline(long) method |
recvline_flags | Configuration parameters |
|
inlinePOSIX |
Receive data in the form of a "msghdr" structure.
randolf::rex::xEBADF | The underlying socket is not open |
randolf::rex::xECONNREFUSED | Remote address is not listening for new connections |
randolf::rex::xEFAULT | Address structure/memory is not in a writable part of the user address space |
randolf::rex::xEINTR | Interrupted by a signal |
randolf::rex::xEINVAL | Invalid argument passed |
randolf::rex::xENOMEM | Insufficient memory |
randolf::rex::xENOTCONN | Underlying socket is not connected |
randolf::rex::xENOTSOCK | Underlying socket file descriptor (handle) doesn't refer to a socket |
randolf::rex::xEWOULDBLOCK | The underlying socket is non-blocking and there's no new data |
msg | Pointer to "msghdr" structure (or nullptr for automatic allocation) |
posix_flags | MSG_OOB MSG_PEEK MSG_WAITALL MSG_DONTWAIT MSG_CMSG_CLOEXEC |
|
inlinePOSIX |
Receive data in the form of an "mmsghdr" structure.
randolf::rex::xEBADF | The underlying socket is not open |
randolf::rex::xECONNREFUSED | Remote address is not listening for new connections |
randolf::rex::xEFAULT | Address structure/memory is not in a writable part of the user address space |
randolf::rex::xEINTR | Interrupted by a signal |
randolf::rex::xEINVAL | Invalid argument passed |
randolf::rex::xENOMEM | Insufficient memory |
randolf::rex::xENOTCONN | Underlying socket is not connected |
randolf::rex::xENOTSOCK | Underlying socket file descriptor (handle) doesn't refer to a socket |
randolf::rex::xEWOULDBLOCK | The underlying socket is non-blocking and there's no new data |
mmsg | Pointer to "mmsghdr" structure (or nullptr for automatic allocation) |
vlen | Size of target endpoint structure |
posix_flags | MSG_DONTROUTE MSG_DONTWAIT MSG_EOR MSG_NOSIGNAL MSG_OOB |
timeout | Timeout |
|
inlineTLS |
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.
nbytes + 1
which ensures that any string processing functions or presentation libraries - such as printf()
- expecting an ASCIIZ string buffer will stop at null (0), and will reliably output no more than the maximum size specified. 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 nbytes
parameter.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.randolf::rex::xEBADF | The underlying socket is not open |
randolf::rex::xECONNREFUSED | Remote address is not listening for new connections |
randolf::rex::xEFAULT | Address structure/memory is not in a writable part of the user address space |
randolf::rex::xEINTR | Interrupted by a signal |
randolf::rex::xEINVAL | Invalid argument passed |
randolf::rex::xENOMEM | Insufficient memory |
randolf::rex::xENOTCONN | Underlying socket is not connected |
randolf::rex::xENOTSOCK | Underlying socket file descriptor (handle) doesn't refer to a socket |
randolf::rex::xEWOULDBLOCK | The underlying socket is non-blocking and there's no new data |
nbytes | Maximum number of bytes to receive |
posix_flags | MSG_OOB MSG_PEEK MSG_WAITALL MSG_DONTWAIT MSG_CMSG_CLOEXEC |
|
inlineTLS |
Send data in the form of a std::string to the endpoint.
randolf::rex::xEBADF | The underlying socket is not open |
randolf::rex::xECONNRESET | Connect reset by peer |
randolf::rex::xEDESTADDRREQ | Socket is not connected to an endpoint |
randolf::rex::xEFAULT | Address structure/memory is not in a writable part of the user address space |
randolf::rex::xEINTR | Interrupted by a signal |
randolf::rex::xEINVAL | Invalid argument passed |
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?) |
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) |
randolf::rex::xENOBUFS | Output queue is full, mostly likely due to network congestion (or, less commonly, insufficient memory) |
randolf::rex::xENOMEM | Insufficient memory |
randolf::rex::xENOTCONN | Underlying socket is not connected |
randolf::rex::xENOTSOCK | Underlying socket file descriptor (handle) doesn't refer to a socket |
randolf::rex::xEOPNOTSUPP | Underlying socket is no of type SOCK_STREAM |
randolf::rex::xEPIPE | Connection-oriented socket was shut down on the local end (and SIGPIPE will also be received if MSG_NOSIGNAL isn't set) |
randolf::rex::xEWOULDBLOCK | The underlying socket is non-blocking and there's no new data |
randolf::rex::xEWOULDBLOCK | No ephemeral ports are available for assignment to unbound socket (should be randolf::rex::xEADDRNOTAVAIL, but it really isn't) |
msg | Data to send |
posix_flags | MSG_DONTROUTE MSG_DONTWAIT MSG_EOR MSG_NOSIGNAL MSG_OOB |
|
inlineTLS |
Send data in the form of a std::vector<char> to the endpoint.
randolf::rex::xEBADF | The underlying socket is not open |
randolf::rex::xECONNRESET | Connect reset by peer |
randolf::rex::xEDESTADDRREQ | Socket is not connected to an endpoint |
randolf::rex::xEFAULT | Address structure/memory is not in a writable part of the user address space |
randolf::rex::xEINTR | Interrupted by a signal |
randolf::rex::xEINVAL | Invalid argument passed |
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?) |
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) |
randolf::rex::xENOBUFS | Output queue is full, mostly likely due to network congestion (or, less commonly, insufficient memory) |
randolf::rex::xENOMEM | Insufficient memory |
randolf::rex::xENOTCONN | Underlying socket is not connected |
randolf::rex::xENOTSOCK | Underlying socket file descriptor (handle) doesn't refer to a socket |
randolf::rex::xEOPNOTSUPP | Underlying socket is no of type SOCK_STREAM |
randolf::rex::xEPIPE | Connection-oriented socket was shut down on the local end (and SIGPIPE will also be received if MSG_NOSIGNAL isn't set) |
randolf::rex::xEWOULDBLOCK | The underlying socket is non-blocking and there's no new data |
randolf::rex::xEWOULDBLOCK | No ephemeral ports are available for assignment to unbound socket (should be randolf::rex::xEADDRNOTAVAIL, but it really isn't) |
msg | Data to send |
posix_flags | MSG_DONTROUTE MSG_DONTWAIT MSG_EOR MSG_NOSIGNAL MSG_OOB |
|
inlinePOSIXTLS |
Send data in the form of a C-string to the endpoint.
randolf::rex::xEBADF | The underlying socket is not open |
randolf::rex::xECONNRESET | Connect reset by peer |
randolf::rex::xEDESTADDRREQ | Socket is not connected to an endpoint |
randolf::rex::xEFAULT | Address structure/memory is not in a writable part of the user address space |
randolf::rex::xEINTR | Interrupted by a signal |
randolf::rex::xEINVAL | Invalid argument passed |
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?) |
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) |
randolf::rex::xENOBUFS | Output queue is full, mostly likely due to network congestion (or, less commonly, insufficient memory) |
randolf::rex::xENOMEM | Insufficient memory |
randolf::rex::xENOTCONN | Underlying socket is not connected |
randolf::rex::xENOTSOCK | Underlying socket file descriptor (handle) doesn't refer to a socket |
randolf::rex::xEOPNOTSUPP | Underlying socket is no of type SOCK_STREAM |
randolf::rex::xEPIPE | Connection-oriented socket was shut down on the local end (and SIGPIPE will also be received if MSG_NOSIGNAL isn't set) |
randolf::rex::xEWOULDBLOCK | The underlying socket is non-blocking and there's no new data |
randolf::rex::xEWOULDBLOCK | No ephemeral ports are available for assignment to unbound socket (should be randolf::rex::xEADDRNOTAVAIL, but it really isn't) |
msg | Pointer to data to send |
len | Number of bytes to send, or 0 to auto-detect length if message is an ASCIIZ string |
posix_flags | MSG_DONTROUTE MSG_DONTWAIT MSG_EOR MSG_NOSIGNAL MSG_OOB |
|
inlineTLS |
Send data in the form of an ASCIIZ string to the endpoint, including the terminating NULL character.
randolf::rex::xEBADF | The underlying socket is not open |
randolf::rex::xECONNRESET | Connect reset by peer |
randolf::rex::xEDESTADDRREQ | Socket is not connected to an endpoint |
randolf::rex::xEFAULT | Address structure/memory is not in a writable part of the user address space |
randolf::rex::xEINTR | Interrupted by a signal |
randolf::rex::xEINVAL | Invalid argument passed |
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?) |
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) |
randolf::rex::xENOBUFS | Output queue is full, mostly likely due to network congestion (or, less commonly, insufficient memory) |
randolf::rex::xENOMEM | Insufficient memory |
randolf::rex::xENOTCONN | Underlying socket is not connected |
randolf::rex::xENOTSOCK | Underlying socket file descriptor (handle) doesn't refer to a socket |
randolf::rex::xEOPNOTSUPP | Underlying socket is no of type SOCK_STREAM |
randolf::rex::xEPIPE | Connection-oriented socket was shut down on the local end (and SIGPIPE will also be received if MSG_NOSIGNAL isn't set) |
randolf::rex::xEWOULDBLOCK | The underlying socket is non-blocking and there's no new data |
randolf::rex::xEWOULDBLOCK | No ephemeral ports are available for assignment to unbound socket (should be randolf::rex::xEADDRNOTAVAIL, but it really isn't) |
msg | Pointer to data to send |
posix_flags | MSG_DONTROUTE MSG_DONTWAIT MSG_EOR MSG_NOSIGNAL MSG_OOB |
|
inlineTLS |
Send one 8-bit byte (one unsigned character) of data to the endpoint.
randolf::rex::xEBADF | The underlying socket is not open |
randolf::rex::xECONNRESET | Connect reset by peer |
randolf::rex::xEDESTADDRREQ | Socket is not connected to an endpoint |
randolf::rex::xEFAULT | Address structure/memory is not in a writable part of the user address space |
randolf::rex::xEINTR | Interrupted by a signal |
randolf::rex::xEINVAL | Invalid argument passed |
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?) |
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) |
randolf::rex::xENOBUFS | Output queue is full, mostly likely due to network congestion (or, less commonly, insufficient memory) |
randolf::rex::xENOMEM | Insufficient memory |
randolf::rex::xENOTCONN | Underlying socket is not connected |
randolf::rex::xENOTSOCK | Underlying socket file descriptor (handle) doesn't refer to a socket |
randolf::rex::xEOPNOTSUPP | Underlying socket is no of type SOCK_STREAM |
randolf::rex::xEPIPE | Connection-oriented socket was shut down on the local end (and SIGPIPE will also be received if MSG_NOSIGNAL isn't set) |
randolf::rex::xEWOULDBLOCK | The underlying socket is non-blocking and there's no new data |
randolf::rex::xEWOULDBLOCK | No ephemeral ports are available for assignment to unbound socket (should be randolf::rex::xEADDRNOTAVAIL, but it really isn't) |
value | Data to send |
posix_flags | MSG_DONTROUTE MSG_DONTWAIT MSG_EOR MSG_NOSIGNAL MSG_OOB |
|
inlineTLS |
|
inlineTLS |
Send the EoL sequence to the endpoint.
randolf::rex::xEBADF | The underlying socket is not open |
randolf::rex::xECONNRESET | Connect reset by peer |
randolf::rex::xEDESTADDRREQ | Socket is not connected to an endpoint |
randolf::rex::xEFAULT | Address structure/memory is not in a writable part of the user address space |
randolf::rex::xEINTR | Interrupted by a signal |
randolf::rex::xEINVAL | Invalid argument passed |
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?) |
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) |
randolf::rex::xENOBUFS | Output queue is full, mostly likely due to network congestion (or, less commonly, insufficient memory) |
randolf::rex::xENOMEM | Insufficient memory |
randolf::rex::xENOTCONN | Underlying socket is not connected |
randolf::rex::xENOTSOCK | Underlying socket file descriptor (handle) doesn't refer to a socket |
randolf::rex::xEOPNOTSUPP | Underlying socket is no of type SOCK_STREAM |
randolf::rex::xEPIPE | Connection-oriented socket was shut down on the local end (and SIGPIPE will also be received if MSG_NOSIGNAL isn't set) |
randolf::rex::xEWOULDBLOCK | The underlying socket is non-blocking and there's no new data |
randolf::rex::xEWOULDBLOCK | No ephemeral ports are available for assignment to unbound socket (should be randolf::rex::xEADDRNOTAVAIL, but it really isn't) |
posix_flags | MSG_DONTROUTE MSG_DONTWAIT MSG_EOR MSG_NOSIGNAL MSG_OOB |
|
inlineTLS |
Send a data structure to the endpoint.
randolf::rex::xEBADF | The underlying socket is not open |
randolf::rex::xECONNRESET | Connect reset by peer |
randolf::rex::xEDESTADDRREQ | Socket is not connected to an endpoint |
randolf::rex::xEFAULT | Address structure/memory is not in a writable part of the user address space |
randolf::rex::xEINTR | Interrupted by a signal |
randolf::rex::xEINVAL | Invalid argument passed |
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?) |
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) |
randolf::rex::xENOBUFS | Output queue is full, mostly likely due to network congestion (or, less commonly, insufficient memory) |
randolf::rex::xENOMEM | Insufficient memory |
randolf::rex::xENOTCONN | Underlying socket is not connected |
randolf::rex::xENOTSOCK | Underlying socket file descriptor (handle) doesn't refer to a socket |
randolf::rex::xEOPNOTSUPP | Underlying socket is no of type SOCK_STREAM |
randolf::rex::xEPIPE | Connection-oriented socket was shut down on the local end (and SIGPIPE will also be received if MSG_NOSIGNAL isn't set) |
randolf::rex::xEWOULDBLOCK | The underlying socket is non-blocking and there's no new data |
randolf::rex::xEWOULDBLOCK | No ephemeral ports are available for assignment to unbound socket (should be randolf::rex::xEADDRNOTAVAIL, but it really isn't) |
value | Data to send |
posix_flags | MSG_DONTROUTE MSG_DONTWAIT MSG_EOR MSG_NOSIGNAL MSG_OOB |
|
inlineTLS |
Send one 16-bit unsigned integer of data in LSB (little endian) order to the endpoint.
randolf::rex::xEBADF | The underlying socket is not open |
randolf::rex::xECONNRESET | Connect reset by peer |
randolf::rex::xEDESTADDRREQ | Socket is not connected to an endpoint |
randolf::rex::xEFAULT | Address structure/memory is not in a writable part of the user address space |
randolf::rex::xEINTR | Interrupted by a signal |
randolf::rex::xEINVAL | Invalid argument passed |
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?) |
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) |
randolf::rex::xENOBUFS | Output queue is full, mostly likely due to network congestion (or, less commonly, insufficient memory) |
randolf::rex::xENOMEM | Insufficient memory |
randolf::rex::xENOTCONN | Underlying socket is not connected |
randolf::rex::xENOTSOCK | Underlying socket file descriptor (handle) doesn't refer to a socket |
randolf::rex::xEOPNOTSUPP | Underlying socket is no of type SOCK_STREAM |
randolf::rex::xEPIPE | Connection-oriented socket was shut down on the local end (and SIGPIPE will also be received if MSG_NOSIGNAL isn't set) |
randolf::rex::xEWOULDBLOCK | The underlying socket is non-blocking and there's no new data |
randolf::rex::xEWOULDBLOCK | No ephemeral ports are available for assignment to unbound socket (should be randolf::rex::xEADDRNOTAVAIL, but it really isn't) |
value | Data to send |
posix_flags | MSG_DONTROUTE MSG_DONTWAIT MSG_EOR MSG_NOSIGNAL MSG_OOB |
|
inlineTLS |
Send one 16-bit integer of data in MSB (big endian) order to the endpoint.
randolf::rex::xEBADF | The underlying socket is not open |
randolf::rex::xECONNRESET | Connect reset by peer |
randolf::rex::xEDESTADDRREQ | Socket is not connected to an endpoint |
randolf::rex::xEFAULT | Address structure/memory is not in a writable part of the user address space |
randolf::rex::xEINTR | Interrupted by a signal |
randolf::rex::xEINVAL | Invalid argument passed |
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?) |
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) |
randolf::rex::xENOBUFS | Output queue is full, mostly likely due to network congestion (or, less commonly, insufficient memory) |
randolf::rex::xENOMEM | Insufficient memory |
randolf::rex::xENOTCONN | Underlying socket is not connected |
randolf::rex::xENOTSOCK | Underlying socket file descriptor (handle) doesn't refer to a socket |
randolf::rex::xEOPNOTSUPP | Underlying socket is no of type SOCK_STREAM |
randolf::rex::xEPIPE | Connection-oriented socket was shut down on the local end (and SIGPIPE will also be received if MSG_NOSIGNAL isn't set) |
randolf::rex::xEWOULDBLOCK | The underlying socket is non-blocking and there's no new data |
randolf::rex::xEWOULDBLOCK | No ephemeral ports are available for assignment to unbound socket (should be randolf::rex::xEADDRNOTAVAIL, but it really isn't) |
value | Data to send |
posix_flags | MSG_DONTROUTE MSG_DONTWAIT MSG_EOR MSG_NOSIGNAL MSG_OOB |
|
inlineTLS |
Send one 32-bit unsigned integer of data in LSB (little endian) order to the endpoint.
randolf::rex::xEBADF | The underlying socket is not open |
randolf::rex::xECONNRESET | Connect reset by peer |
randolf::rex::xEDESTADDRREQ | Socket is not connected to an endpoint |
randolf::rex::xEFAULT | Address structure/memory is not in a writable part of the user address space |
randolf::rex::xEINTR | Interrupted by a signal |
randolf::rex::xEINVAL | Invalid argument passed |
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?) |
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) |
randolf::rex::xENOBUFS | Output queue is full, mostly likely due to network congestion (or, less commonly, insufficient memory) |
randolf::rex::xENOMEM | Insufficient memory |
randolf::rex::xENOTCONN | Underlying socket is not connected |
randolf::rex::xENOTSOCK | Underlying socket file descriptor (handle) doesn't refer to a socket |
randolf::rex::xEOPNOTSUPP | Underlying socket is no of type SOCK_STREAM |
randolf::rex::xEPIPE | Connection-oriented socket was shut down on the local end (and SIGPIPE will also be received if MSG_NOSIGNAL isn't set) |
randolf::rex::xEWOULDBLOCK | The underlying socket is non-blocking and there's no new data |
randolf::rex::xEWOULDBLOCK | No ephemeral ports are available for assignment to unbound socket (should be randolf::rex::xEADDRNOTAVAIL, but it really isn't) |
value | Data to send |
posix_flags | MSG_DONTROUTE MSG_DONTWAIT MSG_EOR MSG_NOSIGNAL MSG_OOB |
|
inlineTLS |
Send one 32-bit unsigned integer of data in MSB (big endian) order to the endpoint.
randolf::rex::xEBADF | The underlying socket is not open |
randolf::rex::xECONNRESET | Connect reset by peer |
randolf::rex::xEDESTADDRREQ | Socket is not connected to an endpoint |
randolf::rex::xEFAULT | Address structure/memory is not in a writable part of the user address space |
randolf::rex::xEINTR | Interrupted by a signal |
randolf::rex::xEINVAL | Invalid argument passed |
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?) |
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) |
randolf::rex::xENOBUFS | Output queue is full, mostly likely due to network congestion (or, less commonly, insufficient memory) |
randolf::rex::xENOMEM | Insufficient memory |
randolf::rex::xENOTCONN | Underlying socket is not connected |
randolf::rex::xENOTSOCK | Underlying socket file descriptor (handle) doesn't refer to a socket |
randolf::rex::xEOPNOTSUPP | Underlying socket is no of type SOCK_STREAM |
randolf::rex::xEPIPE | Connection-oriented socket was shut down on the local end (and SIGPIPE will also be received if MSG_NOSIGNAL isn't set) |
randolf::rex::xEWOULDBLOCK | The underlying socket is non-blocking and there's no new data |
randolf::rex::xEWOULDBLOCK | No ephemeral ports are available for assignment to unbound socket (should be randolf::rex::xEADDRNOTAVAIL, but it really isn't) |
value | Data to send |
posix_flags | MSG_DONTROUTE MSG_DONTWAIT MSG_EOR MSG_NOSIGNAL MSG_OOB |
|
inlineTLS |
Send one 64-bit unsigned integer of data in LSB (little endian) order to the endpoint.
randolf::rex::xEBADF | The underlying socket is not open |
randolf::rex::xECONNRESET | Connect reset by peer |
randolf::rex::xEDESTADDRREQ | Socket is not connected to an endpoint |
randolf::rex::xEFAULT | Address structure/memory is not in a writable part of the user address space |
randolf::rex::xEINTR | Interrupted by a signal |
randolf::rex::xEINVAL | Invalid argument passed |
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?) |
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) |
randolf::rex::xENOBUFS | Output queue is full, mostly likely due to network congestion (or, less commonly, insufficient memory) |
randolf::rex::xENOMEM | Insufficient memory |
randolf::rex::xENOTCONN | Underlying socket is not connected |
randolf::rex::xENOTSOCK | Underlying socket file descriptor (handle) doesn't refer to a socket |
randolf::rex::xEOPNOTSUPP | Underlying socket is no of type SOCK_STREAM |
randolf::rex::xEPIPE | Connection-oriented socket was shut down on the local end (and SIGPIPE will also be received if MSG_NOSIGNAL isn't set) |
randolf::rex::xEWOULDBLOCK | The underlying socket is non-blocking and there's no new data |
randolf::rex::xEWOULDBLOCK | No ephemeral ports are available for assignment to unbound socket (should be randolf::rex::xEADDRNOTAVAIL, but it really isn't) |
value | Data to send |
posix_flags | MSG_DONTROUTE MSG_DONTWAIT MSG_EOR MSG_NOSIGNAL MSG_OOB |
|
inlineTLS |
Send one 64-bit unsigned integer of data in MSB (big endian) order to the endpoint.
randolf::rex::xEBADF | The underlying socket is not open |
randolf::rex::xECONNRESET | Connect reset by peer |
randolf::rex::xEDESTADDRREQ | Socket is not connected to an endpoint |
randolf::rex::xEFAULT | Address structure/memory is not in a writable part of the user address space |
randolf::rex::xEINTR | Interrupted by a signal |
randolf::rex::xEINVAL | Invalid argument passed |
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?) |
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) |
randolf::rex::xENOBUFS | Output queue is full, mostly likely due to network congestion (or, less commonly, insufficient memory) |
randolf::rex::xENOMEM | Insufficient memory |
randolf::rex::xENOTCONN | Underlying socket is not connected |
randolf::rex::xENOTSOCK | Underlying socket file descriptor (handle) doesn't refer to a socket |
randolf::rex::xEOPNOTSUPP | Underlying socket is no of type SOCK_STREAM |
randolf::rex::xEPIPE | Connection-oriented socket was shut down on the local end (and SIGPIPE will also be received if MSG_NOSIGNAL isn't set) |
randolf::rex::xEWOULDBLOCK | The underlying socket is non-blocking and there's no new data |
randolf::rex::xEWOULDBLOCK | No ephemeral ports are available for assignment to unbound socket (should be randolf::rex::xEADDRNOTAVAIL, but it really isn't) |
value | Data to send |
posix_flags | MSG_DONTROUTE MSG_DONTWAIT MSG_EOR MSG_NOSIGNAL MSG_OOB |
|
inlineTLS |
Send data in the form of a std::string to the endpoint, with an EoL sequence appended.
randolf::rex::xEBADF | The underlying socket is not open |
randolf::rex::xECONNRESET | Connect reset by peer |
randolf::rex::xEDESTADDRREQ | Socket is not connected to an endpoint |
randolf::rex::xEFAULT | Address structure/memory is not in a writable part of the user address space |
randolf::rex::xEINTR | Interrupted by a signal |
randolf::rex::xEINVAL | Invalid argument passed |
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?) |
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) |
randolf::rex::xENOBUFS | Output queue is full, mostly likely due to network congestion (or, less commonly, insufficient memory) |
randolf::rex::xENOMEM | Insufficient memory |
randolf::rex::xENOTCONN | Underlying socket is not connected |
randolf::rex::xENOTSOCK | Underlying socket file descriptor (handle) doesn't refer to a socket |
randolf::rex::xEOPNOTSUPP | Underlying socket is no of type SOCK_STREAM |
randolf::rex::xEPIPE | Connection-oriented socket was shut down on the local end (and SIGPIPE will also be received if MSG_NOSIGNAL isn't set) |
randolf::rex::xEWOULDBLOCK | The underlying socket is non-blocking and there's no new data |
randolf::rex::xEWOULDBLOCK | No ephemeral ports are available for assignment to unbound socket (should be randolf::rex::xEADDRNOTAVAIL, but it really isn't) |
msg | Data to send |
posix_flags | MSG_DONTROUTE MSG_DONTWAIT MSG_EOR MSG_NOSIGNAL MSG_OOB |
|
inlinePOSIX |
Send data in the form of a "msghdr" structure to a specific endpoint.
randolf::rex::xEBADF | The underlying socket is not open |
randolf::rex::xECONNRESET | Connect reset by peer |
randolf::rex::xEDESTADDRREQ | Socket is not connected to an endpoint |
randolf::rex::xEFAULT | Address structure/memory is not in a writable part of the user address space |
randolf::rex::xEINTR | Interrupted by a signal |
randolf::rex::xEINVAL | Invalid argument passed |
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?) |
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) |
randolf::rex::xENOBUFS | Output queue is full, mostly likely due to network congestion (or, less commonly, insufficient memory) |
randolf::rex::xENOMEM | Insufficient memory |
randolf::rex::xENOTCONN | Underlying socket is not connected |
randolf::rex::xENOTSOCK | Underlying socket file descriptor (handle) doesn't refer to a socket |
randolf::rex::xEOPNOTSUPP | Underlying socket is no of type SOCK_STREAM |
randolf::rex::xEPIPE | Connection-oriented socket was shut down on the local end (and SIGPIPE will also be received if MSG_NOSIGNAL isn't set) |
randolf::rex::xEWOULDBLOCK | The underlying socket is non-blocking and there's no new data |
randolf::rex::xEWOULDBLOCK | No ephemeral ports are available for assignment to unbound socket (should be randolf::rex::xEADDRNOTAVAIL, but it really isn't) |
msg | Pointer to data to send |
posix_flags | MSG_DONTROUTE MSG_DONTWAIT MSG_EOR MSG_NOSIGNAL MSG_OOB |
|
inlinePOSIX |
Send data in the form of a "mmsghdr" structure to a specific endpoint.
randolf::rex::xEBADF | The underlying socket is not open |
randolf::rex::xECONNRESET | Connect reset by peer |
randolf::rex::xEDESTADDRREQ | Socket is not connected to an endpoint |
randolf::rex::xEFAULT | Address structure/memory is not in a writable part of the user address space |
randolf::rex::xEINTR | Interrupted by a signal |
randolf::rex::xEINVAL | Invalid argument passed |
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?) |
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) |
randolf::rex::xENOBUFS | Output queue is full, mostly likely due to network congestion (or, less commonly, insufficient memory) |
randolf::rex::xENOMEM | Insufficient memory |
randolf::rex::xENOTCONN | Underlying socket is not connected |
randolf::rex::xENOTSOCK | Underlying socket file descriptor (handle) doesn't refer to a socket |
randolf::rex::xEOPNOTSUPP | Underlying socket is no of type SOCK_STREAM |
randolf::rex::xEPIPE | Connection-oriented socket was shut down on the local end (and SIGPIPE will also be received if MSG_NOSIGNAL isn't set) |
randolf::rex::xEWOULDBLOCK | The underlying socket is non-blocking and there's no new data |
randolf::rex::xEWOULDBLOCK | No ephemeral ports are available for assignment to unbound socket (should be randolf::rex::xEADDRNOTAVAIL, but it really isn't) |
mmsg | Pointer to data to send |
vlen | Size of target endpoint structure |
posix_flags | MSG_DONTROUTE MSG_DONTWAIT MSG_EOR MSG_NOSIGNAL MSG_OOB |
|
inlinePOSIX |
Send data in the form of a std::string to a specific endpoint.
randolf::rex::xEBADF | The underlying socket is not open |
randolf::rex::xECONNRESET | Connect reset by peer |
randolf::rex::xEDESTADDRREQ | Socket is not connected to an endpoint |
randolf::rex::xEFAULT | Address structure/memory is not in a writable part of the user address space |
randolf::rex::xEINTR | Interrupted by a signal |
randolf::rex::xEINVAL | Invalid argument passed |
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?) |
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) |
randolf::rex::xENOBUFS | Output queue is full, mostly likely due to network congestion (or, less commonly, insufficient memory) |
randolf::rex::xENOMEM | Insufficient memory |
randolf::rex::xENOTCONN | Underlying socket is not connected |
randolf::rex::xENOTSOCK | Underlying socket file descriptor (handle) doesn't refer to a socket |
randolf::rex::xEOPNOTSUPP | Underlying socket is no of type SOCK_STREAM |
randolf::rex::xEPIPE | Connection-oriented socket was shut down on the local end (and SIGPIPE will also be received if MSG_NOSIGNAL isn't set) |
randolf::rex::xEWOULDBLOCK | The underlying socket is non-blocking and there's no new data |
randolf::rex::xEWOULDBLOCK | No ephemeral ports are available for assignment to unbound socket (should be randolf::rex::xEADDRNOTAVAIL, but it really isn't) |
msg | Data to send |
posix_flags | MSG_DONTROUTE MSG_DONTWAIT MSG_EOR MSG_NOSIGNAL MSG_OOB |
to | Target endpoint address structure |
tolen | Size of target endpoint structure |
|
inlinePOSIX |
Send data in the form of a C-string to a specific endpoint.
randolf::rex::xEBADF | The underlying socket is not open |
randolf::rex::xECONNRESET | Connect reset by peer |
randolf::rex::xEDESTADDRREQ | Socket is not connected to an endpoint |
randolf::rex::xEFAULT | Address structure/memory is not in a writable part of the user address space |
randolf::rex::xEINTR | Interrupted by a signal |
randolf::rex::xEINVAL | Invalid argument passed |
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?) |
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) |
randolf::rex::xENOBUFS | Output queue is full, mostly likely due to network congestion (or, less commonly, insufficient memory) |
randolf::rex::xENOMEM | Insufficient memory |
randolf::rex::xENOTCONN | Underlying socket is not connected |
randolf::rex::xENOTSOCK | Underlying socket file descriptor (handle) doesn't refer to a socket |
randolf::rex::xEOPNOTSUPP | Underlying socket is no of type SOCK_STREAM |
randolf::rex::xEPIPE | Connection-oriented socket was shut down on the local end (and SIGPIPE will also be received if MSG_NOSIGNAL isn't set) |
randolf::rex::xEWOULDBLOCK | The underlying socket is non-blocking and there's no new data |
randolf::rex::xEWOULDBLOCK | No ephemeral ports are available for assignment to unbound socket (should be randolf::rex::xEADDRNOTAVAIL, but it really isn't) |
msg | Pointer to data to send |
len | Number of bytes to send |
posix_flags | MSG_DONTROUTE MSG_DONTWAIT MSG_EOR MSG_NOSIGNAL MSG_OOB |
to | Target endpoint address structure |
tolen | Size of target endpoint structure |
|
inlineTLS |
Send data in the form of an ASCIIZ string to the endpoint. The terminating NULL character won't be transmitted.
randolf::rex::xEBADF | The underlying socket is not open |
randolf::rex::xECONNRESET | Connect reset by peer |
randolf::rex::xEDESTADDRREQ | Socket is not connected to an endpoint |
randolf::rex::xEFAULT | Address structure/memory is not in a writable part of the user address space |
randolf::rex::xEINTR | Interrupted by a signal |
randolf::rex::xEINVAL | Invalid argument passed |
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?) |
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) |
randolf::rex::xENOBUFS | Output queue is full, mostly likely due to network congestion (or, less commonly, insufficient memory) |
randolf::rex::xENOMEM | Insufficient memory |
randolf::rex::xENOTCONN | Underlying socket is not connected |
randolf::rex::xENOTSOCK | Underlying socket file descriptor (handle) doesn't refer to a socket |
randolf::rex::xEOPNOTSUPP | Underlying socket is no of type SOCK_STREAM |
randolf::rex::xEPIPE | Connection-oriented socket was shut down on the local end (and SIGPIPE will also be received if MSG_NOSIGNAL isn't set) |
randolf::rex::xEWOULDBLOCK | The underlying socket is non-blocking and there's no new data |
randolf::rex::xEWOULDBLOCK | No ephemeral ports are available for assignment to unbound socket (should be randolf::rex::xEADDRNOTAVAIL, but it really isn't) |
msg | Pointer to data to send |
posix_flags | MSG_DONTROUTE MSG_DONTWAIT MSG_EOR MSG_NOSIGNAL MSG_OOB |
|
inline |
Send data in the form of an ASCIIZ string to a specific endpoint. The terminating NULL character won't be transmitted.
randolf::rex::xEBADF | The underlying socket is not open |
randolf::rex::xECONNRESET | Connect reset by peer |
randolf::rex::xEDESTADDRREQ | Socket is not connected to an endpoint |
randolf::rex::xEFAULT | Address structure/memory is not in a writable part of the user address space |
randolf::rex::xEINTR | Interrupted by a signal |
randolf::rex::xEINVAL | Invalid argument passed |
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?) |
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) |
randolf::rex::xENOBUFS | Output queue is full, mostly likely due to network congestion (or, less commonly, insufficient memory) |
randolf::rex::xENOMEM | Insufficient memory |
randolf::rex::xENOTCONN | Underlying socket is not connected |
randolf::rex::xENOTSOCK | Underlying socket file descriptor (handle) doesn't refer to a socket |
randolf::rex::xEOPNOTSUPP | Underlying socket is no of type SOCK_STREAM |
randolf::rex::xEPIPE | Connection-oriented socket was shut down on the local end (and SIGPIPE will also be received if MSG_NOSIGNAL isn't set) |
randolf::rex::xEWOULDBLOCK | The underlying socket is non-blocking and there's no new data |
randolf::rex::xEWOULDBLOCK | No ephemeral ports are available for assignment to unbound socket (should be randolf::rex::xEADDRNOTAVAIL, but it really isn't) |
msg | Pointer to data to send |
posix_flags | MSG_DONTROUTE MSG_DONTWAIT MSG_EOR MSG_NOSIGNAL MSG_OOB |
to | Target endpoint address structure |
tolen | Size of target endpoint structure |
|
inlinePOSIXTLS |
Set socket option to the specific integer.
randolf::rex::xEBADF | The underlying socket is not open |
randolf::rex::xEFAULT | Address structure/memory is not in a writable part of the user address space |
randolf::rex::xEINVAL | Address length is incorrect, or address is not valid for this socket's family (a.k.a., communication domain) |
randolf::rex::xENOPROTOOPT | Either the level or the specified optname is not supported |
randolf::rex::xENOTSOCK | Underlying socket file descriptor (handle) doesn't refer to a socket |
level | The level at which the option resides; typically SOL_SOCKET |
option | The name of the option, such as SO_REUSEADDR , SO_LINGER , etc. |
value | The value that this socket option will be set to |
|
inlineTLS |
Set socket option to the specific unsigned integer.
randolf::rex::xEBADF | The underlying socket is not open |
randolf::rex::xEFAULT | Address structure/memory is not in a writable part of the user address space |
randolf::rex::xEINVAL | Address length is incorrect, or address is not valid for this socket's family (a.k.a., communication domain) |
randolf::rex::xENOPROTOOPT | Either the level or the specified optname is not supported |
randolf::rex::xENOTSOCK | Underlying socket file descriptor (handle) doesn't refer to a socket |
level | The level at which the option resides; typically SOL_SOCKET |
option | The name of the option, such as SO_REUSEADDR , SO_LINGER , etc. |
value | The value that this socket option will be set to |
randolf::rex::xEBADF | The underlying socket is not open |
randolf::rex::xEFAULT | Address structure/memory is not in a writable part of the user address space |
randolf::rex::xEINVAL | Address length is incorrect, or address is not valid for this socket's family (a.k.a., communication domain) |
randolf::rex::xENOPROTOOPT | Either the level or the specified optname is not supported |
randolf::rex::xENOTSOCK | Underlying socket file descriptor (handle) doesn't refer to a socket |
level | The level at which the option resides; typically SOL_SOCKET |
option | The name of the option, such as SO_REUSEADDR , SO_LINGER , etc. |
value | The value that this socket option will be set to |
|
inlineTLS |
Set socket option to the specific unsigned character.
randolf::rex::xEBADF | The underlying socket is not open |
randolf::rex::xEFAULT | Address structure/memory is not in a writable part of the user address space |
randolf::rex::xEINVAL | Address length is incorrect, or address is not valid for this socket's family (a.k.a., communication domain) |
randolf::rex::xENOPROTOOPT | Either the level or the specified optname is not supported |
randolf::rex::xENOTSOCK | Underlying socket file descriptor (handle) doesn't refer to a socket |
level | The level at which the option resides; typically SOL_SOCKET |
option | The name of the option, such as SO_REUSEADDR , SO_LINGER , etc. |
value | The value that this socket option will be set to |
level | The level at which the option resides; typically SOL_SOCKET |
option | The name of the option, such as SO_REUSEADDR , SO_LINGER , etc. |
value | The value that this socket option will be set to |
|
inlineTLS |
Set socket option to the specific structure.
randolf::rex::xEBADF | The underlying socket is not open |
randolf::rex::xEFAULT | Address structure/memory is not in a writable part of the user address space |
randolf::rex::xEINVAL | Address length is incorrect, or address is not valid for this socket's family (a.k.a., communication domain) |
randolf::rex::xENOPROTOOPT | Either the level or the specified optname is not supported |
randolf::rex::xENOTSOCK | Underlying socket file descriptor (handle) doesn't refer to a socket |
level | The level at which the option resides; typically SOL_SOCKET |
option | The name of the option, such as SO_REUSEADDR , SO_LINGER , etc. |
value | The value that this socket option will be set to |
level | The level at which the option resides; typically SOL_SOCKET |
option | The name of the option, such as SO_REUSEADDR , SO_LINGER , etc. |
value | The structure that this socket option will be set to |
|
inlineTLS |
Set socket option to the specific structure.
randolf::rex::xEBADF | The underlying socket is not open |
randolf::rex::xEFAULT | Address structure/memory is not in a writable part of the user address space |
randolf::rex::xEINVAL | Address length is incorrect, or address is not valid for this socket's family (a.k.a., communication domain) |
randolf::rex::xENOPROTOOPT | Either the level or the specified optname is not supported |
randolf::rex::xENOTSOCK | Underlying socket file descriptor (handle) doesn't refer to a socket |
level | The level at which the option resides; typically SOL_SOCKET |
option | The name of the option, such as SO_REUSEADDR , SO_LINGER , etc. |
value | The value that this socket option will be set to |
level | The level at which the option resides; typically SOL_SOCKET |
option | The name of the option, such as SO_REUSEADDR , SO_LINGER , etc. |
value | The structure that this socket option will be set to |
level | The level at which the option resides; typically SOL_SOCKET |
option | The name of the option, such as SO_REUSEADDR , SO_LINGER , etc. |
value | The structure that this socket option will be set to |
|
inlineTLS |
Set socket option to the specific structure.
randolf::rex::xEBADF | The underlying socket is not open |
randolf::rex::xEFAULT | Address structure/memory is not in a writable part of the user address space |
randolf::rex::xEINVAL | Address length is incorrect, or address is not valid for this socket's family (a.k.a., communication domain) |
randolf::rex::xENOPROTOOPT | Either the level or the specified optname is not supported |
randolf::rex::xENOTSOCK | Underlying socket file descriptor (handle) doesn't refer to a socket |
level | The level at which the option resides; typically SOL_SOCKET |
option | The name of the option, such as SO_REUSEADDR , SO_LINGER , etc. |
value | The value that this socket option will be set to |
level | The level at which the option resides; typically SOL_SOCKET |
option | The name of the option, such as SO_REUSEADDR , SO_LINGER , etc. |
value | The structure that this socket option will be set to |
level | The level at which the option resides; typically SOL_SOCKET |
option | The name of the option, such as SO_REUSEADDR , SO_LINGER , etc. |
value | The structure that this socket option will be set to |
|
inlineTLS |
Set socket option to the specific structure.
randolf::rex::xEBADF | The underlying socket is not open |
randolf::rex::xEFAULT | Address structure/memory is not in a writable part of the user address space |
randolf::rex::xEINVAL | Address length is incorrect, or address is not valid for this socket's family (a.k.a., communication domain) |
randolf::rex::xENOPROTOOPT | Either the level or the specified optname is not supported |
randolf::rex::xENOTSOCK | Underlying socket file descriptor (handle) doesn't refer to a socket |
level | The level at which the option resides; typically SOL_SOCKET |
option | The name of the option, such as SO_REUSEADDR , SO_LINGER , etc. |
value | The value that this socket option will be set to |
level | The level at which the option resides; typically SOL_SOCKET |
option | The name of the option, such as SO_REUSEADDR , SO_LINGER , etc. |
value | The structure that this socket option will be set to |
level | The level at which the option resides; typically SOL_SOCKET |
option | The name of the option, such as SO_REUSEADDR , SO_LINGER , etc. |
value | The structure that this socket option will be set to |
|
inlineTLS |
Set socket option to the specific structure.
randolf::rex::xEBADF | The underlying socket is not open |
randolf::rex::xEFAULT | Address structure/memory is not in a writable part of the user address space |
randolf::rex::xEINVAL | Address length is incorrect, or address is not valid for this socket's family (a.k.a., communication domain) |
randolf::rex::xENOPROTOOPT | Either the level or the specified optname is not supported |
randolf::rex::xENOTSOCK | Underlying socket file descriptor (handle) doesn't refer to a socket |
level | The level at which the option resides; typically SOL_SOCKET |
option | The name of the option, such as SO_REUSEADDR , SO_LINGER , etc. |
value | The value that this socket option will be set to |
level | The level at which the option resides; typically SOL_SOCKET |
option | The name of the option, such as SO_REUSEADDR , SO_LINGER , etc. |
value | The structure that this socket option will be set to |
level | The level at which the option resides; typically SOL_SOCKET |
option | The name of the option, such as SO_REUSEADDR , SO_LINGER , etc. |
value | The structure that this socket option will be set to |
|
inlineTLS |
Set socket option to the specific structure.
randolf::rex::xEBADF | The underlying socket is not open |
randolf::rex::xEFAULT | Address structure/memory is not in a writable part of the user address space |
randolf::rex::xEINVAL | Address length is incorrect, or address is not valid for this socket's family (a.k.a., communication domain) |
randolf::rex::xENOPROTOOPT | Either the level or the specified optname is not supported |
randolf::rex::xENOTSOCK | Underlying socket file descriptor (handle) doesn't refer to a socket |
level | The level at which the option resides; typically SOL_SOCKET |
option | The name of the option, such as SO_REUSEADDR , SO_LINGER , etc. |
value | The value that this socket option will be set to |
level | The level at which the option resides; typically SOL_SOCKET |
option | The name of the option, such as SO_REUSEADDR , SO_LINGER , etc. |
value | The structure that this socket option will be set to |
level | The level at which the option resides; typically SOL_SOCKET |
option | The name of the option, such as SO_REUSEADDR , SO_LINGER , etc. |
value | The structure that this socket option will be set to |
|
inlineTLS |
Set socket option to the specific structure.
randolf::rex::xEBADF | The underlying socket is not open |
randolf::rex::xEFAULT | Address structure/memory is not in a writable part of the user address space |
randolf::rex::xEINVAL | Address length is incorrect, or address is not valid for this socket's family (a.k.a., communication domain) |
randolf::rex::xENOPROTOOPT | Either the level or the specified optname is not supported |
randolf::rex::xENOTSOCK | Underlying socket file descriptor (handle) doesn't refer to a socket |
level | The level at which the option resides; typically SOL_SOCKET |
option | The name of the option, such as SO_REUSEADDR , SO_LINGER , etc. |
value | The value that this socket option will be set to |
level | The level at which the option resides; typically SOL_SOCKET |
option | The name of the option, such as SO_REUSEADDR , SO_LINGER , etc. |
value | The structure that this socket option will be set to |
level | The level at which the option resides; typically SOL_SOCKET |
option | The name of the option, such as SO_REUSEADDR , SO_LINGER , etc. |
value | The structure that this socket option will be set to |
|
inlineTLS |
Set socket option to the specific structure.
randolf::rex::xEBADF | The underlying socket is not open |
randolf::rex::xEFAULT | Address structure/memory is not in a writable part of the user address space |
randolf::rex::xEINVAL | Address length is incorrect, or address is not valid for this socket's family (a.k.a., communication domain) |
randolf::rex::xENOPROTOOPT | Either the level or the specified optname is not supported |
randolf::rex::xENOTSOCK | Underlying socket file descriptor (handle) doesn't refer to a socket |
level | The level at which the option resides; typically SOL_SOCKET |
option | The name of the option, such as SO_REUSEADDR , SO_LINGER , etc. |
value | The value that this socket option will be set to |
level | The level at which the option resides; typically SOL_SOCKET |
option | The name of the option, such as SO_REUSEADDR , SO_LINGER , etc. |
value | The structure that this socket option will be set to |
level | The level at which the option resides; typically SOL_SOCKET |
option | The name of the option, such as SO_REUSEADDR , SO_LINGER , etc. |
value | The structure that this socket option will be set to |
|
inlineTLS |
Set socket option to the specific structure.
randolf::rex::xEBADF | The underlying socket is not open |
randolf::rex::xEFAULT | Address structure/memory is not in a writable part of the user address space |
randolf::rex::xEINVAL | Address length is incorrect, or address is not valid for this socket's family (a.k.a., communication domain) |
randolf::rex::xENOPROTOOPT | Either the level or the specified optname is not supported |
randolf::rex::xENOTSOCK | Underlying socket file descriptor (handle) doesn't refer to a socket |
level | The level at which the option resides; typically SOL_SOCKET |
option | The name of the option, such as SO_REUSEADDR , SO_LINGER , etc. |
value | The value that this socket option will be set to |
level | The level at which the option resides; typically SOL_SOCKET |
option | The name of the option, such as SO_REUSEADDR , SO_LINGER , etc. |
value | The structure that this socket option will be set to |
level | The level at which the option resides; typically SOL_SOCKET |
option | The name of the option, such as SO_REUSEADDR , SO_LINGER , etc. |
value | The structure that this socket option will be set to |
|
inlineTLS |
Set socket option to the specific structure.
randolf::rex::xEBADF | The underlying socket is not open |
randolf::rex::xEFAULT | Address structure/memory is not in a writable part of the user address space |
randolf::rex::xEINVAL | Address length is incorrect, or address is not valid for this socket's family (a.k.a., communication domain) |
randolf::rex::xENOPROTOOPT | Either the level or the specified optname is not supported |
randolf::rex::xENOTSOCK | Underlying socket file descriptor (handle) doesn't refer to a socket |
level | The level at which the option resides; typically SOL_SOCKET |
option | The name of the option, such as SO_REUSEADDR , SO_LINGER , etc. |
value | The value that this socket option will be set to |
level | The level at which the option resides; typically SOL_SOCKET |
option | The name of the option, such as SO_REUSEADDR , SO_LINGER , etc. |
value | The structure that this socket option will be set to |
level | The level at which the option resides; typically SOL_SOCKET |
option | The name of the option, such as SO_REUSEADDR , SO_LINGER , etc. |
value | The structure that this socket option will be set to |
|
inlineTLS |
Set socket option to the specific structure.
randolf::rex::xEBADF | The underlying socket is not open |
randolf::rex::xEFAULT | Address structure/memory is not in a writable part of the user address space |
randolf::rex::xEINVAL | Address length is incorrect, or address is not valid for this socket's family (a.k.a., communication domain) |
randolf::rex::xENOPROTOOPT | Either the level or the specified optname is not supported |
randolf::rex::xENOTSOCK | Underlying socket file descriptor (handle) doesn't refer to a socket |
level | The level at which the option resides; typically SOL_SOCKET |
option | The name of the option, such as SO_REUSEADDR , SO_LINGER , etc. |
value | The value that this socket option will be set to |
level | The level at which the option resides; typically SOL_SOCKET |
option | The name of the option, such as SO_REUSEADDR , SO_LINGER , etc. |
value | The structure that this socket option will be set to |
level | The level at which the option resides; typically SOL_SOCKET |
option | The name of the option, such as SO_REUSEADDR , SO_LINGER , etc. |
value | The structure that this socket option will be set to |
|
inlinePOSIXTLS |
Shut down the underlying socket, partially or fully.
SHUT_RD: | Further receives will be disallowed. |
SHUT_WR: | Further sends will be disallowed (this may cause actions specific to the protocol family of the socket to occur). |
SHUT_RDWR: | Further sends and receives will be disallowed (default). |
randolf::rex::xEBADF | The underlying socket is not open |
randolf::rex::xEINVAL | Invalid argument passed |
randolf::rex::xENOTCONN | Underlying socket is not connected |
randolf::rex::xENOTSOCK | Underlying socket file descriptor (handle) doesn't refer to a socket |
how | SHUT_RD SHUT_RW SHUT_RDWR (default) |
tls_shutdown | 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) |
|
inlinePOSIXTLS |
Complete the configuration of an rsocket that was previously initialized without any parameters (a.k.a., an "empty rsocket").
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 before setting the socket's configuration with one of the socket() methods; for example:
The built-in defaults, when not provided, are as follows ("family" is also known as the "communication domain"):
family
= AF_INETtype
= SOCK_STREAMprotocol
= PF_UNSPECYou 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.)
randolf::rex::xEACCES | Elevated access is needed to open this socket |
randolf::rex::xEAFNOSUPPORT | Address family not implemented/supported |
randolf::rex::xEALREADY | If this socket() method was already used, or it was used after rsocket() initialized with at least one parameter |
randolf::rex::xEINVAL | Protocal family invalid or not available |
randolf::rex::xEINVAL | Invalid flags in type |
randolf::rex::xEMFILE | Per-process maximum open files limit reached |
randolf::rex::xENFILE | System-wide maximum open files limit reached |
randolf::rex::xENOBUFS | Insufficient memory |
randolf::rex::xENOMEM | Insufficient memory |
randolf::rex::xEPROTONOSUPPORT | Specified type or protocol is not supported within the specified family (a.k.a., communication domain) |
family | Communication domain; usually one of: AF_INET (IPv4) AF_INET6 (IPv6) AF_UNIX (UNIX domain sockets) |
type | Communication semantics; usually one of: SOCK_STREAM (common for TCP) SOCK_DGRAM (common for UDP) |
protocol | Network protocol; usually one of: IPPROTO_TCP IPPROTO_UDP IPPROTO_IP PF_UNSPEC (auto-detect) |
|
inlinenoexceptTLS |
Get underlying socket family/domain constant (SO_DOMAIN).
|
inlinenoexceptTLS |
Get underlying socket descriptor/handle.
|
inlineTLS |
Set underlying socket descriptor/handle (to one that is presumed to be open).
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 |
new_socket_fd | New socket descriptor/handle |
|
inlinenoexceptTLS |
Get underlying socket protocol constant (SO_PROTOCOL).
|
inlinenoexceptTLS |
Get underlying socket type constant (SO_TYPE).
|
inlinePOSIXTLS |
Find out whether the underlying socket is at the out-of-band (OOB) mark.
randolf::rex::xEBADF | The underlying socket is not open |
randolf::rex::xEINVAL | The underlying socket file descriptor is not a type to which sockatmark() can be applied |
|
inlineTLS |
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).
randolf::rex::xEBADF | The underlying socket is not open |
randolf::rex::xEFAULT | Address structure/memory is not in a writable part of the user address space |
randolf::rex::xEINVAL | Address length is incorrect, or address is not valid for this socket's family (a.k.a., communication domain) |
randolf::rex::xENOPROTOOPT | Either the level or the specified optname is not supported |
randolf::rex::xENOTSOCK | Underlying socket file descriptor (handle) doesn't refer to a socket |
timeval
socket option structure wrapped in std::shared_ptr
|
inlineTLS |
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).
randolf::rex::xEBADF | The underlying socket is not open |
randolf::rex::xEFAULT | Address structure/memory is not in a writable part of the user address space |
randolf::rex::xEINVAL | Address length is incorrect, or address is not valid for this socket's family (a.k.a., communication domain) |
randolf::rex::xENOPROTOOPT | Either the level or the specified optname is not supported |
randolf::rex::xENOTSOCK | Underlying socket file descriptor (handle) doesn't refer to a socket |
tv | timeval structure |
|
inlineTLS |
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).
randolf::rex::xEBADF | The underlying socket is not open |
randolf::rex::xEFAULT | Address structure/memory is not in a writable part of the user address space |
randolf::rex::xEINVAL | Address length is incorrect, or address is not valid for this socket's family (a.k.a., communication domain) |
randolf::rex::xENOPROTOOPT | Either the level or the specified optname is not supported |
randolf::rex::xENOTSOCK | Underlying socket file descriptor (handle) doesn't refer to a socket |
tv | timeval structure |
tv_sec | Timeout in seconds |
tv_usec | Timeout in microseconds |
|
inlineTLS |
Find out what the read timeout is set to when using the recvline() method.
long
value (0 = no timeout)
|
inlineTLS |
Set the read timeout for the recvline() method (the recvline() method's timeout
parameter can override this setting).
randolf::rex::xERANGE | if the timeout parameter is below 0 |
timeout | timeval structure |
|
inlineTLS |
Enable or disable encrypted communications (from the OpenSSL library).
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 tls_ctx() method (regardless of whether encryption is being enabled or disabled). If the default TLS_FLAGS aren't sufficient for the needs of your application, then the tls_ctx() method facilitates this regardless of wehther rsocket is open.
STARTTLS
, which is commonly transmitted in unencrypted form, like 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 recv
methods (I hope that including this information here in this documentation will be helpful): SSL_ERROR_UNKNOWN: error:0A00010B:SSL routines::wrong version numberThis 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).
randolf::rex::xALL | Catch this exception for now (at this time, the OpenSSL library doesn't document which errors may be returned) |
status | TRUE = Enable encrypted communications FALSE = Disable encrypted communications |
flags | Configuration parameters |
|
inlinenoexceptTLS |
Return the current TLS context (multiple TLS contexts are supported, although typically needed to support SNI with inbound connections).
SSL_CTX*
in the documentation for OpenSSL), or nullptr if this context was never assigned to (or created by) this rsocket
|
inlineTLS |
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().
randolf::rex::xALL | Catch this exception for now (at this time, the OpenSSL library doesn't document which errors may be returned) |
rtemplate | OpenSSL's TLS context to use (if not provided, a new context will be created automatically using OpenSSL's defaults) |
flags | Configuration parameters |
|
inlineTLS |
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).
rsocket
, which will also be used for non-SNI handshakes.randolf::rex::xALL | Catch this exception for now (at this time, the OpenSSL library doesn't document which errors may be returned) |
ctx | OpenSSL's TLS context to use (if not provided, a new context will be created using OpenSSL's defaults) |
flags | Configuration parameters |
|
inlineTLS |
Check the private key it to ensure it's consistent with the corresponding TLS certificate chain.
randolf::rex::xALL | Catch this exception for now (at this time, the OpenSSL library doesn't document which errors may be returned) |
|
inlineTLS |
Load a TLS certificate chain and private key in PEM format from text files and use them in the TLS context.
randolf::rex::xALL | Catch this exception for now (at this time, the OpenSSL library doesn't document which errors may be returned) |
chain_file | Pointer to ASCIIZ path and filename to certificate chain file (nullptr will simply be ignored) |
key_file | Pointer to ASCIIZ path and filename to private key file (nullptr will simply be ignored) |
|
inlineTLS |
Load a TLS certificate chain and private key in PEM format from text files and use them in the TLS context.
randolf::rex::xALL | Catch this exception for now (at this time, the OpenSSL library doesn't document which errors may be returned) |
chain_file | Pointer to ASCIIZ path and filename to certificate chain file (an empty string will simply be ignored) |
key_file | Pointer to ASCIIZ path and filename to private key file (an empty string will simply be ignored) |
|
inlineTLS |
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 tls_ctx_use_certificate_chain_and_privatekey_files() methods, but without needing the PEM-formatted certificate chain stored in files beforehand.
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).
randolf::rex::xALL | Catch this exception for now (at this time, the OpenSSL library doesn't document which errors may be returned) |
cert_pem_data | Pointer to certificate chain data in PEM format |
key_pem_data | Pointer to private key data in PEM format |
cert_len | Length of cert_pem_data (in bytes), or 0 to auto-detect length if cert_pem_data is an ASCIIZ string |
key_len | Length of key_pem_data (in bytes), or 0 to auto-detect length if key_pem_data is an ASCIIZ string |
random_fill | Whether to overwrite the temporary files with random data before deleting them |
|
inlineTLS |
Load a TLS certificate chain in PEM format from a text file and use it in the TLS context.
randolf::rex::xALL | Catch this exception for now (at this time, the OpenSSL library doesn't document which errors may be returned) |
file | Pointer to ASCIIZ path and filename to certificate chain file |
|
inlineTLS |
Load a TLS certificate chain in PEM format from a text file and use it in the TLS context.
randolf::rex::xALL | Catch this exception for now (at this time, the OpenSSL library doesn't document which errors may be returned) |
file | Path and filename to certificate chain file |
|
inlineTLS |
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 tls_ctx_use_certificate_chain_file() methods, but without needing the PEM-formatted certificate chain stored in a file beforehand.
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).
randolf::rex::xALL | Catch this exception for now (at this time, the OpenSSL library doesn't document which errors may be returned) |
pem_data | Pointer to certificate chain data in PEM format |
len | Length of pem_data (in bytes), or 0 to auto-detect length if pem_data is an ASCIIZ string |
random_fill | Whether to overwrite the temporary file with random data before deleting it |
|
inlineTLS |
Load a TLS private key in PEM format from a text file and use it in the TLS context.
randolf::rex::xALL | Catch this exception for now (at this time, the OpenSSL library doesn't document which errors may be returned) |
file | Pointer to ASCIIZ path-and-filename of private key file |
|
inlineTLS |
Load a TLS private key in PEM format from a text file and use it in the TLS context.
randolf::rex::xALL | Catch this exception for now (at this time, the OpenSSL library doesn't document which errors may be returned) |
file | Path and filename to private key file |
|
inlineTLS |
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 tls_ctx_use_privatekey_file() methods, but without needing the PEM-formatted private key stored in a file beforehand.
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).
randolf::rex::xALL | Catch this exception for now (at this time, the OpenSSL library doesn't document which errors may be returned) |
pem_data | Pointer to private key data in PEM format |
len | Length of pem_data (in bytes), or 0 to auto-detect length if pem_data is an ASCIIZ string |
random_fill | Whether to overwrite the temporary file with random data before deleting it |
|
inlineTLS |
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 STARTTLS
(which are implemented in protocols like SMTP, POP3, IMAP4, MEOW, FTP, NNTP, LDAP, XMPP, etc.).
randolf::rex::xALL | Catch this exception for now (at this time, the OpenSSL library doesn't document which errors may be returned) |
|
inlinenoexceptTLS |
Get OpenSSL's TLS structure.
|
inlinenoexceptTLS |
Return the current rsocket_sni object that this rsocket
will use when accepting incoming encrypted connections.
rsocket_sni
object
|
inlinenoexceptTLS |
Set the current rsocket_sni object that this rsocket
will use when accepting incoming encrypted connections.
Use the 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).
sni | Pointer to the rsocket_sni object to use, or specify nullptr to remove SNI support from this rsocket object |
|
inlinestaticnoexceptTLS |
Convert a 48-bit integer to a machine address in the form of xx:xx:xx:xx:xx:xx
where every instance of 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.
addr | Pointer to 48-bit integer |
|
inlinestaticnoexceptTLS |
Convert a 48-bit integer to a node address in the form of xxxx:xxxx:xxxx
where every instance of 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.
addr | Pointer to 48-bit integer |
|
inlinePOSIXTLS |
Send a formatted string to the rsocket endpoint.
The format
is described in the documentation for the POSIX or Standard C Library printf()
function.
randolf::rex::xEBADF | The underlying socket is not open |
randolf::rex::xEILSEQ | An invalid wide-character code was detected |
randolf::rex::xEOVERFLOW | The value returned is greater than {INT_MAX} |
randolf::rex::xEMFILE | Per-process maximum open files limit reached |
randolf::rex::xENOMEM | Insufficient memory |
format | Format string to use |
args | Variadic arguments in va_list format |
|
inlineTLS |
Send a formatted string to the rsocket endpoint, and append an EoL sequence.
The format
is described in the documentation for the POSIX or Standard C Library printf()
function.
randolf::rex::xEBADF | The underlying socket is not open |
randolf::rex::xEILSEQ | An invalid wide-character code was detected |
randolf::rex::xEOVERFLOW | The value returned is greater than {INT_MAX} |
randolf::rex::xEMFILE | Per-process maximum open files limit reached |
randolf::rex::xENOMEM | Insufficient memory |
format | Format string to use |
args | Variadic arguments in va_list format |