dope-sys 0.42.0

Typed operating-system call contracts
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119

use std::ptr;

use crate::io::socket::addr;

pub mod source;

/// Exact message flags one receive reported for its payload.
#[derive(Clone, Copy, Debug, Eq, PartialEq)]
#[repr(transparent)]
pub struct Flags(u32);

impl Flags {
    pub const NONE: Self = Self(0);

    pub const fn new(bits: u32) -> Self {
        Self(bits)
    }

    /// Whether the kernel truncated the received payload.
    pub const fn is_truncated(self) -> bool {
        self.0 & libc::MSG_TRUNC as u32 != 0
    }

    /// Raw reported bits, for exact diagnostics.
    pub const fn raw(self) -> u32 {
        self.0
    }
}

/// One native scatter/gather extent.
///
/// Values carry no borrow by themselves; installing them in a [`Header`] and
/// freezing that header retains the bytes they point at.
#[derive(Clone, Copy)]
#[repr(transparent)]
pub struct Iovec(pub(super) libc::iovec);

impl Iovec {
    #[must_use]
    pub const fn empty() -> Self {
        Self(libc::iovec {
            iov_base: ptr::null_mut(),
            iov_len: 0,
        })
    }

    #[must_use]
    pub fn from_slice(bytes: &[u8]) -> Self {
        Self(libc::iovec {
            iov_base: bytes.as_ptr().cast_mut().cast(),
            iov_len: bytes.len(),
        })
    }

    /// Exact byte extent this entry covers.
    #[must_use]
    pub const fn len(self) -> usize {
        self.0.iov_len
    }

    pub const fn is_empty(self) -> bool {
        self.len() == 0
    }
}

/// One native message header over caller-owned extents.
///
/// The value is deliberately not `Copy`: a configured header is the root of a
/// raw pointer graph and is frozen through the caller's message type.
#[repr(transparent)]
pub struct Header(libc::msghdr);

impl Header {
    #[must_use]
    pub const fn new() -> Self {
        Self(libc::msghdr {
            msg_name: ptr::null_mut(),
            msg_namelen: 0,
            msg_iov: ptr::null_mut(),
            msg_iovlen: 0,
            msg_control: ptr::null_mut(),
            msg_controllen: 0,
            msg_flags: 0,
        })
    }

    /// Installs one exact address view as this header's destination.
    pub fn name(&mut self, addr: addr::Addr<'_>) {
        let (addr, len) = addr.parts();
        self.0.msg_name = addr.cast_mut().cast();
        self.0.msg_namelen = len.raw();
    }

    /// Installs ancillary bytes whose borrow the caller retains.
    pub fn control(&mut self, control: &[u8]) {
        self.0.msg_control = control.as_ptr().cast_mut().cast();
        self.0.msg_controllen = control.len() as _;
    }

    /// Installs the exact extent list as this header's scatter/gather vector.
    pub fn bind(&mut self, iovecs: &[Iovec]) {
        self.0.msg_iov = if iovecs.is_empty() {
            ptr::null_mut()
        } else {
            iovecs.as_ptr().cast_mut().cast()
        };
        self.0.msg_iovlen = iovecs.len() as _;
    }

    pub(crate) const fn as_raw(&self) -> &libc::msghdr {
        &self.0
    }
}

impl Default for Header {
    fn default() -> Self {
        Self::new()
    }
}