rama::net::socket::core

Struct SockAddr

pub struct SockAddr { /* private fields */ }

Expand description

The address of a socket.

SockAddrs may be constructed directly to and from the standard library SocketAddr, SocketAddrV4, and SocketAddrV6 types.

Implementations§

§

impl SockAddr

pub const unsafe fn new(storage: SockAddrStorage, len: u32) -> SockAddr

Create a SockAddr from the underlying storage and its length.

§Safety

Caller must ensure that the address family and length match the type of storage address. For example if storage.ss_family is set to AF_INET the storage must be initialised as sockaddr_in, setting the content and length appropriately.

§Examples

use std::io;
use std::os::fd::AsRawFd;

use socket2::{SockAddr, SockAddrStorage, Socket, Domain, Type};

let socket = Socket::new(Domain::IPV4, Type::STREAM, None)?;

// Initialise a `SocketAddr` by calling `getsockname(2)`.
let mut addr_storage = SockAddrStorage::zeroed();
let mut len = addr_storage.size_of();

// The `getsockname(2)` system call will initialize `storage` for
// us, setting `len` to the correct length.
let res = unsafe {
    libc::getsockname(
        socket.as_raw_fd(),
        addr_storage.view_as(),
        &mut len,
    )
};
if res == -1 {
    return Err(io::Error::last_os_error());
}

let address = unsafe { SockAddr::new(addr_storage, len) };

pub unsafe fn try_init<F, T>(init: F) -> Result<(T, SockAddr), Error>
where F: FnOnce(mut SockAddrStorage, mut u32) -> Result<T, Error>,

Initialise a SockAddr by calling the function init.

The type of the address storage and length passed to the function init is OS/architecture specific.

The address is zeroed before init is called and is thus valid to dereference and read from. The length initialised to the maximum length of the storage.

§Safety

Caller must ensure that the address family and length match the type of storage address. For example if storage.ss_family is set to AF_INET the storage must be initialised as sockaddr_in, setting the content and length appropriately.

§Examples

use std::io;
use std::os::fd::AsRawFd;

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

let socket = Socket::new(Domain::IPV4, Type::STREAM, None)?;

// Initialise a `SocketAddr` by calling `getsockname(2)`.
let (_, address) = unsafe {
    SockAddr::try_init(|addr_storage, len| {
        // The `getsockname(2)` system call will initialize `storage` for
        // us, setting `len` to the correct length.
        if libc::getsockname(socket.as_raw_fd(), addr_storage.cast(), len) == -1 {
            Err(io::Error::last_os_error())
        } else {
            Ok(())
        }
    })
}?;

pub fn unix(path: P) -> Result<SockAddr, Error>
where P: AsRef<Path>,

Constructs a SockAddr with the family AF_UNIX and the provided path.

Returns an error if the path is longer than SUN_LEN.

pub unsafe fn set_length(&mut self, length: u32)

Set the length of the address.

§Safety

Caller must ensure that the address up to length bytes are properly initialised.

pub const fn family(&self) -> u16

Returns this address’s family.

pub const fn domain(&self) -> Domain

Returns this address’s Domain.

pub const fn len(&self) -> u32

Returns the size of this address in bytes.

pub const fn as_ptr(&self) -> *const SockAddrStorage

Returns a raw pointer to the address.

pub const fn as_storage(self) -> SockAddrStorage

Retuns the address as the storage.

pub const fn is_ipv4(&self) -> bool

Returns true if this address is in the AF_INET (IPv4) family, false otherwise.

pub const fn is_ipv6(&self) -> bool

Returns true if this address is in the AF_INET6 (IPv6) family, false otherwise.

pub fn is_unix(&self) -> bool

Returns true if this address is of a unix socket (for local interprocess communication), i.e. it is from the AF_UNIX family, false otherwise.

pub fn as_socket(&self) -> Option<SocketAddr>

Returns this address as a SocketAddr if it is in the AF_INET (IPv4) or AF_INET6 (IPv6) family, otherwise returns None.

pub fn as_socket_ipv4(&self) -> Option<SocketAddrV4>

Returns this address as a SocketAddrV4 if it is in the AF_INET family.

pub fn as_socket_ipv6(&self) -> Option<SocketAddrV6>

Returns this address as a SocketAddrV6 if it is in the AF_INET6 family.

§

impl SockAddr

Unix only API.

pub fn vsock(cid: u32, port: u32) -> SockAddr

Constructs a SockAddr with the family AF_VSOCK and the provided CID/port.

§Errors

This function can never fail. In a future version of this library it will be made infallible.

pub fn as_vsock_address(&self) -> Option<(u32, u32)>

Returns this address VSOCK CID/port if it is in the AF_VSOCK family, otherwise return None.

pub fn is_unnamed(&self) -> bool

Returns true if this address is an unnamed address from the AF_UNIX family (for local interprocess communication), false otherwise.

pub fn as_unix(&self) -> Option<SocketAddr>

Returns this address as Unix SocketAddr if it is an AF_UNIX pathname address, otherwise returns None.

pub fn as_pathname(&self) -> Option<&Path>

Returns this address as a Path reference if it is an AF_UNIX pathname address, otherwise returns None.

pub fn as_abstract_namespace(&self) -> Option<&[u8]>

Returns this address as a slice of bytes representing an abstract address if it is an AF_UNIX abstract address, otherwise returns None.

Abstract addresses are a Linux extension, so this method returns None on all non-Linux platforms.

Trait Implementations§

§

impl Clone for SockAddr

§

fn clone(&self) -> SockAddr

Returns a duplicate of the value. Read more

1.0.0 · Source§

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source. Read more

§

impl Debug for SockAddr

§

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

Formats the value using the given formatter. Read more

§