rama::net::socket

Struct SocketOptions

pub struct SocketOptions {Show 53 fields
    pub domain: Domain,
    pub type: Type,
    pub protocol: Option<Protocol>,
    pub address: Option<SocketAddress>,
    pub device: Option<DeviceName>,
    pub broadcast: Option<bool>,
    pub keep_alive: Option<bool>,
    pub linger: Option<Duration>,
    pub out_of_band_inline: Option<bool>,
    pub passcred: Option<bool>,
    pub recv_buffer_size: Option<usize>,
    pub read_timeout: Option<Duration>,
    pub reuse_address: Option<bool>,
    pub send_buffer_size: Option<usize>,
    pub write_timeout: Option<Duration>,
    pub header_included: Option<bool>,
    pub header_included_v6: Option<bool>,
    pub ip_transparent: Option<bool>,
    pub ttl: Option<u32>,
    pub tos: Option<u32>,
    pub recv_tos: Option<bool>,
    pub multicast_hops_v6: Option<u32>,
    pub multicast_all_v4: Option<bool>,
    pub multicast_all_v6: Option<bool>,
    pub multicast_interface_v4: Option<Ipv4Addr>,
    pub multicast_interface_v6: Option<u32>,
    pub multicast_loop_v4: Option<bool>,
    pub multicast_loop_v6: Option<bool>,
    pub multicast_ttl_v4: Option<u32>,
    pub unicast_hops_v6: Option<u32>,
    pub only_v6: Option<bool>,
    pub recv_tclass_v6: Option<bool>,
    pub tclass_v6: Option<u32>,
    pub recv_hoplimit_v6: Option<bool>,
    pub tcp_keep_alive: Option<TcpKeepAlive>,
    pub tcp_no_delay: Option<bool>,
    pub tcp_max_segments: Option<u32>,
    pub tcp_congestion: Option<String>,
    pub mark: Option<u32>,
    pub tcp_cork: Option<bool>,
    pub tcp_quick_ack: Option<bool>,
    pub tcp_thin_linear_timeouts: Option<bool>,
    pub tcp_user_timeout: Option<Duration>,
    pub freebind: Option<bool>,
    pub freebind_ipv6: Option<bool>,
    pub cpu_affinity: Option<usize>,
    pub reuse_port: Option<bool>,
    pub dccp_service: Option<u32>,
    pub dccp_ccid: Option<u8>,
    pub dccp_server_timewait: Option<bool>,
    pub dccp_send_cscov: Option<u32>,
    pub dccp_recv_cscov: Option<u32>,
    pub dccp_qpolicy_txqlen: Option<u32>,
}

Fields§

§domain: Domain§type: Type§protocol: Option<Protocol>§address: Option<SocketAddress>

Bind the Socket to the specified address.

§device: Option<DeviceName>

Bind the Socket to the specified device.

Sets the value for the SO_BINDTODEVICE option on this Socket].

If a socket is bound to an interface, only packets received from that particular interface are processed by the socket. Note that this only works for some socket types, particularly Domain::IPv4 Sockets.

§broadcast: Option<bool>

Set the value of the SO_BROADCAST option for this Socket.

When enabled, this Socket is allowed to send packets to a broadcast address.

§keep_alive: Option<bool>

Set value for the SO_KEEPALIVE option on this Socket.

Enable sending of keep-alive messages on connection-oriented Sockets.

§linger: Option<Duration>

Set value for the SO_LINGER option on this socket.

If linger is not None, a close(2) or shutdown(2) will not return until all queued messages for the socket have been successfully sent or the linger timeout has been reached. Otherwise, the call returns immediately and the closing is done in the background. When the socket is closed as part of exit(2), it always lingers in the background.

§Notes

On most OSs the duration only has a precision of seconds and will be silently truncated.

On Apple platforms (e.g. macOS, iOS, etc) this uses SO_LINGER_SEC.

§out_of_band_inline: Option<bool>

Set value for the SO_OOBINLINE option on this Socket.

If this option is enabled, out-of-band data is directly placed into the receive data stream. Otherwise, out-of-band data is passed only when the MSG_OOB flag is set during receiving. As per RFC6093, TCP Sockets using the Urgent mechanism are encouraged to set this flag.

