Struct BorrowedSyncDevice 

pub struct BorrowedSyncDevice<'dev> { /* private fields */ }

Available on Unix only.

Implementations

impl BorrowedSyncDevice<'_>

pub unsafe fn borrow_raw(fd: RawFd) -> Result<Self>

Safety

The fd passed in must be a valid, open file descriptor. Unlike SyncDevice::from_fd, this function does not take ownership of fd, and therefore will not close it when dropped.
The caller is responsible for ensuring the lifetime and eventual closure of fd.

Methods from Deref<Target = SyncDevice>

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

Receives data from the device into the provided buffer.

Returns the number of bytes read, or an I/O error.

Example

use std::net::Ipv4Addr;
use tun_rs::DeviceBuilder;
let mut tun = DeviceBuilder::new()
    .name("my-tun")
    .ipv4(Ipv4Addr::new(10, 0, 0, 1), 24, None)
    .build_sync()
    .unwrap();
let mut buf = [0u8; 1500];
tun.recv(&mut buf).unwrap();

Note

Blocking the current thread if no packet is available

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

Sends data from the provided buffer to the device.

Returns the number of bytes written, or an I/O error.

Example

use std::net::Ipv4Addr;
use tun_rs::DeviceBuilder;
let mut tun = DeviceBuilder::new()
    .name("my-tun")
    .ipv4(Ipv4Addr::new(10, 0, 0, 1), 24, None)
    .build_sync()
    .unwrap();
tun.send(b"hello").unwrap();

pub fn shutdown(&self) -> Result<()>

Available on crate feature experimental only.

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

Available on crate feature interruptible only.

Reads data into the provided buffer, with support for interruption.

This function attempts to read from the underlying file descriptor into buf, and can be interrupted using the given InterruptEvent. If the event is triggered while the read operation is blocked, the function will return early with an error of kind std::io::ErrorKind::Interrupted.

Arguments

• buf - The buffer to store the read data.
• event - An InterruptEvent used to interrupt the blocking read.

Returns

On success, returns the number of bytes read. On failure, returns an std::io::Error.

Platform-specific Behavior

On Unix platforms, it is recommended to use this together with set_nonblocking(true). Without setting non-blocking mode, concurrent reads may not respond properly to interrupt signals.

Feature

This method is only available when the interruptible feature is enabled.

pub fn recv_intr_timeout( &self, buf: &mut [u8], event: &InterruptEvent, timeout: Option<Duration>, ) -> Result<usize>

Available on crate feature interruptible only.

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

Available on crate feature interruptible only.

Like recv_intr, but reads into multiple buffers.

This function behaves the same as recv_intr, but uses readv to fill the provided set of non-contiguous buffers.

Feature

This method is only available when the interruptible feature is enabled.

