Struct interprocess::os::unix::udsocket::UdStream

pub struct UdStream { /* fields omitted */ }

A Unix domain socket byte stream, obtained either from UdStreamListener or by connecting to an existing server.

Examples

Basic example:

use interprocess::os::unix::udsocket::UdStream;
use std::io::prelude::*;

let mut conn = UdStream::connect("/tmp/example1.sock")?;
conn.write(b"Hello from client!");
let mut string_buffer = String::new();
conn.read_to_string(&mut string_buffer);
println!("Server answered: {}", string_buffer);

Receiving and sending ancillary data:

use interprocess::os::unix::udsocket::{UdStream, AncillaryData, AncillaryDataBuf};
use std::{
    io::{self, prelude::*},
    borrow::Cow,
    fs,
    os::unix::io::{IntoRawFd, FromRawFd},
};

// Create one file descriptor which we will be sending.
let fd = fs::File::open("/tmp/example_file.mfa")?.into_raw_fd();
// Borrow the file descriptor in a slice right away to send it later.
let fds = [fd];
let fd_ancillary = AncillaryData::FileDescriptors(
    Cow::Borrowed(&fds),
);
// Prepare valid credentials.
let credentials = AncillaryData::credentials();
// Allocate a sufficient buffer for receiving ancillary data.
let mut ancillary_buffer = AncillaryDataBuf::owned_with_capacity(
    AncillaryData::ENCODED_SIZE_OF_CREDENTIALS
  + AncillaryData::encoded_size_of_file_descriptors(1),
);

let conn = UdStream::connect("/tmp/example2.sock")?;

conn.send_ancillary(
    b"File descriptor and credentials from client!",
    [fd_ancillary, credentials].iter().map(|x| x.clone_ref()),
)?;
// The receive buffer size depends on the situation, but since this example
// mirrors the second one from UdSocketListener, 64 is sufficient.
let mut recv_buffer = [0; 64];

conn.recv_ancillary(
    &mut recv_buffer,
    &mut ancillary_buffer,
)?;
println!("Server answered: {}", String::from_utf8_lossy(&recv_buffer));
// Decode the received ancillary data.
let (mut file_descriptors, mut cred) = (None, None);
for element in ancillary_buffer.decode() {
    match element {
        AncillaryData::FileDescriptors(fds) => file_descriptors = Some(fds),
        AncillaryData::Credentials {pid, uid, gid} => cred = Some((pid, uid, gid)),
    }
}
let mut files = Vec::new();
if let Some(fds) = file_descriptors {
    // There is a possibility that zero file descriptors were sent — let's account for that.
    for fd in fds.iter().copied() {
        // This is normally unsafe, but since we know that the descriptor is not owned somewhere
        // else in the current process, it's fine to do this:
        let file = unsafe {fs::File::from_raw_fd(fd)};
        files.push(file);
    }
}
for mut file in files {
    file.write(b"Hello foreign file descriptor!");
}
if let Some(credentials) = cred {
    println!("Server\tPID: {}", credentials.0);
    println!(      "\tUID: {}", credentials.1);
    println!(      "\tGID: {}", credentials.2);
}

Implementations

impl UdStream

pub fn connect<'a>(path: impl ToUdSocketPath<'a>) -> Result<Self>

Connect to a Unix domain socket server at the specified path.

Example

use interprocess::os::unix::udsocket::UdStream;

let conn = UdStream::connect("/tmp/example.sock")?;
// Handle the connection to the server

See ToUdSocketPath for an example of using various string types to specify socket paths.

System calls

• socket
• connect

pub fn recv(&self, buf: &mut [u8]) -> Result<usize>

Receives bytes from the socket stream.

System calls

• recvmsg
  • Future versions may use read instead; for now, this method is a wrapper around recv_vectored.