§passcred: Option<bool>

Set value for the SO_PASSCRED option on this Socket.

If this option is enabled, enables the receiving of the SCM_CREDENTIALS control messages.

§recv_buffer_size: Option<usize>

Set value for the SO_RCVBUF option on this Socket.

Changes the size of the operating system’s receive buffer associated with the Socket.

§read_timeout: Option<Duration>

Set value for the SO_RCVTIMEO option on this Socket.

If timeout is None, then read and recv calls will block indefinitely.

§reuse_address: Option<bool>

Set value for the SO_REUSEADDR option on this Socket.

This indicates that further calls to bind may allow reuse of local addresses. For IPv4 Sockets this means that a Socket may bind even when there’s a Socket already listening on this port.

§send_buffer_size: Option<usize>

Set value for the SO_SNDBUF option on this Socket.

Changes the size of the operating system’s send buffer associated with the Socket.

§write_timeout: Option<Duration>

Set value for the SO_SNDTIMEO option on this Socket.

If timeout is None, then write and send calls will block indefinitely.

§header_included: Option<bool>

Set the value of the IP_HDRINCL option on this Socket.

If enabled, the user supplies an IP header in front of the user data. Valid only for Type::Raw Sockets; see raw(7) for more information.

When this flag is enabled, the values set by IP_OPTIONS, IP_TTL, and IP_TOS are ignored.

§header_included_v6: Option<bool>

Set the value of the IP_HDRINCL option on this Socket.

If enabled, the user supplies an IP header in front of the user data. Valid only for Type::Raw Sockets; see raw(7) for more information.

When this flag is enabled, the values set by IP_OPTIONS are ignored.

§ip_transparent: Option<bool>

Set the value of the IP_TRANSPARENT option on this Socket.

Setting this boolean option enables transparent proxying on this Socket.

This Socket option allows the calling application to bind to a nonlocal IP address and operate both as a client and a server with the foreign address as the local endpoint.

§NOTE

This requires that routing be set up in a way that packets going to the foreign address are routed through the TProxy box (i.e., the system hosting the application that employs the IP_TRANSPARENT socket option). Enabling this Socket option requires superuser privileges (the CAP_NET_ADMIN capability).

TProxy redirection with the iptables TPROXY target also requires that this option be set on the redirected socket.

§ttl: Option<u32>

Set the value of the IP_TTL option for this Socket.

This value sets the time-to-live field that is used in every packet sent from this Socket.

§tos: Option<u32>

Set the value of the IP_TOS option for this Socket.

This value sets the type-of-service field that is used in every packet sent from this Socket.

§NOTE

https://docs.microsoft.com/en-us/windows/win32/winsock/ipproto-ip-socket-options documents that not all versions of windows support IP_TOS.

§recv_tos: Option<bool>

Set the value of the IP_RECVTOS option for this Socket.

If enabled, the IP_TOS ancillary message is passed with incoming packets. It contains a byte which specifies the Type of Service/Precedence field of the packet header.

§multicast_hops_v6: Option<u32>

Set the value of the IPV6_MULTICAST_HOPS option for this Socket.

Indicates the number of “routers” multicast packets will transit for this Socket. The default value is 1 which means that multicast packets don’t leave the local network unless explicitly requested.

§multicast_all_v4: Option<bool>

Set the value of the IP_MULTICAST_ALL option for this Socket.

This option can be used to modify the delivery policy of multicast messages. The argument is a boolean (defaults to true). If set to true, the socket will receive messages from all the groups that have been joined globally on the whole system. Otherwise, it will deliver messages only from the groups that have been explicitly joined (for example via the IP_ADD_MEMBERSHIP option) on this particular socket.

§multicast_all_v6: Option<bool>

Set the value of the IPV6_MULTICAST_ALL option for this Socket.

This option can be used to modify the delivery policy of multicast messages. The argument is a boolean (defaults to true). If set to true, the socket will receive messages from all the groups that have been joined globally on the whole system. Otherwise, it will deliver messages only from the groups that have been explicitly joined (for example via the IPV6_ADD_MEMBERSHIP option) on this particular socket.

