Struct socket2::SockRef

source · 
pub struct SockRef<'s> {
    socket: ManuallyDrop<Socket>,
    _lifetime: PhantomData<&'s Socket>,
}
Expand description

A reference to a Socket that can be used to configure socket types other than the Socket type itself.

This allows for example a TcpStream, found in the standard library, to be configured using all the additional methods found in the Socket API.

SockRef can be created from any socket type that implements AsFd (Unix) or AsSocket (Windows) using the From implementation.

§Examples

Below is an example of converting a TcpStream into a SockRef.

use std::net::{TcpStream, SocketAddr};

use socket2::SockRef;

// Create `TcpStream` from the standard library.
let address: SocketAddr = "127.0.0.1:1234".parse()?;
let stream = TcpStream::connect(address)?;

// Create a `SockRef`erence to the stream.
let socket_ref = SockRef::from(&stream);
// Use `Socket::set_nodelay` on the stream.
socket_ref.set_nodelay(true)?;
drop(socket_ref);

assert_eq!(stream.nodelay()?, true);

Fields§

§socket: ManuallyDrop<Socket>

Because this is a reference we don’t own the Socket, however Socket closes itself when dropped, so we use ManuallyDrop to prevent it from closing itself.

§_lifetime: PhantomData<&'s Socket>

Because we don’t own the socket we need to ensure the socket remains open while we have a “reference” to it, the lifetime 's ensures this.

Methods from Deref<Target = Socket>§

source

pub(crate) fn as_raw(&self) -> c_int

source

pub fn bind(&self, address: &SockAddr) -> Result<()>

Binds this socket to the specified address.

This function directly corresponds to the bind(2) function on Windows and Unix.

Additional documentation can be found in manual of the OS:

source

pub fn connect(&self, address: &SockAddr) -> Result<()>

Initiate a connection on this socket to the specified address.

This function directly corresponds to the connect(2) function on Windows and Unix.

An error will be returned if listen or connect has already been called on this builder.

Additional documentation can be found in manual of the OS:

§Notes

When using a non-blocking connect (by setting the socket into non-blocking mode before calling this function), socket option can’t be set while connecting. This will cause errors on Windows. Socket options can be safely set before and after connecting the socket.

source

pub fn connect_timeout(&self, addr: &SockAddr, timeout: Duration) -> Result<()>

Initiate a connection on this socket to the specified address, only only waiting for a certain period of time for the connection to be established.

Unlike many other methods on Socket, this does not correspond to a single C function. It sets the socket to nonblocking mode, connects via connect(2), and then waits for the connection to complete with poll(2) on Unix and select on Windows. When the connection is complete, the socket is set back to blocking mode. On Unix, this will loop over EINTR errors.

§Warnings

The non-blocking state of the socket is overridden by this function - it will be returned in blocking mode on success, and in an indeterminate state on failure.

If the connection request times out, it may still be processing in the background - a second call to connect or connect_timeout may fail.

source

pub fn listen(&self, backlog: c_int) -> Result<()>

Mark a socket as ready to accept incoming connection requests using Socket::accept().

This function directly corresponds to the listen(2) function on Windows and Unix.

An error will be returned if listen or connect has already been called on this builder.

Additional documentation can be found in manual of the OS:

source

pub fn accept(&self) -> Result<(Socket, SockAddr)>

Accept a new incoming connection from this listener.

This function uses accept4(2) on platforms that support it and accept(2) platforms that do not.

This function sets the same flags as in done for Socket::new, Socket::accept_raw can be used if you don’t want to set those flags.

Additional documentation can be found in manual of the OS:

source

pub fn accept_raw(&self) -> Result<(Socket, SockAddr)>

Accept a new incoming connection from this listener.

This function directly corresponds to the accept(2) function on Windows and Unix.

source

pub fn local_addr(&self) -> Result<SockAddr>

Returns the socket address of the local half of this socket.

This function directly corresponds to the getsockname(2) function on Windows and Unix.

Additional documentation can be found in manual of the OS:

§Notes

Depending on the OS this may return an error if the socket is not bound.

source

pub fn peer_addr(&self) -> Result<SockAddr>

Returns the socket address of the remote peer of this socket.

This function directly corresponds to the getpeername(2) function on Windows and Unix.

Additional documentation can be found in manual of the OS:

§Notes

This returns an error if the socket is not connected.

source

pub fn type(&self) -> Result<Type>

Returns the Type of this socket by checking the SO_TYPE option on this socket.

source

pub fn try_clone(&self) -> Result<Socket>

Creates a new independently owned handle to the underlying socket.

§Notes

On Unix this uses F_DUPFD_CLOEXEC and thus sets the FD_CLOEXEC on the returned socket.

On Windows this uses WSA_FLAG_NO_HANDLE_INHERIT setting inheriting to false.

On Windows this can not be used function cannot be used on a QOS-enabled socket, see https://docs.microsoft.com/en-us/windows/win32/api/winsock2/nf-winsock2-wsaduplicatesocketw.

