std::os::unix::net::SocketAncillary - Rust
Description: API documentation for the Rust `SocketAncillary` struct in crate `std`.
Keywords: rust, rustlang, rust-lang, SocketAncillary

# [−][src]Struct std::os::unix::net::SocketAncillary

    pub struct SocketAncillary<'a> { /* fields omitted */ }

🔬 This is a nightly-only experimental API. (`unix_socket_ancillary_data` #76915)
This is supported on Unix only.

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

### `impl<'a> SocketAncillary<'a>`[src]

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

🔬 This is a nightly-only experimental API. (`unix_socket_ancillary_data` #76915)
This is supported on Android or DragonFly BSD or Emscripten or FreeBSD or Linux or NetBSD or OpenBSD only.

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

#### `pub fn capacity(&self) -> usize`[src]

🔬 This is a nightly-only experimental API. (`unix_socket_ancillary_data` #76915)
This is supported on Android or DragonFly BSD or Emscripten or FreeBSD or Linux or NetBSD or OpenBSD only.

Returns the capacity of the buffer.

#### `pub fn len(&self) -> usize`[src]

🔬 This is a nightly-only experimental API. (`unix_socket_ancillary_data` #76915)
This is supported on Android or DragonFly BSD or Emscripten or FreeBSD or Linux or NetBSD or OpenBSD only.

Returns the number of used bytes.

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

### Notable traits for Messages<'a>

`impl<'a> Iterator for Messages<'a> type Item = Result<AncillaryData<'a>, AncillaryError>;`
`[src]

🔬 This is a nightly-only experimental API. (`unix_socket_ancillary_data` #76915)
This is supported on Android or DragonFly BSD or Emscripten or FreeBSD or Linux or NetBSD or OpenBSD only.

Returns the iterator of the control messages.

#### `pub fn truncated(&self) -> bool`[src]

🔬 This is a nightly-only experimental API. (`unix_socket_ancillary_data` #76915)
This is supported on Android or DragonFly BSD or Emscripten or FreeBSD or Linux or NetBSD or OpenBSD only.

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

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

🔬 This is a nightly-only experimental API. (`unix_socket_ancillary_data` #76915)
This is supported on Android or DragonFly BSD or Emscripten or FreeBSD or Linux or NetBSD or OpenBSD only.

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::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[..]);
        ancillary.add_fds(&[sock.as_raw_fd()][..]);

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

Run

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

🔬 This is a nightly-only experimental API. (`unix_socket_ancillary_data` #76915)
This is supported on Android or DragonFly BSD or Emscripten or FreeBSD or Linux or NetBSD or OpenBSD only.

Add credentials to the ancillary data.

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

#### `pub fn clear(&mut self)`[src]

🔬 This is a nightly-only experimental API. (`unix_socket_ancillary_data` #76915)
This is supported on Android or DragonFly BSD or Emscripten or FreeBSD or Linux or NetBSD or OpenBSD only.

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

### `impl<'a> Debug for SocketAncillary<'a>`[src]

This is supported on Android or DragonFly BSD or Emscripten or FreeBSD or Linux or NetBSD or OpenBSD only.

#### `fn fmt(&self, f: &mut Formatter<'_>) -> Result`[src]

Formats the value using the given formatter. Read more

## Auto Trait Implementations

### `impl<'a> RefUnwindSafe for SocketAncillary<'a>`[src]

### `impl<'a> Send for SocketAncillary<'a>`[src]

### `impl<'a> Sync for SocketAncillary<'a>`[src]

### `impl<'a> Unpin for SocketAncillary<'a>`[src]

### `impl<'a> !UnwindSafe for SocketAncillary<'a>`[src]

## Blanket Implementations

### `impl<T> Any for T where
T: 'static + ?Sized,` [src]

#### `pub fn type_id(&self) -> TypeId`[src]

Gets the `TypeId` of `self`. Read more

### `impl<T> Borrow<T> for T where
T: ?Sized,` [src]

#### `pub fn borrow(&self) -> &Tⓘ

### Notable traits for &'_ mut I

`impl<'_, I> Iterator for &'_ mut I where
I: Iterator + ?Sized, type Item = <I as Iterator>::Item;impl<'_, F> Future for &'_ mut F where
F: Unpin + Future + ?Sized, type Output = <F as Future>::Output;impl<R: Read + ?Sized> Read for &mut Rimpl<W: Write + ?Sized> Write for &mut W`
`[src]

Immutably borrows from an owned value. Read more

### `impl<T> BorrowMut<T> for T where
T: ?Sized,` [src]

#### `pub fn borrow_mut(&mut self) -> &mut Tⓘ

### Notable traits for &'_ mut I

`impl<'_, I> Iterator for &'_ mut I where
I: Iterator + ?Sized, type Item = <I as Iterator>::Item;impl<'_, F> Future for &'_ mut F where
F: Unpin + Future + ?Sized, type Output = <F as Future>::Output;impl<R: Read + ?Sized> Read for &mut Rimpl<W: Write + ?Sized> Write for &mut W`
`[src]

Mutably borrows from an owned value. Read more

### `impl<T> From<T> for T`[src]

#### `pub fn from(t: T) -> T`[src]

Performs the conversion.

### `impl<T, U> Into<U> for T where
U: From<T>,` [src]

#### `pub fn into(self) -> U`[src]

Performs the conversion.

### `impl<T, U> TryFrom<U> for T where
U: Into<T>,` [src]

#### `type Error = Infallible`

The type returned in the event of a conversion error.

#### `pub fn try_from(value: U) -> Result<T, <T as TryFrom<U>>::Error>`[src]

Performs the conversion.

### `impl<T, U> TryInto<U> for T where
U: TryFrom<T>,` [src]

#### `type Error = <U as TryFrom<T>>::Error`

The type returned in the event of a conversion error.

#### `pub fn try_into(self) -> Result<U, <U as TryFrom<T>>::Error>`[src]

Performs the conversion.