§multicast_interface_v4: Option<Ipv4Addr>

Set the value of the IP_MULTICAST_IF option for this Socket.

If enabled, multicast packets will be looped back to the local socket. Note that this may not have any affect on IPv6 sockets.

§multicast_interface_v6: Option<u32>

Set the value of the IPV6_MULTICAST_IF option for this Socket.

Specifies the interface to use for routing multicast packets. Unlike ipv4, this is generally required in ipv6 contexts where network routing prefixes may overlap.

§multicast_loop_v4: Option<bool>

Set the value of the IP_MULTICAST_LOOP option for this Socket.

If enabled, multicast packets will be looped back to the local Socket. Note that this may not have any affect on IPv6 Sockets.

§multicast_loop_v6: Option<bool>

Set the value of the IPV6_MULTICAST_LOOP option for this Socket.

Controls whether this Socket sees the multicast packets it sends itself. Note that this may not have any affect on IPv4 Sockets.

§multicast_ttl_v4: Option<u32>

Set the value of the IP_MULTICAST_TTL option for this Socket.

Indicates the time-to-live value of outgoing multicast packets for this Socket. The default value is 1 which means that multicast packets don’t leave the local network unless explicitly requested.

Note that this may not have any affect on IPv6 Sockets.

§unicast_hops_v6: Option<u32>

Set the value for the IPV6_UNICAST_HOPS option on this Socket.

Specifies the hop limit for ipv6 unicast packets

§only_v6: Option<bool>

Set the value for the IPV6_V6ONLY option on this Socket.

If this is set to true then the socket is restricted to sending and receiving IPv6 packets only. In this case two IPv4 and IPv6 applications can bind the same port at the same time.

If this is set to false then the socket can be used to send and receive packets from an IPv4-mapped IPv6 address.

§recv_tclass_v6: Option<bool>

Set the value of the IPV6_RECVTCLASS option for this Socket.

If enabled, the IPV6_TCLASS ancillary message is passed with incoming packets. It contains a byte which specifies the traffic class field of the packet header.

§tclass_v6: Option<u32>

Set the value of the IPV6_TCLASS option for this Socket.

Specifies the traffic class field that is used in every packets sent from this Socket.

§recv_hoplimit_v6: Option<bool>

Set the value of the IPV6_RECVHOPLIMIT option for this Socket.

The received hop limit is returned as ancillary data by recvmsg() only if the application has enabled the IPV6_RECVHOPLIMIT Socket option.

§tcp_keep_alive: Option<TcpKeepAlive>

Set parameters configuring TCP keepalive probes for this Socket.

The supported parameters depend on the operating system, and are configured using the TcpKeepAlive struct. At a minimum, all systems support configuring the keepalive time: the time after which the OS will start sending keepalive messages on an idle connection.

§Notes

This will enable SO_KEEPALIVE on this Socket, if it is not already enabled.
On some platforms, such as Windows, any keepalive parameters not configured by the TcpKeepalive struct passed to this function may be overwritten with their default values. Therefore, this function should either only be called once per Socket, or the same parameters should be passed every time it is called.

§tcp_no_delay: Option<bool>

Set the value of the TCP_NODELAY option on this Socket.

If set, this option disables the Nagle algorithm. This means that segments are always sent as soon as possible, even if there is only a small amount of data. When not set, data is buffered until there is a sufficient amount to send out, thereby avoiding the frequent sending of small packets.

§tcp_max_segments: Option<u32>

Sets the value of the TCP_MAXSEG option on this Socket.

The TCP_MAXSEG option denotes the TCP Maximum Segment Size and is only available on TCP Sockets.

§tcp_congestion: Option<String>

Set the value of the TCP_CONGESTION option for this Socket.

Specifies the TCP congestion control algorithm to use for this socket.

The value must be a valid TCP congestion control algorithm name of the platform. For example, Linux may supports “reno”, “cubic”.

§mark: Option<u32>

Sets the value for the SO_MARK option on this Socket.

This value sets the socket mark field for each packet sent through this Socket. Changing the mark can be used for mark-based routing without netfilter or for packet filtering.

On Linux this function requires the CAP_NET_ADMIN capability.

§tcp_cork: Option<bool>

