tun_rs/platform/
mod.rs

1#[cfg(unix)]
2pub(crate) mod unix;
3
4#[cfg(all(
5    unix,
6    not(any(
7        target_os = "windows",
8        target_os = "macos",
9        all(target_os = "linux", not(target_env = "ohos")),
10        target_os = "freebsd",
11        target_os = "openbsd",
12        target_os = "netbsd",
13    ))
14))]
15pub use self::unix::DeviceImpl;
16#[cfg(unix)]
17#[cfg(feature = "interruptible")]
18pub use unix::InterruptEvent;
19#[cfg(windows)]
20#[cfg(feature = "interruptible")]
21pub use windows::InterruptEvent;
22#[cfg(all(target_os = "linux", not(target_env = "ohos")))]
23pub(crate) mod linux;
24#[cfg(all(target_os = "linux", not(target_env = "ohos")))]
25pub use self::linux::*;
26
27#[cfg(target_os = "freebsd")]
28pub(crate) mod freebsd;
29#[cfg(target_os = "freebsd")]
30pub use self::freebsd::DeviceImpl;
31
32#[cfg(target_os = "macos")]
33pub(crate) mod macos;
34#[cfg(target_os = "macos")]
35pub use self::macos::DeviceImpl;
36#[cfg(target_os = "openbsd")]
37pub(crate) mod openbsd;
38#[cfg(target_os = "openbsd")]
39pub use self::openbsd::DeviceImpl;
40
41#[cfg(target_os = "netbsd")]
42pub(crate) mod netbsd;
43#[cfg(target_os = "netbsd")]
44pub use self::netbsd::DeviceImpl;
45
46#[cfg(target_os = "windows")]
47pub(crate) mod windows;
48#[cfg(target_os = "windows")]
49pub use self::windows::DeviceImpl;
50
51use getifaddrs::Interface;
52#[cfg(unix)]
53use std::io::{IoSlice, IoSliceMut};
54use std::ops::Deref;
55#[cfg(unix)]
56use std::os::fd::{AsFd, AsRawFd, BorrowedFd, FromRawFd, IntoRawFd, RawFd};
57
58#[allow(dead_code)]
59pub(crate) const ETHER_ADDR_LEN: u8 = 6;
60
61#[allow(dead_code)]
62pub(crate) fn get_if_addrs_by_name(if_name: String) -> std::io::Result<Vec<Interface>> {
63    let addrs = getifaddrs::getifaddrs()?;
64    let ifs = addrs.filter(|v| v.name == if_name).collect();
65    Ok(ifs)
66}
67
68/// A transparent wrapper around DeviceImpl, providing synchronous I/O operations.
69///
70/// # Examples
71///
72/// Basic read/write operation:
73///
74/// ```no_run
75/// use std::net::Ipv4Addr;
76/// use tun_rs::DeviceBuilder;
77///
78/// fn main() -> std::io::Result<()> {
79///     // Create a TUN device using the builder
80///     let mut tun = DeviceBuilder::new()
81///         .name("my-tun")
82///         .ipv4(Ipv4Addr::new(10, 0, 0, 1), 24, None)
83///         .build_sync()?;
84///
85///     // Send a packet
86///     // Example IP packet (Replace with real IP message)
87///     let packet = b"[IP Packet: 10.0.0.1 -> 10.0.0.2] Hello, TUN!";
88///     tun.send(packet)?;
89///     println!("Sent {} bytes IP packet", packet.len());
90///
91///     // Receive a packet
92///     let mut buf = [0u8; 1500];
93///     let n = tun.recv(&mut buf)?;
94///     println!("Received {} bytes: {:?}", n, &buf[..n]);
95///
96///     Ok(())
97/// }
98/// ```
99#[repr(transparent)]
100pub struct SyncDevice(pub(crate) DeviceImpl);
101
102impl SyncDevice {
103    /// Creates a new SyncDevice from a raw file descriptor.
104    ///
105    /// # Safety
106    /// - The file descriptor (`fd`) must be an owned file descriptor.
107    /// - It must be valid and open.
108    ///
109    /// This function is only available on Unix platforms.
110    #[cfg(unix)]
111    pub unsafe fn from_fd(fd: RawFd) -> std::io::Result<Self> {
112        Ok(SyncDevice(DeviceImpl::from_fd(fd)?))
113    }
114    /// Receives data from the device into the provided buffer.
115    ///
116    /// Returns the number of bytes read, or an I/O error.
117    ///
118    /// # Example
119    /// ```no_run
120    /// use std::net::Ipv4Addr;
121    /// use tun_rs::DeviceBuilder;
122    /// let mut tun = DeviceBuilder::new()
123    ///     .name("my-tun")
124    ///     .ipv4(Ipv4Addr::new(10, 0, 0, 1), 24, None)
125    ///     .build_sync()
126    ///     .unwrap();
127    /// let mut buf = [0u8; 1500];
128    /// tun.recv(&mut buf).unwrap();
129    /// ```
130    /// # Note
131    /// Blocking the current thread if no packet is available
132    pub fn recv(&self, buf: &mut [u8]) -> std::io::Result<usize> {
133        self.0.recv(buf)
134    }
135    /// Sends data from the provided buffer to the device.
136    ///
137    /// Returns the number of bytes written, or an I/O error.
138    ///
139    /// # Example
140    /// ```no_run
141    /// use std::net::Ipv4Addr;
142    /// use tun_rs::DeviceBuilder;
143    /// let mut tun = DeviceBuilder::new()
144    ///     .name("my-tun")
145    ///     .ipv4(Ipv4Addr::new(10, 0, 0, 1), 24, None)
146    ///     .build_sync()
147    ///     .unwrap();
148    /// tun.send(b"hello").unwrap();
149    /// ```
150    pub fn send(&self, buf: &[u8]) -> std::io::Result<usize> {
151        self.0.send(buf)
152    }
153    /// Attempts to receive data from the device in a non-blocking fashion.
154    ///
155    /// Returns the number of bytes read or an error if the operation would block.
156    #[cfg(target_os = "windows")]
157    pub fn try_recv(&self, buf: &mut [u8]) -> std::io::Result<usize> {
158        self.0.try_recv(buf)
159    }
160    /// Attempts to send data to the device in a non-blocking fashion.
161    ///
162    /// Returns the number of bytes written or an error if the operation would block.
163    #[cfg(target_os = "windows")]
164    pub fn try_send(&self, buf: &[u8]) -> std::io::Result<usize> {
165        self.0.try_send(buf)
166    }
167    /// Shuts down the device on Windows.
168    ///
169    /// This may close the device or signal that no further operations will occur.
170    #[cfg(target_os = "windows")]
171    pub fn shutdown(&self) -> std::io::Result<()> {
172        self.0.shutdown()
173    }
174    #[cfg(all(unix, feature = "experimental"))]
175    pub fn shutdown(&self) -> std::io::Result<()> {
176        Err(std::io::Error::from(std::io::ErrorKind::Unsupported))
177    }
178    /// Reads data into the provided buffer, with support for interruption.
179    ///
180    /// This function attempts to read from the underlying file descriptor into `buf`,
181    /// and can be interrupted using the given [`InterruptEvent`]. If the `event` is triggered
182    /// while the read operation is blocked, the function will return early with
183    /// an error of kind [`std::io::ErrorKind::Interrupted`].
184    ///
185    /// # Arguments
186    ///
187    /// * `buf` - The buffer to store the read data.
188    /// * `event` - An [`InterruptEvent`] used to interrupt the blocking read.
189    ///
190    /// # Returns
191    ///
192    /// On success, returns the number of bytes read. On failure, returns an [`std::io::Error`].
193    ///
194    /// # Platform-specific Behavior
195    ///
196    /// On **Unix platforms**, it is recommended to use this together with `set_nonblocking(true)`.
197    /// Without setting non-blocking mode, concurrent reads may not respond properly to interrupt signals.
198    ///
199    /// # Feature
200    ///
201    /// This method is only available when the `interruptible` feature is enabled.
202    #[cfg(feature = "interruptible")]
203    pub fn recv_intr(&self, buf: &mut [u8], event: &InterruptEvent) -> std::io::Result<usize> {
204        self.0.read_interruptible(buf, event)
205    }
206    /// Like [`recv_intr`](Self::recv_intr), but reads into multiple buffers.
207    ///
208    /// This function behaves the same as [`recv_intr`](Self::recv_intr),
209    /// but uses `readv` to fill the provided set of non-contiguous buffers.
210    ///
211    /// # Feature
212    ///
213    /// This method is only available when the `interruptible` feature is enabled.
214    #[cfg(all(unix, feature = "interruptible"))]
215    pub fn recv_vectored_intr(
216        &self,
217        bufs: &mut [IoSliceMut<'_>],
218        event: &InterruptEvent,
219    ) -> std::io::Result<usize> {
220        self.0.readv_interruptible(bufs, event)
221    }
222    #[cfg(feature = "interruptible")]
223    pub fn wait_readable_intr(&self, event: &InterruptEvent) -> std::io::Result<()> {
224        self.0.wait_readable_interruptible(event)
225    }
226    #[cfg(feature = "interruptible")]
227    pub fn send_intr(&self, buf: &[u8], event: &InterruptEvent) -> std::io::Result<usize> {
228        self.0.write_interruptible(buf, event)
229    }
230    #[cfg(all(unix, feature = "interruptible"))]
231    pub fn send_vectored_intr(
232        &self,
233        bufs: &[IoSlice<'_>],
234        event: &InterruptEvent,
235    ) -> std::io::Result<usize> {
236        self.0.writev_interruptible(bufs, event)
237    }
238    #[cfg(all(unix, feature = "interruptible"))]
239    #[inline]
240    pub fn wait_writable_intr(&self, event: &InterruptEvent) -> std::io::Result<()> {
241        self.0.wait_writable_interruptible(event)
242    }
243    /// Receives data from the device into multiple buffers using vectored I/O.
244    ///
245    /// **Note:** This method operates on a single packet only. It will only read data from one packet,
246    /// even if multiple buffers are provided.
247    ///
248    /// Returns the total number of bytes read from the packet, or an error.
249    #[cfg(unix)]
250    pub fn recv_vectored(&self, bufs: &mut [IoSliceMut<'_>]) -> std::io::Result<usize> {
251        self.0.recv_vectored(bufs)
252    }
253    /// Sends data to the device from multiple buffers using vectored I/O.
254    ///
255    /// **Note:** This method operates on a single packet only. It will only send the data contained in
256    /// the provided buffers as one packet.
257    ///
258    /// Returns the total number of bytes written for the packet, or an error.
259    #[cfg(unix)]
260    pub fn send_vectored(&self, bufs: &[IoSlice<'_>]) -> std::io::Result<usize> {
261        self.0.send_vectored(bufs)
262    }
263    /// Checks whether the device is currently operating in nonblocking mode.
264    ///
265    /// Returns `true` if nonblocking mode is enabled, `false` otherwise, or an error.
266    #[cfg(unix)]
267    pub fn is_nonblocking(&self) -> std::io::Result<bool> {
268        self.0.is_nonblocking()
269    }
270
271    /// Sets the nonblocking mode for the device.
272    ///
273    /// - `nonblocking`: Pass `true` to enable nonblocking mode, `false` to disable.
274    ///
275    /// Returns an empty result on success or an I/O error.
276    #[cfg(unix)]
277    pub fn set_nonblocking(&self, nonblocking: bool) -> std::io::Result<()> {
278        self.0.set_nonblocking(nonblocking)
279    }
280
281    /// # Prerequisites
282    /// - The `IFF_MULTI_QUEUE` flag must be enabled.
283    /// - The system must support network interface multi-queue functionality.
284    ///
285    /// # Description
286    /// When multi-queue is enabled, create a new queue by duplicating an existing one.
287    #[cfg(all(target_os = "linux", not(target_env = "ohos")))]
288    pub fn try_clone(&self) -> std::io::Result<SyncDevice> {
289        let device_impl = self.0.try_clone()?;
290        Ok(SyncDevice(device_impl))
291    }
292}
293#[cfg(all(target_os = "linux", not(target_env = "ohos")))]
294impl SyncDevice {
295    #[cfg(feature = "interruptible")]
296    pub fn send_multiple_intr<B: ExpandBuffer>(
297        &self,
298        gro_table: &mut GROTable,
299        bufs: &mut [B],
300        offset: usize,
301        event: &InterruptEvent,
302    ) -> std::io::Result<usize> {
303        self.send_multiple0(gro_table, bufs, offset, |tun, buf| {
304            tun.write_interruptible(buf, event)
305        })
306    }
307    #[cfg(feature = "interruptible")]
308    pub fn recv_multiple_intr<B: AsRef<[u8]> + AsMut<[u8]>>(
309        &self,
310        original_buffer: &mut [u8],
311        bufs: &mut [B],
312        sizes: &mut [usize],
313        offset: usize,
314        event: &InterruptEvent,
315    ) -> std::io::Result<usize> {
316        self.recv_multiple0(original_buffer, bufs, sizes, offset, |tun, buf| {
317            tun.read_interruptible(buf, event)
318        })
319    }
320}
321
322impl Deref for SyncDevice {
323    type Target = DeviceImpl;
324    fn deref(&self) -> &Self::Target {
325        &self.0
326    }
327}
328
329#[cfg(unix)]
330impl FromRawFd for SyncDevice {
331    unsafe fn from_raw_fd(fd: RawFd) -> Self {
332        SyncDevice::from_fd(fd).unwrap()
333    }
334}
335#[cfg(unix)]
336impl AsRawFd for SyncDevice {
337    fn as_raw_fd(&self) -> RawFd {
338        self.0.as_raw_fd()
339    }
340}
341#[cfg(unix)]
342impl AsFd for SyncDevice {
343    fn as_fd(&self) -> BorrowedFd<'_> {
344        unsafe { BorrowedFd::borrow_raw(self.as_raw_fd()) }
345    }
346}
347#[cfg(unix)]
348impl IntoRawFd for SyncDevice {
349    fn into_raw_fd(self) -> RawFd {
350        self.0.into_raw_fd()
351    }
352}
tun_rs/platform/mod.rs

tun_rs/platform/
mod.rs