source

pub fn nonblocking(&self) -> Result<bool>

Returns true if this socket is set to nonblocking mode, false otherwise.

§Notes

On Unix this corresponds to calling fcntl returning the value of O_NONBLOCK.

On Windows it is not possible retrieve the nonblocking mode status.

source

pub fn set_nonblocking(&self, nonblocking: bool) -> Result<()>

Moves this socket into or out of nonblocking mode.

§Notes

On Unix this corresponds to calling fcntl (un)setting O_NONBLOCK.

On Windows this corresponds to calling ioctlsocket (un)setting FIONBIO.

source

pub fn shutdown(&self, how: Shutdown) -> Result<()>

Shuts down the read, write, or both halves of this connection.

This function will cause all pending and future I/O on the specified portions to return immediately with an appropriate value.

Additional documentation can be found in manual of the OS:

source

pub fn recv(&self, buf: &mut [MaybeUninit<u8>]) -> Result<usize>

Receives data on the socket from the remote address to which it is connected.

The connect method will connect this socket to a remote address. This method might fail if the socket is not connected.

Additional documentation can be found in manual of the OS:

§Safety

Normally casting a &mut [u8] to &mut [MaybeUninit<u8>] would be unsound, as that allows us to write uninitialised bytes to the buffer. However this implementation promises to not write uninitialised bytes to the buffer and passes it directly to recv(2) system call. This promise ensures that this function can be called using a buffer of type &mut [u8].

Note that the io::Read::read implementation calls this function with a buffer of type &mut [u8], allowing initialised buffers to be used without using unsafe.

source

pub fn recv_out_of_band(&self, buf: &mut [MaybeUninit<u8>]) -> Result<usize>

Receives out-of-band (OOB) data on the socket from the remote address to which it is connected by setting the MSG_OOB flag for this call.

For more information, see recv, out_of_band_inline.

source

pub fn recv_with_flags( &self, buf: &mut [MaybeUninit<u8>], flags: c_int, ) -> Result<usize>

Identical to recv but allows for specification of arbitrary flags to the underlying recv call.

source