Set the value of the TCP_CORK option on this Socket.

If set, don’t send out partial frames. All queued partial frames are sent when the option is cleared again. There is a 200 millisecond ceiling on the time for which output is corked by TCP_CORK. If this ceiling is reached, then queued data is automatically transmitted.

§tcp_quick_ack: Option<bool>

Set the value of the TCP_QUICKACK option on this Socket.

If set, acks are sent immediately, rather than delayed if needed in accordance to normal TCP operation. This flag is not permanent, it only enables a switch to or from quickack mode. Subsequent operation of the TCP protocol will once again enter/leave quickack mode depending on internal protocol processing and factors such as delayed ack timeouts occurring and data transfer.

§tcp_thin_linear_timeouts: Option<bool>

Set the value of the TCP_THIN_LINEAR_TIMEOUTS option on this Socket.

If set, the kernel will dynamically detect a thin-stream connection if there are less than four packets in flight. With less than four packets in flight the normal TCP fast retransmission will not be effective. The kernel will modify the retransmission to avoid the very high latencies that thin stream suffer because of exponential backoff.

§tcp_user_timeout: Option<Duration>

Set the value of the TCP_USER_TIMEOUT option on this Socket.

If set, this specifies the maximum amount of time that transmitted data may remain unacknowledged or buffered data may remain untransmitted before TCP will forcibly close the corresponding connection.

Setting timeout to None or a zero duration causes the system default timeouts to be used. If timeout in milliseconds is larger than c_uint::MAX, the timeout is clamped to c_uint::MAX. For example, when c_uint is a 32-bit value, this limits the timeout to approximately 49.71 days.

§freebind: Option<bool>

Set value for the IP_FREEBIND option on this Socket.

If enabled, this boolean option allows binding to an IP address that is nonlocal or does not (yet) exist. This permits listening on a Socket, without requiring the underlying network interface or the specified dynamic IP address to be up at the time that the application is trying to bind to it.

§freebind_ipv6: Option<bool>

Set value for the IPV6_FREEBIND option on this Socket.

This is an IPv6 counterpart of IP_FREEBIND Socket option on Android/Linux. For more information about this option, see set_freebind.

§cpu_affinity: Option<usize>

Set value for the SO_INCOMING_CPU option on this Socket.

Sets the CPU affinity of the Socket.

§reuse_port: Option<bool>

Set value for the SO_REUSEPORT option on this Socket.

This indicates that further calls to bind may allow reuse of local addresses. For IPv4 Sockets this means that a Socket may bind even when there’s a Socket already listening on this port.

§dccp_service: Option<u32>

Set value for the DCCP_SOCKOPT_SERVICE option on this Socket.

Sets the DCCP service. The specification mandates use of service codes. If this Socket option is not set, the Socket will fall back to 0 (which means that no meaningful service code is present). On active Sockets this is set before connect. On passive Sockets up to 32 service codes can be set before calling bind

§dccp_ccid: Option<u8>

Set value for the DCCP_SOCKOPT_CCID option on this Socket.

This option sets both the TX and RX CCIDs at the same time.

§dccp_server_timewait: Option<bool>

Set value for the DCCP_SOCKOPT_SERVER_TIMEWAIT option on this Socket.

Enables a listening Socket to hold timewait state when closing the connection. This option must be set after accept returns.

§dccp_send_cscov: Option<u32>

Set value for the DCCP_SOCKOPT_SEND_CSCOV option on this Socket.

Both this option and DCCP_SOCKOPT_RECV_CSCOV are used for setting the partial checksum coverage. The default is that checksums always cover the entire packet and that only fully covered application data is accepted by the receiver. Hence, when using this feature on the sender, it must be enabled at the receiver too, with suitable choice of CsCov.

§dccp_recv_cscov: Option<u32>

Set the value of the DCCP_SOCKOPT_RECV_CSCOV option on this Socket.

This option is only useful when combined with dccp_send_cscov.

§dccp_qpolicy_txqlen: Option<u32>

Set value for the DCCP_SOCKOPT_QPOLICY_TXQLEN option on this Socket.

This option sets the maximum length of the output queue. A zero value is interpreted as unbounded queue length.