Struct socket2::Socket

pub struct Socket { /* private fields */ }

Newtype, owned, wrapper around a system socket.

This type simply wraps an instance of a file descriptor (c_int) on Unix and an instance of SOCKET on Windows. This is the main type exported by this crate and is intended to mirror the raw semantics of sockets on platforms as closely as possible. Almost all methods correspond to precisely one libc or OS API call which is essentially just a “Rustic translation” of what’s below.

Examples

use std::net::SocketAddr;
use socket2::{Socket, Domain, Type, SockAddr};

// create a TCP listener bound to two addresses
let socket = Socket::new(Domain::ipv4(), Type::stream(), None).unwrap();

socket.bind(&"127.0.0.1:12345".parse::<SocketAddr>().unwrap().into()).unwrap();
socket.bind(&"127.0.0.1:12346".parse::<SocketAddr>().unwrap().into()).unwrap();
socket.listen(128).unwrap();

let listener = socket.into_tcp_listener();
// ...

Implementations

impl Socket

pub fn new(
    domain: Domain,
    type_: Type,
    protocol: Option<Protocol>
) -> Result<Socket>

Creates a new socket ready to be configured.

This function corresponds to socket(2) and simply creates a new socket, no other configuration is done and further functions must be invoked to configure this socket.

pub fn into_tcp_stream(self) -> TcpStream

Consumes this Socket, converting it to a TcpStream.

pub fn into_tcp_listener(self) -> TcpListener

Consumes this Socket, converting it to a TcpListener.

pub fn into_udp_socket(self) -> UdpSocket

Consumes this Socket, converting it to a UdpSocket.

