Struct privsep::net::SocketAncillary

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

A Unix socket Ancillary data struct.

Example

use privsep::net::{SocketAncillary, AncillaryData, StdUnixStreamExt};
use std::io::IoSliceMut;
use std::os::unix::net::UnixStream;

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().flatten() {
        if let AncillaryData::ScmRights(scm_rights) = ancillary_result {
            for fd in scm_rights {
                println!("receive file descriptor: {}", fd);
            }
        }
    }
    Ok(())
}

Implementations

impl<'a> SocketAncillary<'a>

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

Create an ancillary data with the given buffer.

Example

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

pub fn capacity(&self) -> usize

Returns the capacity of the buffer.

pub fn len(&self) -> usize

Returns the number of used bytes.

pub fn is_empty(&self) -> bool

Checks if the buffer is empty

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

Returns the iterator of the control messages.

pub fn truncated(&self) -> bool

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

Example

use privsep::net::{SocketAncillary, AncillaryData, StdUnixStreamExt};
use std::io::IoSliceMut;
use std::os::unix::net::UnixStream;

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

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

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

use privsep::net::{SocketAncillary, AncillaryData, StdUnixStreamExt};
use std::io::IoSlice;
use std::os::unix::net::UnixStream;
use std::os::unix::io::AsRawFd;

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 [IoSlice::new(&mut buf[..])][..];
    sock.send_vectored_with_ancillary(bufs, &mut ancillary)?;
    Ok(())
}

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

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)

Clears the ancillary data, removing all values.

Example

use privsep::net::{SocketAncillary, AncillaryData, StdUnixStreamExt};
use std::io::IoSliceMut;
use std::os::unix::net::UnixStream;

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().flatten() {
        if let AncillaryData::ScmRights(scm_rights) = ancillary_result {
            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().flatten() {
        if let AncillaryData::ScmRights(scm_rights) = ancillary_result {
            for fd in scm_rights {
                println!("receive file descriptor: {}", fd);
            }
        }
    }
    Ok(())
}

Trait Implementations

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

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

Formats the value using the given formatter.