# Struct 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(())
    }

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

Creates 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[..]);

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(())
    }

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(())
    }

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(())
    }

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

Source§

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

Source§

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