pub fn connect(&self, addr: &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.

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

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

Binds this socket to the specified address.

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

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

Mark a socket as ready to accept incoming connection requests using 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.

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

Accept a new incoming connection from this listener.

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.

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

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

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

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

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

Creates a new independently owned handle to the underlying socket.

The returned TcpStream is a reference to the same stream that this object references. Both handles will read and write the same stream of data, and options set on one stream will be propagated to the other stream.

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.

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

Moves this TCP stream into or out of nonblocking mode.

On Unix this corresponds to calling fcntl, and on Windows this corresponds to calling ioctlsocket.

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.

pub fn recv(&self, buf: &mut [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 will fail if the socket is not connected.

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

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

pub fn recv_out_of_band(&self, buf: &mut [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.

pub fn peek(&self, buf: &mut [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.

pub fn recv_from(&self, buf: &mut [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.

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

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

pub fn peek_from(&self, buf: &mut [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.

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.

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

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

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.

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. On success returns the number of bytes that were sent.

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

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

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

Gets the value of the IP_TTL option for this socket.

For more information about this option, see set_ttl.

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

Sets the value for the IP_TTL option on this socket.

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

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

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

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.

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.

This function is only available on Linux and requires the CAP_NET_ADMIN capability.

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.

This function is only available on Linux and requires the CAP_NET_ADMIN capability.

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

Gets the value for the SO_BINDTODEVICE option on this socket.

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

This function is only available on Linux.

pub fn bind_device(&self, interface: Option<&CStr>) -> 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.

This function is only available on Linux.

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

Gets the value of the IPV6_UNICAST_HOPS option for this socket.

Specifies the hop limit for ipv6 unicast packets

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

Sets the value for the IPV6_UNICAST_HOPS option on this socket.

Specifies the hop limit for ipv6 unicast packets

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

Gets the value of the IPV6_V6ONLY option for this socket.

For more information about this option, see set_only_v6.

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

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

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

Returns the read timeout of this socket.

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

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

Sets the read timeout to the timeout specified.

If the value specified is None, then read calls will block indefinitely. It is an error to pass the zero Duration to this method.

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

Returns the write timeout of this socket.

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

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

Sets the write timeout to the timeout specified.

If the value specified is None, then write calls will block indefinitely. It is an error to pass the zero Duration to this method.

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

Gets the value of the TCP_NODELAY option on this socket.

For more information about this option, see set_nodelay.

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

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

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

Sets the value of the SO_BROADCAST option for this socket.

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

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

Gets the value of the SO_BROADCAST option for this socket.

For more information about this option, see set_broadcast.

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

Gets the value of the IP_MULTICAST_LOOP option for this socket.

For more information about this option, see set_multicast_loop_v4.

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

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

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

Gets the value of the IP_MULTICAST_TTL option for this socket.

For more information about this option, see set_multicast_ttl_v4.

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

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

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

Gets the value of the IPV6_MULTICAST_HOPS option for this socket

For more information about this option, see set_multicast_hops_v6.

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

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

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

Gets the value of the IP_MULTICAST_IF option for this socket.

For more information about this option, see set_multicast_if_v4.

Returns the interface to use for routing multicast packets.

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

Sets the value of the IP_MULTICAST_IF option for this socket.

Specifies the interface to use for routing multicast packets.

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

Gets the value of the IPV6_MULTICAST_IF option for this socket.

For more information about this option, see set_multicast_if_v6.

Returns the interface to use for routing multicast packets.

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

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

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

Gets the value of the IPV6_MULTICAST_LOOP option for this socket.

For more information about this option, see set_multicast_loop_v6.

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

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

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

Executes an operation of the IP_ADD_MEMBERSHIP type.

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 equal to INADDR_ANY then an appropriate interface is chosen by the system.

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

Executes an operation of the IPV6_ADD_MEMBERSHIP type.

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

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

Executes an operation of the IP_DROP_MEMBERSHIP type.

For more information about this option, see join_multicast_v4.

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

Executes an operation of the IPV6_DROP_MEMBERSHIP type.

For more information about this option, see join_multicast_v6.

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

Reads the linger duration for this socket by getting the SO_LINGER option

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

Sets the linger duration of this socket by setting the SO_LINGER option

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

Check the SO_REUSEADDR option on this socket.

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

Set value for the SO_REUSEADDR option on this socket.

This indicates that futher 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.

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

Gets the value of the SO_RCVBUF option on this socket.

For more information about this option, see set_recv_buffer_size.

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

Sets the value of the SO_RCVBUF option on this socket.

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

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

Gets the value of the SO_SNDBUF option on this socket.

For more information about this option, see set_send_buffer.

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

Sets the value of the SO_SNDBUF option on this socket.

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

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

Returns whether keepalive messages are enabled on this socket, and if so the duration of time between them.

For more information about this option, see set_keepalive.

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

Sets whether keepalive messages are enabled to be sent on this socket.

On Unix, this option will set the SO_KEEPALIVE as well as the TCP_KEEPALIVE or TCP_KEEPIDLE option (depending on your platform). On Windows, this will set the SIO_KEEPALIVE_VALS option.

If None is specified then keepalive messages are disabled, otherwise the duration specified will be the time to remain idle before sending a TCP keepalive probe.

Some platforms specify this value in seconds, so sub-second specifications may be omitted.

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

Returns the value of the SO_OOBINLINE flag of the underlying socket. For more information about this option, see set_out_of_band_inline.

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

Sets the SO_OOBINLINE flag of the underlying socket. as per RFC6093, TCP sockets using the Urgent mechanism are encouraged to set this flag.

If this flag is not set, the MSG_OOB flag is needed while recving to aquire the out-of-band data.

Trait Implementations

impl AsRawFd for Socket

fn as_raw_fd(&self) -> c_int

Extracts the raw file descriptor.

impl Debug for Socket

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

Formats the value using the given formatter.

impl From<Socket> for TcpStream

fn from(socket: Socket) -> TcpStream

Performs the conversion.

impl From<Socket> for TcpListener

fn from(socket: Socket) -> TcpListener

Performs the conversion.

impl From<Socket> for UdpSocket

fn from(socket: Socket) -> UdpSocket

Performs the conversion.

impl From<TcpListener> for Socket

fn from(socket: TcpListener) -> Socket

Performs the conversion.

impl From<TcpStream> for Socket

fn from(socket: TcpStream) -> Socket

Performs the conversion.

impl From<UdpSocket> for Socket

fn from(socket: UdpSocket) -> Socket

Performs the conversion.

impl FromRawFd for Socket

unsafe fn from_raw_fd(fd: c_int) -> Socket

Constructs a new instance of Self from the given raw file descriptor.

impl IntoRawFd for Socket

fn into_raw_fd(self) -> c_int

Consumes this object, returning the raw underlying file descriptor.

impl Read for Socket

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

Pull some bytes from this source into the specified buffer, returning how many bytes were read.

fn read_vectored(&mut self, bufs: &mut [IoSliceMut<'_>]) -> Result<usize, Error>

Like read, except that it reads into a slice of buffers.

fn is_read_vectored(&self) -> bool

🔬 This is a nightly-only experimental API. (can_vector)

Determines if this Reader has an efficient read_vectored implementation.

fn read_to_end(&mut self, buf: &mut Vec<u8, Global>) -> Result<usize, Error>

Read all bytes until EOF in this source, placing them into buf.

fn read_to_string(&mut self, buf: &mut String) -> Result<usize, Error>

Read all bytes until EOF in this source, appending them to buf.

fn read_exact(&mut self, buf: &mut [u8]) -> Result<(), Error>

Read the exact number of bytes required to fill buf.

fn read_buf(&mut self, buf: &mut ReadBuf<'_>) -> Result<(), Error>

🔬 This is a nightly-only experimental API. (read_buf)

Pull some bytes from this source into the specified buffer.

fn read_buf_exact(&mut self, buf: &mut ReadBuf<'_>) -> Result<(), Error>

🔬 This is a nightly-only experimental API. (read_buf)

Read the exact number of bytes required to fill buf.

fn by_ref(&mut self) -> &mut Self

Creates a “by reference” adaptor for this instance of Read.

fn bytes(self) -> Bytes<Self>

Transforms this Read instance to an Iterator over its bytes.

fn chain<R>(self, next: R) -> Chain<Self, R> where
    R: Read, 

Creates an adapter which will chain this stream with another.

fn take(self, limit: u64) -> Take<Self>

Creates an adapter which will read at most limit bytes from it.

impl<'a> Read for &'a Socket

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

Pull some bytes from this source into the specified buffer, returning how many bytes were read.

fn read_vectored(&mut self, bufs: &mut [IoSliceMut<'_>]) -> Result<usize, Error>

Like read, except that it reads into a slice of buffers.

fn is_read_vectored(&self) -> bool

🔬 This is a nightly-only experimental API. (can_vector)

Determines if this Reader has an efficient read_vectored implementation.

fn read_to_end(&mut self, buf: &mut Vec<u8, Global>) -> Result<usize, Error>

Read all bytes until EOF in this source, placing them into buf.

fn read_to_string(&mut self, buf: &mut String) -> Result<usize, Error>

Read all bytes until EOF in this source, appending them to buf.

fn read_exact(&mut self, buf: &mut [u8]) -> Result<(), Error>

Read the exact number of bytes required to fill buf.

fn read_buf(&mut self, buf: &mut ReadBuf<'_>) -> Result<(), Error>

🔬 This is a nightly-only experimental API. (read_buf)

Pull some bytes from this source into the specified buffer.

fn read_buf_exact(&mut self, buf: &mut ReadBuf<'_>) -> Result<(), Error>

🔬 This is a nightly-only experimental API. (read_buf)

Read the exact number of bytes required to fill buf.

fn by_ref(&mut self) -> &mut Self

Creates a “by reference” adaptor for this instance of Read.

fn bytes(self) -> Bytes<Self>

Transforms this Read instance to an Iterator over its bytes.

fn chain<R>(self, next: R) -> Chain<Self, R> where
    R: Read, 

Creates an adapter which will chain this stream with another.

fn take(self, limit: u64) -> Take<Self>

Creates an adapter which will read at most limit bytes from it.

impl Write for Socket

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

Write a buffer into this writer, returning how many bytes were written.

fn flush(&mut self) -> Result<()>

Flush this output stream, ensuring that all intermediately buffered contents reach their destination.

fn write_vectored(&mut self, bufs: &[IoSlice<'_>]) -> Result<usize, Error>

Like write, except that it writes from a slice of buffers.

fn is_write_vectored(&self) -> bool

🔬 This is a nightly-only experimental API. (can_vector)

Determines if this Writer has an efficient write_vectored implementation.

fn write_all(&mut self, buf: &[u8]) -> Result<(), Error>

Attempts to write an entire buffer into this writer.

fn write_all_vectored(&mut self, bufs: &mut [IoSlice<'_>]) -> Result<(), Error>

🔬 This is a nightly-only experimental API. (write_all_vectored)

Attempts to write multiple buffers into this writer.

fn write_fmt(&mut self, fmt: Arguments<'_>) -> Result<(), Error>

Writes a formatted string into this writer, returning any error encountered.

fn by_ref(&mut self) -> &mut Self

Creates a “by reference” adapter for this instance of Write.

impl<'a> Write for &'a Socket

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

Write a buffer into this writer, returning how many bytes were written.

fn flush(&mut self) -> Result<()>

Flush this output stream, ensuring that all intermediately buffered contents reach their destination.

fn write_vectored(&mut self, bufs: &[IoSlice<'_>]) -> Result<usize, Error>

Like write, except that it writes from a slice of buffers.

fn is_write_vectored(&self) -> bool

🔬 This is a nightly-only experimental API. (can_vector)

Determines if this Writer has an efficient write_vectored implementation.

fn write_all(&mut self, buf: &[u8]) -> Result<(), Error>

Attempts to write an entire buffer into this writer.

fn write_all_vectored(&mut self, bufs: &mut [IoSlice<'_>]) -> Result<(), Error>

🔬 This is a nightly-only experimental API. (write_all_vectored)

Attempts to write multiple buffers into this writer.

fn write_fmt(&mut self, fmt: Arguments<'_>) -> Result<(), Error>

Writes a formatted string into this writer, returning any error encountered.

fn by_ref(&mut self) -> &mut Self

Creates a “by reference” adapter for this instance of Write.