Struct std::os::unix::net::SocketAncillary

source ·
pub struct SocketAncillary<'a> { /* private fields */ }
🔬This is a nightly-only experimental API. (unix_socket_ancillary_data #76915)
Available on (Android or Linux) and Unix only.
Expand description

A Unix socket Ancillary data struct.

§Example

#![feature(unix_socket_ancillary_data)]
use std::os::unix::net::{UnixStream, SocketAncillary, AncillaryData};
use std::io::IoSliceMut;

fn main() -> std::io::Result<()> {
    let sock = UnixStream::connect("/tmp/sock")?;

    let mut fds = [0; 8];
    let mut ancillary_buffer = [0; 128];
    let mut ancillary = SocketAncillary::new(&mut ancillary_buffer[..]);

    let mut buf = [1; 8];
    let mut bufs = &mut [IoSliceMut::new(&mut buf[..])][..];
    sock.recv_vectored_with_ancillary(bufs, &mut ancillary)?;

    for ancillary_result in ancillary.messages() {
        if let AncillaryData::ScmRights(scm_rights) = ancillary_result.unwrap() {
            for fd in scm_rights {
                println!("receive file descriptor: {fd}");
            }
        }
    }
    Ok(())
}
Run

Implementations§

source§

impl<'a> SocketAncillary<'a>

source

pub fn new(buffer: &'a mut [u8]) -> Self

🔬This is a nightly-only experimental API. (unix_socket_ancillary_data #76915)

Create an ancillary data with the given buffer.

§Example
#![feature(unix_socket_ancillary_data)]
use std::os::unix::net::SocketAncillary;
let mut ancillary_buffer = [0; 128];
let mut ancillary = SocketAncillary::new(&mut ancillary_buffer[..]);
Run
source

pub fn capacity(&self) -> usize

🔬This is a nightly-only experimental API. (unix_socket_ancillary_data #76915)

Returns the capacity of the buffer.

source

pub fn is_empty(&self) -> bool

🔬This is a nightly-only experimental API. (unix_socket_ancillary_data #76915)

Returns true if the ancillary data is empty.

source

pub fn len(&self) -> usize

🔬This is a nightly-only experimental API. (unix_socket_ancillary_data #76915)

Returns the number of used bytes.

source

pub fn messages(&self) -> Messages<'_>

🔬This is a nightly-only experimental API. (unix_socket_ancillary_data #76915)

Returns the iterator of the control messages.

source

pub fn truncated(&self) -> bool

🔬This is a nightly-only experimental API. (unix_socket_ancillary_data #76915)

Is true if during a recv operation the ancillary was truncated.

§Example
#![feature(unix_socket_ancillary_data)]
use std::os::unix::net::{UnixStream, SocketAncillary};
use std::io::IoSliceMut;

fn main() -> std::io::Result<()> {
    let sock = UnixStream::connect("/tmp/sock")?;

    let mut ancillary_buffer = [0; 128];
    let mut ancillary = SocketAncillary::new(&mut ancillary_buffer[..]);

    let mut buf = [1; 8];
    let mut bufs = &mut [IoSliceMut::new(&mut buf[..])][..];
    sock.recv_vectored_with_ancillary(bufs, &mut ancillary)?;

    println!("Is truncated: {}", ancillary.truncated());
    Ok(())
}
Run
source

pub fn add_fds(&mut self, fds: &[RawFd]) -> bool

🔬This is a nightly-only experimental API. (unix_socket_ancillary_data #76915)

Add file descriptors to the ancillary data.

The function returns true if there was enough space in the buffer. If there was not enough space then no file descriptors was appended. Technically, that means this operation adds a control message with the level SOL_SOCKET and type SCM_RIGHTS.

§Example
#![feature(unix_socket_ancillary_data)]
use std::os::unix::net::{UnixStream, SocketAncillary};
use std::os::unix::io::AsRawFd;
use std::io::IoSlice;

fn main() -> std::io::Result<()> {
    let sock = UnixStream::connect("/tmp/sock")?;

    let mut ancillary_buffer = [0; 128];
    let mut ancillary = SocketAncillary::new(&mut ancillary_buffer[..]);
    ancillary.add_fds(&[sock.as_raw_fd()][..]);

    let buf = [1; 8];
    let mut bufs = &mut [IoSlice::new(&buf[..])][..];
    sock.send_vectored_with_ancillary(bufs, &mut ancillary)?;
    Ok(())
}
Run
source

pub fn add_creds(&mut self, creds: &[SocketCred]) -> bool

🔬This is a nightly-only experimental API. (unix_socket_ancillary_data #76915)

Add credentials to the ancillary data.

The function returns true if there is enough space in the buffer. If there is not enough space then no credentials will be appended. Technically, that means this operation adds a control message with the level SOL_SOCKET and type SCM_CREDENTIALS, SCM_CREDS, or SCM_CREDS2.

source

pub fn clear(&mut self)

🔬This is a nightly-only experimental API. (unix_socket_ancillary_data #76915)

Clears the ancillary data, removing all values.

§Example
#![feature(unix_socket_ancillary_data)]
use std::os::unix::net::{UnixStream, SocketAncillary, AncillaryData};
use std::io::IoSliceMut;

fn main() -> std::io::Result<()> {
    let sock = UnixStream::connect("/tmp/sock")?;

    let mut fds1 = [0; 8];
    let mut fds2 = [0; 8];
    let mut ancillary_buffer = [0; 128];
    let mut ancillary = SocketAncillary::new(&mut ancillary_buffer[..]);

    let mut buf = [1; 8];
    let mut bufs = &mut [IoSliceMut::new(&mut buf[..])][..];

    sock.recv_vectored_with_ancillary(bufs, &mut ancillary)?;
    for ancillary_result in ancillary.messages() {
        if let AncillaryData::ScmRights(scm_rights) = ancillary_result.unwrap() {
            for fd in scm_rights {
                println!("receive file descriptor: {fd}");
            }
        }
    }

    ancillary.clear();

    sock.recv_vectored_with_ancillary(bufs, &mut ancillary)?;
    for ancillary_result in ancillary.messages() {
        if let AncillaryData::ScmRights(scm_rights) = ancillary_result.unwrap() {
            for fd in scm_rights {
                println!("receive file descriptor: {fd}");
            }
        }
    }
    Ok(())
}
Run

Trait Implementations§

source§

impl<'a> Debug for SocketAncillary<'a>

source§

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

Formats the value using the given formatter. Read more

Auto Trait Implementations§

§

impl<'a> Freeze for SocketAncillary<'a>

§

impl<'a> RefUnwindSafe for SocketAncillary<'a>

§

impl<'a> Send for SocketAncillary<'a>

§

impl<'a> Sync for SocketAncillary<'a>

§

impl<'a> Unpin for SocketAncillary<'a>

§

impl<'a> !UnwindSafe for SocketAncillary<'a>

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>,

§

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>,

§

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.