socket2 Rust Documentation

Socket2 is a Rust crate designed to provide utilities for creating and using sockets with advanced configuration options that are unavailable in the Rust standard library.

Key Characteristics:

• Direct System Access: It provides as direct as possible access to system socket functionality, meaning it offers maximal flexibility but minimal cross-platform abstraction.
• No Unsafe Code: The crate aims to provide these advanced options without requiring the user to write unsafe code.
• Low-Level Design: Most functions map directly to equivalent system calls. Because of this, the crate does not apply high-level error handling (e.g., it does not automatically handle EINTR).

Warning: This crate is intended for users who already understand how to create and manage sockets using libc or system calls. If you are unfamiliar with low-level socket programming, this crate may be too complex for your needs.

The SockRef type provides a way to use the advanced configuration methods of the socket2::Socket API on socket types owned by other libraries, such as std::net::TcpStream or std::net::TcpListener.

Because SockRef is a reference, it does not take ownership of the underlying socket. It uses ManuallyDrop internally to ensure that when the SockRef is dropped, the underlying socket is not closed, allowing the original owner (e.g., the TcpStream) to continue using it.

Platform Support

• Unix/WASI: Works with any type implementing std::os::fd::AsFd.
• Windows: Works with any type implementing std::os::windows::io::AsSocket.

Usage Pattern

1. Create a socket using the standard library (e.g., TcpStream::connect).
2. Create a SockRef using SockRef::from(&socket).
3. Call socket2 methods (like set_tcp_nodelay) via the SockRef instance.
4. The SockRef implements Deref, so it behaves like a Socket reference.

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

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

// Create a `SockRef`erence to the stream.
let socket_ref = SockRef::from(&stream);

// Use `Socket` methods on the standard library stream via the reference.
socket_ref.set_tcp_nodelay(true).unwrap();

// The original stream is still valid and reflects the changes.
assert_eq!(stream.nodelay().unwrap(), true);

The Socket type is an owned wrapper around a system socket (a file descriptor on Unix or a SOCKET on Windows). It is the primary type in socket2 and is designed to mirror raw OS socket semantics closely.

Key Capabilities:

• Creation: Create sockets with specific Domain, Type, and Protocol using Socket::new (which sets common flags like close-on-exec) or Socket::new_raw (for no automatic configuration).
• Conversion: You can convert a Socket into standard library network primitives like std::net::TcpStream or std::net::UdpSocket using the From trait.
• Lifecycle: Manage connections via bind, connect, listen, and accept. It also supports connect_timeout for establishing connections with a specific duration.
• I/O: Perform low-level I/O operations including recv, send, recv_from, send_to, and vectored I/O (recv_vectored, send_vectored).
• Non-blocking mode: Toggle between blocking and non-blocking modes using set_nonblocking.

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

// create a TCP listener
let socket = Socket::new(Domain::IPV6, Type::STREAM, None)?;

let address: SocketAddr = "[::1]:12345".parse().unwrap();
let address = address.into();
socket.bind(&address)?;
socket.listen(128)?;

let listener: TcpListener = socket.into();

The Socket type provides direct access to system socket functionality. You can create a new socket using Socket::new by specifying a Domain, Type, and an optional Protocol. Once created, you can configure advanced options (like TCP keepalive or binding to specific addresses) and eventually convert the Socket into standard library types like TcpListener or TcpStream using into().

Note: This crate provides minimal error handling (it does not handle EINTR) and is intended for users who understand system calls.

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

// Create a TCP listener bound to two addresses.
let socket = Socket::new(Domain::IPV6, Type::STREAM, None)?;

socket.set_only_v6(false)?;
let address: SocketAddr = "[::1]:12345".parse().unwrap();
socket.bind(&address.into())?;
socket.listen(128)?;

let listener: TcpListener = socket.into();