pub fn recv_vectored(&self, bufs: &mut [IoSliceMut<'_>]) -> Result<usize>

Receives bytes from the socket stream, making use of scatter input for the main data.

System calls

• recvmsg
  • Future versions may use readv instead; for now, this method is a wrapper around recv_ancillary_vectored.

pub fn recv_ancillary<'a: 'b, 'b>(
    &self,
    buf: &mut [u8],
    abuf: &'b mut AncillaryDataBuf<'a>
) -> Result<(usize, usize)>

Receives both bytes and ancillary data from the socket stream.

The ancillary data buffer is automatically converted from the supplied value, if possible. For that reason, mutable slices of bytes (u8 values) can be passed directly.

System calls

• recvmsg

pub fn recv_ancillary_vectored<'a: 'b, 'b>(
    &self,
    bufs: &[IoSliceMut<'_>],
    abuf: &'b mut AncillaryDataBuf<'a>
) -> Result<(usize, usize)>

Receives bytes and ancillary data from the socket stream, making use of scatter input for the main data.

The ancillary data buffer is automatically converted from the supplied value, if possible. For that reason, mutable slices of bytes (u8 values) can be passed directly.

System calls

• recvmsg

pub fn send(&self, buf: &[u8]) -> Result<usize>

Sends bytes into the socket stream.

System calls

• sendmsg
  • Future versions of interprocess may use write instead; for now, this method is a wrapper around send_vectored.

pub fn send_vectored(&self, bufs: &[IoSlice<'_>]) -> Result<usize>

Sends bytes into the socket stream, making use of gather output for the main data.

System calls

• sendmsg
  • Future versions of interprocess may use writev instead; for now, this method is a wrapper around send_ancillary_vectored.

pub fn send_ancillary<'a>(
    &self,
    buf: &[u8],
    ancillary_data: impl IntoIterator<Item = AncillaryData<'a>>
) -> Result<(usize, usize)>

Sends bytes and ancillary data into the socket stream.

The ancillary data buffer is automatically converted from the supplied value, if possible. For that reason, slices and Vecs of AncillaryData can be passed directly.

System calls

• sendmsg

pub fn send_ancillary_vectored<'a>(
    &self,
    bufs: &[IoSlice<'_>],
    ancillary_data: impl IntoIterator<Item = AncillaryData<'a>>
) -> Result<(usize, usize)>

Sends bytes and ancillary data into the socket stream, making use of gather output for the main data.

The ancillary data buffer is automatically converted from the supplied value, if possible. For that reason, slices and Vecs of AncillaryData can be passed directly.

System calls

• sendmsg

Trait Implementations

impl AsRawFd for UdStream

fn as_raw_fd(&self) -> c_int

Extracts the raw file descriptor.

impl Debug for UdStream

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

Formats the value using the given formatter.

impl FromRawFd for UdStream

unsafe fn from_raw_fd(fd: c_int) -> Self

Constructs a new instance of Self from the given raw file descriptor.

impl IntoRawFd for UdStream

fn into_raw_fd(self) -> c_int

Consumes this object, returning the raw underlying file descriptor.

impl Read for UdStream

fn read(&mut self, buf: &mut [u8]) -> Result<usize>

Pull some bytes from this source into the specified buffer, returning how many bytes were read.

fn read_vectored(&mut self, bufs: &mut [IoSliceMut<'_>]) -> Result<usize>

Like read, except that it reads into a slice of buffers.

fn is_read_vectored(&self) -> bool

🔬 This is a nightly-only experimental API. (can_vector)

Determines if this Reader has an efficient read_vectored implementation.

unsafe fn initializer(&self) -> Initializer

🔬 This is a nightly-only experimental API. (read_initializer)

Determines if this Reader can work with buffers of uninitialized memory.

fn read_to_end(&mut self, buf: &mut Vec<u8>) -> Result<usize, Error>

Read all bytes until EOF in this source, placing them into buf.

fn read_to_string(&mut self, buf: &mut String) -> Result<usize, Error>

Read all bytes until EOF in this source, appending them to buf.

fn read_exact(&mut self, buf: &mut [u8]) -> Result<(), Error>

Read the exact number of bytes required to fill buf.

fn by_ref(&mut self) -> &mut Self

Creates a "by reference" adaptor for this instance of Read.

fn bytes(self) -> Bytes<Self>

Transforms this Read instance to an [Iterator] over its bytes.

fn chain<R>(self, next: R) -> Chain<Self, R> where
    R: Read, 

Creates an adaptor which will chain this stream with another.

fn take(self, limit: u64) -> Take<Self>

Creates an adaptor which will read at most limit bytes from it.

impl Write for UdStream

fn write(&mut self, buf: &[u8]) -> Result<usize>

Write a buffer into this writer, returning how many bytes were written.

fn write_vectored(&mut self, bufs: &[IoSlice<'_>]) -> Result<usize>

Like [write], except that it writes from a slice of buffers.

fn flush(&mut self) -> Result<()>

Flush this output stream, ensuring that all intermediately buffered contents reach their destination.

fn is_write_vectored(&self) -> bool

🔬 This is a nightly-only experimental API. (can_vector)

Determines if this Writeer has an efficient [write_vectored] implementation.

fn write_all(&mut self, buf: &[u8]) -> Result<(), Error>

Attempts to write an entire buffer into this writer.

fn write_all_vectored(&mut self, bufs: &mut [IoSlice<'_>]) -> Result<(), Error>

🔬 This is a nightly-only experimental API. (write_all_vectored)

Attempts to write multiple buffers into this writer.

fn write_fmt(&mut self, fmt: Arguments<'_>) -> Result<(), Error>

Writes a formatted string into this writer, returning any error encountered.

fn by_ref(&mut self) -> &mut Self

Creates a "by reference" adaptor for this instance of Write.