Struct tokio_seqpacket::ancillary::AncillaryMessageWriter

pub struct AncillaryMessageWriter<'a> { /* private fields */ }

Writer to help you construct ancillary messages for Unix sockets.

The writer uses a pre-allocated buffer and will never (re)-allocate.

Example

use tokio_seqpacket::UnixSeqpacket;
use tokio_seqpacket::ancillary::AncillaryMessageWriter;
use std::io::IoSlice;
use std::os::fd::AsRawFd;

#[tokio::main]
async fn main() -> std::io::Result<()> {
    let sock = UnixSeqpacket::connect("/tmp/sock").await?;
    let file = std::fs::File::create("/tmp/my-file")?;

    let mut fds = [0; 8];
    let mut ancillary_buffer = [0; 128];
    let mut ancillary = AncillaryMessageWriter::new(&mut ancillary_buffer);
    ancillary.add_fds(&[&file])?;

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

    Ok(())
}

Implementations

impl<'a> AncillaryMessageWriter<'a>

pub const BUFFER_ALIGN: usize = 4usize

Alignment requirement for the control messages added to the buffer.

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

Create an ancillary data with the given buffer.

Some bytes at the start of the buffer may be left unused to enforce alignment to Self::BUFFER_ALIGN. You can use Self::capacity() to check how much of the buffer can be used for control messages.

Example

use tokio_seqpacket::ancillary::AncillaryMessageWriter;
let mut ancillary_buffer = [0; 128];
let mut ancillary = AncillaryMessageWriter::new(&mut ancillary_buffer);

pub fn capacity(&self) -> usize

Returns the capacity of the buffer.

pub fn is_empty(&self) -> bool

Returns true if the ancillary data is empty.

pub fn len(&self) -> usize

Returns the number of used bytes.

pub fn add_fds<T>(&mut self, fds: &[T]) -> Result<(), AddControlMessageError>where T: BorrowFd<'a>,

Add file descriptors to the ancillary data.

The function returns Ok(()) if there was enough space in the buffer. If there was not enough space then no file descriptors was appended.

This adds a single control message with level SOL_SOCKET and type SCM_RIGHTS.

Example

use tokio_seqpacket::UnixSeqpacket;
use tokio_seqpacket::ancillary::AncillaryMessageWriter;
use std::os::unix::io::AsFd;
use std::io::IoSlice;

#[tokio::main]
async fn main() -> std::io::Result<()> {
    let sock = UnixSeqpacket::connect("/tmp/sock").await?;
    let file = std::fs::File::open("/my/file")?;

    let mut ancillary_buffer = [0; 128];
    let mut ancillary = AncillaryMessageWriter::new(&mut ancillary_buffer);
    ancillary.add_fds(&[file.as_fd()]);

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

pub fn add_ucreds( &mut self, credentials: &[UCred] ) -> Result<(), AddControlMessageError>

Add Unix credentials to the ancillary data.

The function returns Ok(()) if there is enough space in the buffer. If there is not enough space, then no credentials are appended.

This function adds a single control message with level SOL_SOCKET and type SCM_CREDENTIALS on most platforms. On NetBSD the message has type SCM_CREDS.

Trait Implementations

impl<'a> Debug for AncillaryMessageWriter<'a>

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

Formats the value using the given formatter.