pub fn recv_vectored( &self, bufs: &mut [MaybeUninitSlice<'_>], ) -> Result<(usize, RecvFlags)>

Receives data on the socket from the remote address to which it is connected. Unlike recv this allows passing multiple buffers.

The connect method will connect this socket to a remote address. This method might fail if the socket is not connected.

In addition to the number of bytes read, this function returns the flags for the received message. See RecvFlags for more information about the returned flags.

Additional documentation can be found in manual of the OS:

§Safety

Normally casting a IoSliceMut to MaybeUninitSlice would be unsound, as that allows us to write uninitialised bytes to the buffer. However this implementation promises to not write uninitialised bytes to the bufs and passes it directly to recvmsg(2) system call. This promise ensures that this function can be called using bufs of type &mut [IoSliceMut].

Note that the io::Read::read_vectored implementation calls this function with bufs of type &mut [IoSliceMut], allowing initialised buffers to be used without using unsafe.

source

pub fn recv_vectored_with_flags( &self, bufs: &mut [MaybeUninitSlice<'_>], flags: c_int, ) -> Result<(usize, RecvFlags)>

Identical to recv_vectored but allows for specification of arbitrary flags to the underlying recvmsg/WSARecv call.

§Safety

recv_from_vectored makes the same safety guarantees regarding bufs as recv_vectored.

source

pub fn peek(&self, buf: &mut [MaybeUninit<u8>]) -> Result<usize>

Receives data on the socket from the remote adress to which it is connected, without removing that data from the queue. On success, returns the number of bytes peeked.

Successive calls return the same data. This is accomplished by passing MSG_PEEK as a flag to the underlying recv system call.

§Safety

peek makes the same safety guarantees regarding the buffer as recv.

source

pub fn recv_from( &self, buf: &mut [MaybeUninit<u8>], ) -> Result<(usize, SockAddr)>

Receives data from the socket. On success, returns the number of bytes read and the address from whence the data came.

Additional documentation can be found in manual of the OS:

§Safety

recv_from makes the same safety guarantees regarding the buffer as recv.

source

pub fn recv_from_with_flags( &self, buf: &mut [MaybeUninit<u8>], flags: c_int, ) -> Result<(usize, SockAddr)>

Identical to recv_from but allows for specification of arbitrary flags to the underlying recvfrom call.

source

pub fn recv_from_vectored( &self, bufs: &mut [MaybeUninitSlice<'_>], ) -> Result<(usize, RecvFlags, SockAddr)>

Receives data from the socket. Returns the amount of bytes read, the RecvFlags and the remote address from the data is coming. Unlike recv_from this allows passing multiple buffers.

Additional documentation can be found in manual of the OS:

§Safety

recv_from_vectored makes the same safety guarantees regarding bufs as recv_vectored.

source

pub fn recv_from_vectored_with_flags( &self, bufs: &mut [MaybeUninitSlice<'_>], flags: c_int, ) -> Result<(usize, RecvFlags, SockAddr)>

Identical to recv_from_vectored but allows for specification of arbitrary flags to the underlying recvmsg/WSARecvFrom call.

§Safety

recv_from_vectored makes the same safety guarantees regarding bufs as recv_vectored.

source

pub fn peek_from( &self, buf: &mut [MaybeUninit<u8>], ) -> Result<(usize, SockAddr)>

Receives data from the socket, without removing it from the queue.

Successive calls return the same data. This is accomplished by passing MSG_PEEK as a flag to the underlying recvfrom system call.

On success, returns the number of bytes peeked and the address from whence the data came.

§Safety

peek_from makes the same safety guarantees regarding the buffer as recv.

§Note: Datagram Sockets

For datagram sockets, the behavior of this method when buf is smaller than the datagram at the head of the receive queue differs between Windows and Unix-like platforms (Linux, macOS, BSDs, etc: colloquially termed “*nix”).

On *nix platforms, the datagram is truncated to the length of buf.

On Windows, an error corresponding to WSAEMSGSIZE will be returned.

For consistency between platforms, be sure to provide a sufficiently large buffer to avoid truncation; the exact size required depends on the underlying protocol.

If you just want to know the sender of the data, try peek_sender.

source

pub fn peek_sender(&self) -> Result<SockAddr>

Retrieve the sender for the data at the head of the receive queue.

This is equivalent to calling peek_from with a zero-sized buffer, but suppresses the WSAEMSGSIZE error on Windows.

source

pub fn recvmsg( &self, msg: &mut MsgHdrMut<'_, '_, '_>, flags: c_int, ) -> Result<usize>

Receive a message from a socket using a message structure.

This is not supported on Windows as calling WSARecvMsg (the recvmsg equivalent) is not straight forward on Windows. See https://github.com/microsoft/Windows-classic-samples/blob/7cbd99ac1d2b4a0beffbaba29ea63d024ceff700/Samples/Win7Samples/netds/winsock/recvmsg/rmmc.cpp for an example (in C++).

Additional documentation can be found in manual of the OS:

source

pub fn send(&self, buf: &[u8]) -> Result<usize>

Sends data on the socket to a connected peer.

This is typically used on TCP sockets or datagram sockets which have been connected.

On success returns the number of bytes that were sent.

Additional documentation can be found in manual of the OS:

source

pub fn send_with_flags(&self, buf: &[u8], flags: c_int) -> Result<usize>

Identical to send but allows for specification of arbitrary flags to the underlying send call.

source

pub fn send_vectored(&self, bufs: &[IoSlice<'_>]) -> Result<usize>

Send data to the connected peer. Returns the amount of bytes written.

source

pub fn send_vectored_with_flags( &self, bufs: &[IoSlice<'_>], flags: c_int, ) -> Result<usize>

Identical to send_vectored but allows for specification of arbitrary flags to the underlying sendmsg/WSASend call.

Additional documentation can be found in manual of the OS:

source

pub fn send_out_of_band(&self, buf: &[u8]) -> Result<usize>

Sends out-of-band (OOB) data on the socket to connected peer by setting the MSG_OOB flag for this call.

For more information, see send, out_of_band_inline.

source

pub fn send_to(&self, buf: &[u8], addr: &SockAddr) -> Result<usize>

Sends data on the socket to the given address. On success, returns the number of bytes written.

This is typically used on UDP or datagram-oriented sockets.

Additional documentation can be found in manual of the OS:

source

pub fn send_to_with_flags( &self, buf: &[u8], addr: &SockAddr, flags: c_int, ) -> Result<usize>

Identical to send_to but allows for specification of arbitrary flags to the underlying sendto call.

source

pub fn send_to_vectored( &self, bufs: &[IoSlice<'_>], addr: &SockAddr, ) -> Result<usize>

Send data to a peer listening on addr. Returns the amount of bytes written.

Additional documentation can be found in manual of the OS:

source

pub fn send_to_vectored_with_flags( &self, bufs: &[IoSlice<'_>], addr: &SockAddr, flags: c_int, ) -> Result<usize>

Identical to send_to_vectored but allows for specification of arbitrary flags to the underlying sendmsg/WSASendTo call.

source

pub fn sendmsg(&self, msg: &MsgHdr<'_, '_, '_>, flags: c_int) -> Result<usize>

Send a message on a socket using a message structure.

Additional documentation can be found in manual of the OS:

source

pub fn broadcast(&self) -> Result<bool>

Get the value of the SO_BROADCAST option for this socket.

For more information about this option, see set_broadcast.

source

pub fn set_broadcast(&self, broadcast: bool) -> Result<()>

Set the value of the SO_BROADCAST option for this socket.

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

source

pub fn take_error(&self) -> Result<Option<Error>>

Get the value of the SO_ERROR option on this socket.

This will retrieve the stored error in the underlying socket, clearing the field in the process. This can be useful for checking errors between calls.

source

pub fn keepalive(&self) -> Result<bool>

Get the value of the SO_KEEPALIVE option on this socket.

For more information about this option, see set_keepalive.

source

pub fn set_keepalive(&self, keepalive: bool) -> Result<()>

Set value for the SO_KEEPALIVE option on this socket.

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

source

pub fn linger(&self) -> Result<Option<Duration>>

Get the value of the SO_LINGER option on this socket.

For more information about this option, see set_linger.

source

pub fn set_linger(&self, linger: Option<Duration>) -> Result<()>

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.

source

pub fn out_of_band_inline(&self) -> Result<bool>

Get value for the SO_OOBINLINE option on this socket.

For more information about this option, see set_out_of_band_inline.

source

pub fn set_out_of_band_inline(&self, oob_inline: bool) -> Result<()>

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.

source

pub fn passcred(&self) -> Result<bool>

Get value for the SO_PASSCRED option on this socket.

For more information about this option, see set_passcred.

source

pub fn set_passcred(&self, passcred: bool) -> Result<()>

Set value for the SO_PASSCRED option on this socket.

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

source

pub fn recv_buffer_size(&self) -> Result<usize>

Get value for the SO_RCVBUF option on this socket.

For more information about this option, see set_recv_buffer_size.

source

pub fn set_recv_buffer_size(&self, size: usize) -> Result<()>

Set value for the SO_RCVBUF option on this socket.

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

source

pub fn read_timeout(&self) -> Result<Option<Duration>>

Get value for the SO_RCVTIMEO option on this socket.

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

source

pub fn set_read_timeout(&self, duration: Option<Duration>) -> Result<()>

Set value for the SO_RCVTIMEO option on this socket.

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

source

pub fn reuse_address(&self) -> Result<bool>

Get the value of the SO_REUSEADDR option on this socket.

For more information about this option, see set_reuse_address.

source

pub fn set_reuse_address(&self, reuse: bool) -> Result<()>

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.

source

pub fn send_buffer_size(&self) -> Result<usize>

Get the value of the SO_SNDBUF option on this socket.

For more information about this option, see set_send_buffer_size.

source

pub fn set_send_buffer_size(&self, size: usize) -> Result<()>

Set value for the SO_SNDBUF option on this socket.

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

source

pub fn write_timeout(&self) -> Result<Option<Duration>>

Get value for the SO_SNDTIMEO option on this socket.

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

source

pub fn set_write_timeout(&self, duration: Option<Duration>) -> Result<()>

Set value for the SO_SNDTIMEO option on this socket.

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

source

pub fn header_included(&self) -> Result<bool>

👎Deprecated: Use Socket::header_included_v4 instead

This method is deprecated, use crate::Socket::header_included_v4.

source

pub fn header_included_v4(&self) -> Result<bool>

Get the value of the IP_HDRINCL option on this socket.

For more information about this option, see set_header_included.

source

pub fn set_header_included(&self, included: bool) -> Result<()>

👎Deprecated: Use Socket::set_header_included_v4 instead

This method is deprecated, use crate::Socket::set_header_included_v4.

source

pub fn set_header_included_v4(&self, included: bool) -> Result<()>

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 SOCK_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.

source

pub fn ip_transparent(&self) -> Result<bool>

Get the value of the IP_TRANSPARENT option on this socket.

For more information about this option, see set_ip_transparent.

source

pub fn set_ip_transparent(&self, transparent: bool) -> Result<()>

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.

source

pub fn join_multicast_v4( &self, multiaddr: &Ipv4Addr, interface: &Ipv4Addr, ) -> Result<()>

Join a multicast group using IP_ADD_MEMBERSHIP option on this socket.

This function specifies a new multicast group for this socket to join. The address must be a valid multicast address, and interface is the address of the local interface with which the system should join the multicast group. If it’s Ipv4Addr::UNSPECIFIED (INADDR_ANY) then an appropriate interface is chosen by the system.

source

pub fn leave_multicast_v4( &self, multiaddr: &Ipv4Addr, interface: &Ipv4Addr, ) -> Result<()>

Leave a multicast group using IP_DROP_MEMBERSHIP option on this socket.

For more information about this option, see join_multicast_v4.

source

pub fn join_multicast_v4_n( &self, multiaddr: &Ipv4Addr, interface: &InterfaceIndexOrAddress, ) -> Result<()>

Join a multicast group using IP_ADD_MEMBERSHIP option on this socket.

This function specifies a new multicast group for this socket to join. The address must be a valid multicast address, and interface specifies the local interface with which the system should join the multicast group. See InterfaceIndexOrAddress.

source

pub fn leave_multicast_v4_n( &self, multiaddr: &Ipv4Addr, interface: &InterfaceIndexOrAddress, ) -> Result<()>

Leave a multicast group using IP_DROP_MEMBERSHIP option on this socket.

For more information about this option, see join_multicast_v4_n.

source

pub fn join_ssm_v4( &self, source: &Ipv4Addr, group: &Ipv4Addr, interface: &Ipv4Addr, ) -> Result<()>

Join a multicast SSM channel using IP_ADD_SOURCE_MEMBERSHIP option on this socket.

This function specifies a new multicast channel for this socket to join. The group must be a valid SSM group address, the source must be the address of the sender and interface is the address of the local interface with which the system should join the multicast group. If it’s Ipv4Addr::UNSPECIFIED (INADDR_ANY) then an appropriate interface is chosen by the system.

source

pub fn leave_ssm_v4( &self, source: &Ipv4Addr, group: &Ipv4Addr, interface: &Ipv4Addr, ) -> Result<()>

Leave a multicast group using IP_DROP_SOURCE_MEMBERSHIP option on this socket.

For more information about this option, see join_ssm_v4.

source

pub fn multicast_all_v4(&self) -> Result<bool>

Get the value of the IP_MULTICAST_ALL option for this socket.

For more information about this option, see set_multicast_all_v4.

source

pub fn set_multicast_all_v4(&self, all: bool) -> Result<()>

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.

source

pub fn multicast_if_v4(&self) -> Result<Ipv4Addr>

Get the value of the IP_MULTICAST_IF option for this socket.

For more information about this option, see set_multicast_if_v4.

source

pub fn set_multicast_if_v4(&self, interface: &Ipv4Addr) -> Result<()>

Set the value of the IP_MULTICAST_IF option for this socket.

Specifies the interface to use for routing multicast packets.

source

pub fn multicast_loop_v4(&self) -> Result<bool>

Get the value of the IP_MULTICAST_LOOP option for this socket.

For more information about this option, see set_multicast_loop_v4.

source

pub fn set_multicast_loop_v4(&self, loop_v4: bool) -> Result<()>

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.

source

pub fn multicast_ttl_v4(&self) -> Result<u32>

Get the value of the IP_MULTICAST_TTL option for this socket.

For more information about this option, see set_multicast_ttl_v4.

source

pub fn set_multicast_ttl_v4(&self, ttl: u32) -> Result<()>

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.

source

pub fn ttl(&self) -> Result<u32>

Get the value of the IP_TTL option for this socket.

For more information about this option, see set_ttl.

source

pub fn set_ttl(&self, ttl: u32) -> Result<()>

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.

source

pub fn set_tos(&self, tos: u32) -> Result<()>

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.

source

pub fn tos(&self) -> Result<u32>

Get the value of the IP_TOS option for this socket.

For more information about this option, see set_tos.

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

source

pub fn set_recv_tos(&self, recv_tos: bool) -> Result<()>

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.

source

pub fn recv_tos(&self) -> Result<bool>

Get the value of the IP_RECVTOS option for this socket.

For more information about this option, see set_recv_tos.

source

pub fn header_included_v6(&self) -> Result<bool>

Get the value of the IP_HDRINCL option on this socket.

For more information about this option, see set_header_included.

source

pub fn set_header_included_v6(&self, included: bool) -> Result<()>

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 SOCK_RAW sockets; see raw(7) for more information. When this flag is enabled, the values set by IP_OPTIONS are ignored.

source

pub fn join_multicast_v6( &self, multiaddr: &Ipv6Addr, interface: u32, ) -> Result<()>

Join a multicast group using IPV6_ADD_MEMBERSHIP option on this socket.

Some OSs use IPV6_JOIN_GROUP for this option.

This function specifies a new multicast group for this socket to join. The address must be a valid multicast address, and interface is the index of the interface to join/leave (or 0 to indicate any interface).

source

pub fn leave_multicast_v6( &self, multiaddr: &Ipv6Addr, interface: u32, ) -> Result<()>

Leave a multicast group using IPV6_DROP_MEMBERSHIP option on this socket.

Some OSs use IPV6_LEAVE_GROUP for this option.

For more information about this option, see join_multicast_v6.

source

pub fn multicast_hops_v6(&self) -> Result<u32>

Get the value of the IPV6_MULTICAST_HOPS option for this socket

For more information about this option, see set_multicast_hops_v6.

source

pub fn set_multicast_hops_v6(&self, hops: u32) -> Result<()>

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.

source

pub fn multicast_all_v6(&self) -> Result<bool>

Get the value of the IPV6_MULTICAST_ALL option for this socket.

For more information about this option, see set_multicast_all_v6.

source

pub fn set_multicast_all_v6(&self, all: bool) -> Result<()>

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.

source

pub fn multicast_if_v6(&self) -> Result<u32>

Get the value of the IPV6_MULTICAST_IF option for this socket.

For more information about this option, see set_multicast_if_v6.

source

pub fn set_multicast_if_v6(&self, interface: u32) -> Result<()>

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.

source

pub fn multicast_loop_v6(&self) -> Result<bool>

Get the value of the IPV6_MULTICAST_LOOP option for this socket.

For more information about this option, see set_multicast_loop_v6.

source

pub fn set_multicast_loop_v6(&self, loop_v6: bool) -> Result<()>

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.

source

pub fn unicast_hops_v6(&self) -> Result<u32>

Get the value of the IPV6_UNICAST_HOPS option for this socket.

Specifies the hop limit for ipv6 unicast packets

source

pub fn set_unicast_hops_v6(&self, hops: u32) -> Result<()>

Set the value for the IPV6_UNICAST_HOPS option on this socket.

Specifies the hop limit for ipv6 unicast packets

source

pub fn only_v6(&self) -> Result<bool>

Get the value of the IPV6_V6ONLY option for this socket.

For more information about this option, see set_only_v6.

source

pub fn set_only_v6(&self, only_v6: bool) -> Result<()>

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.

source

pub fn recv_tclass_v6(&self) -> Result<bool>

Get the value of the IPV6_RECVTCLASS option for this socket.

For more information about this option, see set_recv_tclass_v6.

source

pub fn set_recv_tclass_v6(&self, recv_tclass: bool) -> Result<()>

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.

source

pub fn keepalive_time(&self) -> Result<Duration>

Get the value of the TCP_KEEPIDLE option on this socket.

This returns the value of TCP_KEEPALIVE on macOS and iOS and TCP_KEEPIDLE on all other supported Unix operating systems.

source

pub fn keepalive_interval(&self) -> Result<Duration>

Get the value of the TCP_KEEPINTVL option on this socket.

For more information about this option, see set_tcp_keepalive.

source

pub fn keepalive_retries(&self) -> Result<u32>

Get the value of the TCP_KEEPCNT option on this socket.

For more information about this option, see set_tcp_keepalive.

source

pub fn set_tcp_keepalive(&self, params: &TcpKeepalive) -> Result<()>

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.
§Examples
use std::time::Duration;

use socket2::{Socket, TcpKeepalive, Domain, Type};

let socket = Socket::new(Domain::IPV4, Type::STREAM, None)?;
let keepalive = TcpKeepalive::new()
    .with_time(Duration::from_secs(4));
    // Depending on the target operating system, we may also be able to
    // configure the keepalive probe interval and/or the number of
    // retries here as well.

socket.set_tcp_keepalive(&keepalive)?;
source

pub fn nodelay(&self) -> Result<bool>

Get the value of the TCP_NODELAY option on this socket.

For more information about this option, see set_nodelay.

source

pub fn set_nodelay(&self, nodelay: bool) -> Result<()>

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.

source

pub fn original_dst(&self) -> Result<SockAddr>

Get the value for the SO_ORIGINAL_DST option on this socket.

source

pub fn original_dst_ipv6(&self) -> Result<SockAddr>

Get the value for the IP6T_SO_ORIGINAL_DST option on this socket.

source

pub fn accept4(&self, flags: c_int) -> Result<(Socket, SockAddr)>

Accept a new incoming connection from this listener.

This function directly corresponds to the accept4(2) function.

This function will block the calling thread until a new connection is established. When established, the corresponding Socket and the remote peer’s address will be returned.

Additional documentation can be found in manual of the OS:

source

pub(crate) fn _accept4(&self, flags: c_int) -> Result<(Socket, SockAddr)>

source

pub fn set_cloexec(&self, close_on_exec: bool) -> Result<()>

Sets CLOEXEC on the socket.

§Notes

On supported platforms you can use Type::cloexec.

source

pub(crate) fn _set_cloexec(&self, close_on_exec: bool) -> Result<()>

source

pub fn mss(&self) -> Result<u32>

Gets the value of the TCP_MAXSEG option on this socket.

For more information about this option, see set_mss.

source

pub fn set_mss(&self, mss: u32) -> Result<()>

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.

source

pub fn is_listener(&self) -> Result<bool>

Returns true if listen(2) was called on this socket by checking the SO_ACCEPTCONN option on this socket.

source

pub fn domain(&self) -> Result<Domain>

Returns the Domain of this socket by checking the SO_DOMAIN option on this socket.

source

pub fn protocol(&self) -> Result<Option<Protocol>>

Returns the Protocol of this socket by checking the SO_PROTOCOL option on this socket.

source

pub fn mark(&self) -> Result<u32>

Gets the value for the SO_MARK option on this socket.

This value gets the socket mark field for each packet sent through this socket.

On Linux this function requires the CAP_NET_ADMIN capability.

source

pub fn set_mark(&self, mark: u32) -> Result<()>

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.

source

pub fn cork(&self) -> Result<bool>

Get the value of the TCP_CORK option on this socket.

For more information about this option, see set_cork.

source

pub fn set_cork(&self, cork: bool) -> Result<()>

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.

source

pub fn quickack(&self) -> Result<bool>

Get the value of the TCP_QUICKACK option on this socket.

For more information about this option, see set_quickack.

source

pub fn set_quickack(&self, quickack: bool) -> Result<()>

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.

source

pub fn thin_linear_timeouts(&self) -> Result<bool>

Get the value of the TCP_THIN_LINEAR_TIMEOUTS option on this socket.

For more information about this option, see set_thin_linear_timeouts.

source

pub fn set_thin_linear_timeouts(&self, timeouts: bool) -> Result<()>

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.

source

pub fn device(&self) -> Result<Option<Vec<u8>>>

Gets the value for the SO_BINDTODEVICE option on this socket.

This value gets the socket binded device’s interface name.

source

pub fn bind_device(&self, interface: Option<&[u8]>) -> Result<()>

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 AF_INET sockets.

If interface is None or an empty string it removes the binding.

source

pub fn cpu_affinity(&self) -> Result<usize>

Get the value of the SO_INCOMING_CPU option on this socket.

For more information about this option, see set_cpu_affinity.

source

pub fn set_cpu_affinity(&self, cpu: usize) -> Result<()>

Set value for the SO_INCOMING_CPU option on this socket.

Sets the CPU affinity of the socket.

source

pub fn reuse_port(&self) -> Result<bool>

Get the value of the SO_REUSEPORT option on this socket.

For more information about this option, see set_reuse_port.

source

pub fn set_reuse_port(&self, reuse: bool) -> Result<()>

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.

source

pub fn freebind(&self) -> Result<bool>

Get the value of the IP_FREEBIND option on this socket.

For more information about this option, see set_freebind.

source

pub fn set_freebind(&self, freebind: bool) -> Result<()>

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.

source

pub fn freebind_ipv6(&self) -> Result<bool>

Get the value of 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.

source

pub fn set_freebind_ipv6(&self, freebind: bool) -> Result<()>

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.

§Examples

On Linux:

use socket2::{Domain, Socket, Type};
use std::io::{self, Error, ErrorKind};

fn enable_freebind(socket: &Socket) -> io::Result<()> {
    match socket.domain()? {
        Domain::IPV4 => socket.set_freebind(true)?,
        Domain::IPV6 => socket.set_freebind_ipv6(true)?,
        _ => return Err(Error::new(ErrorKind::Other, "unsupported domain")),
    };
    Ok(())
}
source

pub fn sendfile<F>( &self, file: &F, offset: usize, length: Option<NonZeroUsize>, ) -> Result<usize>
where F: AsRawFd,

Copies data between a file and this socket using the sendfile(2) system call. Because this copying is done within the kernel, sendfile() is more efficient than the combination of read(2) and write(2), which would require transferring data to and from user space.

Different OSs support different kinds of files, see the OS documentation for what kind of files are supported. Generally regular files are supported by all OSs.

Additional documentation can be found in manual of the OS:

The offset is the absolute offset into the file to use as starting point.

Depending on the OS this function may change the offset of file. For the best results reset the offset of the file before using it again.

The length determines how many bytes to send, where a length of None means it will try to send all bytes.

source

fn _sendfile( &self, file: RawFd, offset: off_t, length: Option<NonZeroUsize>, ) -> Result<usize>

source

pub fn set_tcp_user_timeout(&self, timeout: Option<Duration>) -> Result<()>

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.

source

pub fn tcp_user_timeout(&self) -> Result<Option<Duration>>

Get the value of the TCP_USER_TIMEOUT option on this socket.

For more information about this option, see set_tcp_user_timeout.

source

pub fn attach_filter(&self, filters: &[sock_filter]) -> Result<()>

Attach Berkeley Packet Filter(BPF) on this socket.

BPF allows a user-space program to attach a filter onto any socket and allow or disallow certain types of data to come through the socket.

For more information about this option, see filter

source

pub fn detach_filter(&self) -> Result<()>

Detach Berkeley Packet Filter(BPF) from this socket.

For more information about this option, see attach_filter

source

pub fn cookie(&self) -> Result<u64>

Gets the value for the SO_COOKIE option on this socket.

The socket cookie is a unique, kernel-managed identifier tied to each socket. Therefore, there is no corresponding set helper.

For more information about this option, see Linux patch

source

pub fn tclass_v6(&self) -> Result<u32>

Get the value of the IPV6_TCLASS option for this socket.

For more information about this option, see set_tclass_v6.

source

pub fn set_tclass_v6(&self, tclass: u32) -> Result<()>

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.

source

pub fn tcp_congestion(&self) -> Result<Vec<u8>>

Get the value of the TCP_CONGESTION option for this socket.

For more information about this option, see set_tcp_congestion.

source

pub fn set_tcp_congestion(&self, tcp_ca_name: &[u8]) -> Result<()>

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”.

source

pub fn set_dccp_service(&self, code: u32) -> Result<()>

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

source

pub fn dccp_service(&self) -> Result<u32>

Get the value of the DCCP_SOCKOPT_SERVICE option on this socket.

For more information about this option see set_dccp_service

source

pub fn set_dccp_ccid(&self, ccid: u8) -> Result<()>

Set value for the DCCP_SOCKOPT_CCID option on this socket.

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

source

pub fn dccp_tx_ccid(&self) -> Result<u32>

Get the value of the DCCP_SOCKOPT_TX_CCID option on this socket.

For more information about this option see set_dccp_ccid.

source

pub fn dccp_xx_ccid(&self) -> Result<u32>

Get the value of the DCCP_SOCKOPT_RX_CCID option on this socket.

For more information about this option see set_dccp_ccid.

source

pub fn set_dccp_server_timewait(&self, hold_timewait: bool) -> Result<()>

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.

source

pub fn dccp_server_timewait(&self) -> Result<bool>

Get the value of the DCCP_SOCKOPT_SERVER_TIMEWAIT option on this socket.

For more information see set_dccp_server_timewait

source

pub fn set_dccp_send_cscov(&self, level: u32) -> Result<()>

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.

source

pub fn dccp_send_cscov(&self) -> Result<u32>

Get the value of the DCCP_SOCKOPT_SEND_CSCOV option on this socket.

For more information on this option see set_dccp_send_cscov.

source

pub fn set_dccp_recv_cscov(&self, level: u32) -> Result<()>

Set the value of the DCCP_SOCKOPT_RECV_CSCOV option on this socket.

This option is only useful when combined with set_dccp_send_cscov.

source

pub fn dccp_recv_cscov(&self) -> Result<u32>

Get the value of the DCCP_SOCKOPT_RECV_CSCOV option on this socket.

For more information on this option see set_dccp_recv_cscov.

source

pub fn set_dccp_qpolicy_txqlen(&self, length: u32) -> Result<()>

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.

source

pub fn dccp_qpolicy_txqlen(&self) -> Result<u32>

Get the value of the DCCP_SOCKOPT_QPOLICY_TXQLEN on this socket.

For more information on this option see set_dccp_qpolicy_txqlen.

source

pub fn dccp_available_ccids<const N: usize>(&self) -> Result<CcidEndpoints<N>>

Get the value of the DCCP_SOCKOPT_AVAILABLE_CCIDS option on this socket.

Returns the list of CCIDs supported by the endpoint.

The parameter N is used to get the maximum number of supported endpoints. The documentation recommends a minimum of four at the time of writing.

source

pub fn dccp_cur_mps(&self) -> Result<u32>

Get the value of the DCCP_SOCKOPT_GET_CUR_MPS option on this socket.

This option retrieves the current maximum packet size (application payload size) in bytes.

Trait Implementations§

source§

impl Debug for SockRef<'_>

source§

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter. Read more
source§

impl<'s> Deref for SockRef<'s>

source§

type Target = Socket

The resulting type after dereferencing.
source§

fn deref(&self) -> &Self::Target

Dereferences the value.
source§

impl<'s, S> From<&'s S> for SockRef<'s>
where S: AsFd,

On Windows, a corresponding From<&impl AsSocket> implementation exists.

source§

fn from(socket: &'s S) -> Self

The caller must ensure S is actually a socket.

Auto Trait Implementations§

§

impl<'s> Freeze for SockRef<'s>

§

impl<'s> RefUnwindSafe for SockRef<'s>

§

impl<'s> Send for SockRef<'s>

§

impl<'s> Sync for SockRef<'s>

§

impl<'s> Unpin for SockRef<'s>

§

impl<'s> UnwindSafe for SockRef<'s>

Blanket Implementations§

source§

impl<T> Any for T
where T: 'static + ?Sized,

source§

fn type_id(&self) -> TypeId

Gets the TypeId of self. Read more
source§

impl<T> Borrow<T> for T
where T: ?Sized,

source§

fn borrow(&self) -> &T

Immutably borrows from an owned value. Read more
source§

impl<T> BorrowMut<T> for T
where T: ?Sized,

source§

fn borrow_mut(&mut self) -> &mut T

Mutably borrows from an owned value. Read more
source§

impl<T> From<T> for T

source§

fn from(t: T) -> T

Returns the argument unchanged.

source§

impl<T, U> Into<U> for T
where U: From<T>,

source§

fn into(self) -> U

Calls U::from(self).

That is, this conversion is whatever the implementation of From<T> for U chooses to do.

source§

impl<T, U> TryFrom<U> for T
where U: Into<T>,

source§

type Error = Infallible

The type returned in the event of a conversion error.
source§

fn try_from(value: U) -> Result<T, <T as TryFrom<U>>::Error>

Performs the conversion.
source§

impl<T, U> TryInto<U> for T
where U: TryFrom<T>,

source§

type Error = <U as TryFrom<T>>::Error

The type returned in the event of a conversion error.
source§

fn try_into(self) -> Result<U, <U as TryFrom<T>>::Error>

Performs the conversion.