pub fn recv_vectored_intr_timeout( &self, bufs: &mut [IoSliceMut<'_>], event: &InterruptEvent, timeout: Option<Duration>, ) -> Result<usize>

Available on crate feature interruptible only.

pub fn wait_readable_intr(&self, event: &InterruptEvent) -> Result<()>

Available on crate feature interruptible only.

pub fn wait_readable_intr_timeout( &self, event: &InterruptEvent, timeout: Option<Duration>, ) -> Result<()>

Available on crate feature interruptible only.

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

Available on crate feature interruptible only.

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

Available on crate feature interruptible only.

pub fn wait_writable_intr(&self, event: &InterruptEvent) -> Result<()>

Available on crate feature interruptible only.

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

Receives data from the device into multiple buffers using vectored I/O.

Note: This method operates on a single packet only. It will only read data from one packet, even if multiple buffers are provided.

Returns the total number of bytes read from the packet, or an error.

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

Sends data to the device from multiple buffers using vectored I/O.

Note: This method operates on a single packet only. It will only send the data contained in the provided buffers as one packet.

Returns the total number of bytes written for the packet, or an error.

pub fn is_nonblocking(&self) -> Result<bool>

Checks whether the device is currently operating in nonblocking mode.

Returns true if nonblocking mode is enabled, false otherwise, or an error.

pub fn set_nonblocking(&self, nonblocking: bool) -> Result<()>

Sets the nonblocking mode for the device.

• nonblocking: Pass true to enable nonblocking mode, false to disable.

Returns an empty result on success or an I/O error.

pub fn try_clone(&self) -> Result<SyncDevice>

Available on Linux and non-target_env=ohos only.

Prerequisites

• The IFF_MULTI_QUEUE flag must be enabled.
• The system must support network interface multi-queue functionality.

Description

When multi-queue is enabled, create a new queue by duplicating an existing one.

pub fn send_multiple_intr<B: ExpandBuffer>( &self, gro_table: &mut GROTable, bufs: &mut [B], offset: usize, event: &InterruptEvent, ) -> Result<usize>

Available on Linux and non-target_env=ohos and crate feature interruptible only.

pub fn recv_multiple_intr<B: AsRef<[u8]> + AsMut<[u8]>>( &self, original_buffer: &mut [u8], bufs: &mut [B], sizes: &mut [usize], offset: usize, event: &InterruptEvent, ) -> Result<usize>

Available on Linux and non-target_env=ohos and crate feature interruptible only.

Methods from Deref<Target = DeviceImpl>

pub fn if_index(&self) -> Result<u32>

Available on Linux and non-target_env=ohos, or macOS, or FreeBSD, or OpenBSD, or NetBSD only.

Retrieves the interface index for the network interface.

This function converts the interface name (obtained via self.name()) into a C-compatible string (CString) and then calls the libc function if_nametoindex to retrieve the corresponding interface index.

pub fn addresses(&self) -> Result<Vec<IpAddr>>

Available on Linux and non-target_env=ohos, or macOS, or FreeBSD, or OpenBSD, or NetBSD only.

Retrieves all IP addresses associated with the network interface.

This function calls getifaddrs with the interface name, then iterates over the returned list of interface addresses, extracting and collecting the IP addresses into a vector.

pub fn udp_gso(&self) -> bool

Available on Linux and non-target_env=ohos only.

Returns whether UDP Generic Segmentation Offload (GSO) is enabled.

This is determined by the udp_gso flag in the device.

pub fn tcp_gso(&self) -> bool

Available on Linux and non-target_env=ohos only.

Returns whether TCP Generic Segmentation Offload (GSO) is enabled.

In this implementation, this is represented by the vnet_hdr flag.

pub fn set_tx_queue_len(&self, tx_queue_len: u32) -> Result<()>

Available on Linux and non-target_env=ohos only.

Sets the transmit queue length for the network interface.

This method constructs an interface request (ifreq) structure, assigns the desired transmit queue length to the ifru_metric field, and calls the change_tx_queue_len function using the control file descriptor. If the underlying operation fails, an I/O error is returned.

pub fn tx_queue_len(&self) -> Result<u32>

Available on Linux and non-target_env=ohos only.

Retrieves the current transmit queue length for the network interface.

This function constructs an interface request structure and calls tx_queue_len to populate it with the current transmit queue length. The value is then returned.

pub fn persist(&self) -> Result<()>

Available on Linux and non-target_env=ohos only.

Make the device persistent.

pub fn user(&self, value: i32) -> Result<()>

Available on Linux and non-target_env=ohos only.

Set the owner of the device.

pub fn group(&self, value: i32) -> Result<()>

Available on Linux and non-target_env=ohos only.

Set the group of the device.

pub fn send_multiple<B: ExpandBuffer>( &self, gro_table: &mut GROTable, bufs: &mut [B], offset: usize, ) -> Result<usize>

Available on Linux and non-target_env=ohos only.

send multiple fragmented data packets. GROTable can be reused, as it is used to assist in data merging. Offset is the starting position of the data. Need to meet offset>=10.

pub fn recv_multiple<B: AsRef<[u8]> + AsMut<[u8]>>( &self, original_buffer: &mut [u8], bufs: &mut [B], sizes: &mut [usize], offset: usize, ) -> Result<usize>

Available on Linux and non-target_env=ohos only.

Recv a packet from tun device. If offload is enabled. This method can be used to obtain processed data.

original_buffer is used to store raw data, including the VirtioNetHdr and the unsplit IP packet. The recommended size is 10 + 65535. bufs and sizes are used to store the segmented IP packets. bufs.len == sizes.len > 65535/MTU offset: Starting position

pub fn remove_address_v6_impl(&self, addr: Ipv6Addr, prefix: u8) -> Result<()>

Available on Linux and non-target_env=ohos only.

pub fn name(&self) -> Result<String>

Available on Linux and non-target_env=ohos only.

Retrieves the name of the network interface.

pub fn remove_address_v6(&self, addr: Ipv6Addr, prefix: u8) -> Result<()>

Available on Linux and non-target_env=ohos only.

pub fn set_name(&self, value: &str) -> Result<()>

Available on Linux and non-target_env=ohos only.

Sets a new name for the network interface.

This function converts the provided name into a C-compatible string, checks that its length does not exceed the maximum allowed (IFNAMSIZ), and then copies it into an interface request structure. It then uses a system call (via siocsifname) to apply the new name.

pub fn is_running(&self) -> Result<bool>

Available on Linux and non-target_env=ohos only.

Checks whether the network interface is currently running.

The interface is considered running if both the IFF_UP and IFF_RUNNING flags are set.

pub fn enabled(&self, value: bool) -> Result<()>

Available on Linux and non-target_env=ohos only.

Enables or disables the network interface.

If value is true, the interface is enabled by setting the IFF_UP and IFF_RUNNING flags. If false, the IFF_UP flag is cleared. The change is applied using a system call.

pub fn broadcast(&self) -> Result<IpAddr>

Available on Linux and non-target_env=ohos only.

Retrieves the broadcast address of the network interface.

This function populates an interface request with the broadcast address via a system call, converts it into a sockaddr structure, and then extracts the IP address.

pub fn set_broadcast(&self, value: IpAddr) -> Result<()>

Available on Linux and non-target_env=ohos only.

Sets the broadcast address of the network interface.

This function converts the given IP address into a sockaddr structure (with a specified overwrite size) and then applies it to the interface via a system call.

pub fn set_network_address<IPv4: ToIpv4Address, Netmask: ToIpv4Netmask>( &self, address: IPv4, netmask: Netmask, destination: Option<IPv4>, ) -> Result<()>

Available on Linux and non-target_env=ohos only.

Sets the IPv4 network address, netmask, and an optional destination address. Remove all previous set IPv4 addresses and set the specified address.

pub fn add_address_v4<IPv4: ToIpv4Address, Netmask: ToIpv4Netmask>( &self, address: IPv4, netmask: Netmask, ) -> Result<()>

Available on Linux and non-target_env=ohos only.

Add IPv4 network address, netmask

pub fn remove_address(&self, addr: IpAddr) -> Result<()>

Available on Linux and non-target_env=ohos only.

Removes an IP address from the interface.

For IPv4 addresses, it iterates over the current addresses and if a match is found, resets the address to 0.0.0.0 (unspecified). For IPv6 addresses, it retrieves the interface addresses by name and removes the matching address, taking into account its prefix length.

pub fn add_address_v6<IPv6: ToIpv6Address, Netmask: ToIpv6Netmask>( &self, addr: IPv6, netmask: Netmask, ) -> Result<()>

Available on Linux and non-target_env=ohos only.

Adds an IPv6 address to the interface.

This function creates an in6_ifreq structure, fills in the interface index, prefix length, and IPv6 address (converted into a sockaddr structure), and then applies it using a system call.

pub fn mtu(&self) -> Result<u16>

Available on Linux and non-target_env=ohos only.

Retrieves the current MTU (Maximum Transmission Unit) for the interface.

This function constructs an interface request and uses a system call (via siocgifmtu) to obtain the MTU. The result is then converted to a u16.

pub fn set_mtu(&self, value: u16) -> Result<()>

Available on Linux and non-target_env=ohos only.

Sets the MTU (Maximum Transmission Unit) for the interface.

This function creates an interface request, sets the ifru_mtu field to the new value, and then applies it via a system call.

pub fn set_mac_address(&self, eth_addr: [u8; 6]) -> Result<()>

Available on Linux and non-target_env=ohos only.

Sets the MAC (hardware) address for the interface.

This function constructs an interface request and copies the provided MAC address into the hardware address field. It then applies the change via a system call. This operation is typically supported only for TAP devices.

pub fn mac_address(&self) -> Result<[u8; 6]>

Available on Linux and non-target_env=ohos only.

Retrieves the MAC (hardware) address of the interface.

This function queries the MAC address by the interface name using a helper function. An error is returned if the MAC address cannot be found.

Trait Implementations

impl Deref for BorrowedSyncDevice<'_>

type Target = SyncDevice

The resulting type after dereferencing.

fn deref(&self) -> &Self::Target

Dereferences the value.