Struct socket2::Socket

pub struct Socket { /* fields omitted */ }

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();
// ...

Methods

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 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 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_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 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 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 reuse_port(&self) -> Result<bool>

Check the value of the SO_REUSEPORT option on this socket.

This function is only available on Unix when the reuseport feature is enabled.

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

Set value for the SO_REUSEPORT 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.

This function is only available on Unix when the reuseport feature is enabled.

Trait Implementations

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.

unsafe fn initializer(&self) -> Initializer

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

Determines if this Reader can work with buffers of uninitialized memory.

fn read_to_end(&mut self, buf: &mut Vec<u8>) -> 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 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 chars(self) -> Chars<Self>

Deprecated since 1.27.0

: Use str::from_utf8 instead: https://doc.rust-lang.org/nightly/std/str/struct.Utf8Error.html#examples

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

the semantics of a partial read/write of where errors happen is currently unclear and may change

Transforms this Read instance to an [Iterator] over [char]s.

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

Creates an adaptor which will chain this stream with another.

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

Creates an adaptor 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.

unsafe fn initializer(&self) -> Initializer

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

Determines if this Reader can work with buffers of uninitialized memory.

fn read_to_end(&mut self, buf: &mut Vec<u8>) -> 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 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 chars(self) -> Chars<Self>

Deprecated since 1.27.0

: Use str::from_utf8 instead: https://doc.rust-lang.org/nightly/std/str/struct.Utf8Error.html#examples

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

the semantics of a partial read/write of where errors happen is currently unclear and may change

Transforms this Read instance to an [Iterator] over [char]s.

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

Creates an adaptor which will chain this stream with another.

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

Creates an adaptor 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 object, 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_all(&mut self, buf: &[u8]) -> Result<(), Error>

Attempts to write an entire buffer into this write.

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" adaptor for this instance of Write.

impl<'a> Write for &'a Socket

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

Write a buffer into this object, 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_all(&mut self, buf: &[u8]) -> Result<(), Error>

Attempts to write an entire buffer into this write.

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" adaptor for this instance of Write.

impl Debug for Socket

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

Formats the value using the given formatter.

impl From<TcpStream> for Socket

Important traits for Socket

impl Read for Socketimpl<'a> Read for &'a Socketimpl Write for Socketimpl<'a> Write for &'a Socket

fn from(socket: TcpStream) -> Socket

Performs the conversion.

impl From<TcpListener> for Socket

Important traits for Socket

impl Read for Socketimpl<'a> Read for &'a Socketimpl Write for Socketimpl<'a> Write for &'a Socket

fn from(socket: TcpListener) -> Socket

Performs the conversion.

impl From<UdpSocket> for Socket

Important traits for Socket

impl Read for Socketimpl<'a> Read for &'a Socketimpl Write for Socketimpl<'a> Write for &'a Socket

fn from(socket: UdpSocket) -> Socket

Performs the conversion.

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 AsRawFd for Socket

fn as_raw_fd(&self) -> c_int

Extracts the raw file descriptor.

impl IntoRawFd for Socket

fn into_raw_fd(self) -> c_int

Consumes this object, returning the raw underlying file descriptor.

impl FromRawFd for Socket

Important traits for Socket

impl Read for Socketimpl<'a> Read for &'a Socketimpl Write for Socketimpl<'a> Write for &'a Socket

unsafe fn from_raw_fd(fd: c_int) -> Socket

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