Struct Device

pub struct Device { /* private fields */ }

A structure that provides access to sysfs/kernel devices.

Implementations

impl Device

pub fn from_syspath(syspath: &Path) -> Result<Self>

Creates a device for a given syspath.

The syspath parameter should be a path to the device file within the sysfs file system, e.g., /sys/devices/virtual/tty/tty0.

pub fn from_syspath_with_context(udev: Udev, syspath: &Path) -> Result<Self>

Creates a device for a given syspath, using an existing Udev instance rather than creating one automatically.

The syspath parameter should be a path to the device file within the sysfs file system, e.g., /sys/devices/virtual/tty/tty0.

pub fn from_subsystem_sysname( subsystem: String, sysname: String, ) -> Result<Self>

Create new udev device, and fill in information from the sys device and the udev database entry.

The device is looked up by the subsystem and sysname string of the device, like “mem” / “zero”, or “block” / “sda”.

pub fn from_subsystem_sysname_with_context( udev: Udev, subsystem: String, sysname: String, ) -> Result<Self>

Create new udev device, and fill in information from the sys device and the udev database entry, using an existing Udev instance rather than creating a new one.

The device is looked up by the subsystem and sysname string of the device, like “mem” / “zero”, or “block” / “sda”.

pub fn from_devnum(dev_type: DeviceType, devnum: dev_t) -> Result<Self>

Creates a rust udev Device for a given UNIX device “special file” type and number.

The dev_type parameter indicates which of the historical UNIX file-like I/O paradigms the device permits, and is either DeviceType::Character or DeviceType::Block.

n.b. This function follows the naming used by the underlying libudev function. As with the underlying function, there is no direct correspondence between this function’s dev_type parameter and string values returned by devtype. i.e. They represent different underlying concepts within the OS kernel.

The devnum parameter is of type [libc::dev_t][libc::dev_t] which encodes the historical UNIX major and minor device numbers (see below).

Typically both parameters would be determined at run-time by calling one of the stat family of system calls (or Rust std library functions which utilise them) on a filesystem “special file” inode (e.g. /dev/null) or (more commonly) on a symbolic link to such a file which was created by the udevd system daemon such as those under /dev/disk/.

use std::{env, fs, os::linux::fs::MetadataExt};
use udev::DeviceType;

fn main() -> std::io::Result<()> {
    let args: Vec<String> = env::args().collect();
    let path = args.get(1).expect("No filename given");
    let metadata = fs::metadata(path).unwrap_or_else(|_| panic!("Can't open file: {}", path));
    let devtype = match metadata.st_mode() & libc::S_IFMT {
        libc::S_IFCHR => Some(DeviceType::Character),
        libc::S_IFBLK => Some(DeviceType::Block),
        _ => None,
    }.expect("Not a character or block special file");
    let ud = udev::Device::from_devnum(devtype, metadata.st_rdev())
        .expect("Couldn't construct udev from supplied path");
    println!("syspath of {} is {:?}", path, ud.syspath());
    let dn = ud.devnum();
    println!("devnum: {}", dn.unwrap());
    Ok(())
}

The user should be aware that a given device may change its major and/or minor number across reboots, when the hardware attached to the device is subject to hot-plug events, or for a variety of other reasons.

The udevd system daemon (or equivalent) is configured to dynamically create filesystem symbolic links (examples of which can be seen under e.g. /dev/disk/by-id/ on most Linux systems), the purpose of which is to provide a predictable and persistent means of identifying devices which themselves have a persistent state or identity.

Code similar to the sample presented above may be used to obtain a udev::Device corresponding to the filesystem path of the UNIX file I/O style device node or symbolic link.

Historical UNIX systems statically allocated their internal data structures which were associated with devices that exposed a “file-like” user-space API (e.g. /dev/null). A device could be uniquely and persistently identified by combining its type (either “character” or “block”), with its major and minor device numbers.

In the underlying OS kernel, a major number might be allocated to a single device driver such as a SCSI disk controller, and that device driver would allocate the minor device number (e.g. 4 might have represented the 4th SCSI device addressable by a particular SCSI host adapter). The mknod system utility would be used to create friendly filesystem paths in the filesystem, which corresponded with these attributes, and file permissions would be managed with utilities such as chown and chmod etc. and the numbers would not change between system reboots.

As has been noted, modern UNIX-like operating systems dynamically allocate devices. To provide backward compatibility with existing user-space APIs, the concept of major/minor devices being associated with file system “special file” inodes has been retained.

For udev devices which present a UNIX file I/O style interface (i.e. via /dev/ paths), the Linux udevadm utility currently reports devices belonging to the "block" subsystem to be of type “block”, and all other file I/O style udev devices to be of type “character”.

Those needing to compose or decompose values of type dev_t should refer to [libc::major], [libc::minor], [libc::makedev] and equivalent functionality from higher-level rust crates.

pub fn from_devnum_with_context( udev: Udev, dev_type: DeviceType, devnum: dev_t, ) -> Result<Self>

Creates a rust udev Device for a given UNIX device “special file” type and number. Uses an existing Udev instance rather than creating one automatically.

See from_devnum for detailed usage.

pub fn is_initialized(&self) -> bool

Checks whether the device has already been handled by udev.

When a new device is connected to the system, udev initializes the device by setting permissions, renaming network devices, and possibly other initialization routines. This method returns true if udev has performed all of its work to initialize this device.

This method only applies to devices with device nodes or network interfaces. All other devices return true by default.

pub fn devnum(&self) -> Option<dev_t>

Gets the device’s major/minor number.

pub fn syspath(&self) -> &Path

Returns the syspath of the device.

The path is an absolute path and includes the sys mount point. For example, the syspath for tty0 could be /sys/devices/virtual/tty/tty0, which includes the sys mount point, /sys.

pub fn devpath(&self) -> &OsStr

Returns the kernel devpath value of the device.

The path does not contain the sys mount point, but does start with a /. For example, the devpath for tty0 could be /devices/virtual/tty/tty0.

pub fn devnode(&self) -> Option<&Path>

Returns the path to the device node belonging to the device.

The path is an absolute path and starts with the device directory. For example, the device node for tty0 could be /dev/tty0.

pub fn parent(&self) -> Option<Self>

Returns the parent of the device.

pub fn parent_with_subsystem<T: AsRef<OsStr>>( &self, subsystem: T, ) -> Result<Option<Self>>

Returns the parent of the device with the matching subsystem and devtype if any.

pub fn parent_with_subsystem_devtype<T: AsRef<OsStr>, U: AsRef<OsStr>>( &self, subsystem: T, devtype: U, ) -> Result<Option<Self>>

Returns the parent of the device with the matching subsystem and devtype if any.

pub fn subsystem(&self) -> Option<&OsStr>

Returns the subsystem name of the device.

The subsystem name is a string that indicates which kernel subsystem the device belongs to. Examples of subsystem names are tty, vtconsole, block, scsi, and net.

pub fn sysname(&self) -> &OsStr

Returns the kernel device name for the device.

The sysname is a string that differentiates the device from others in the same subsystem. For example, tty0 is the sysname for a TTY device that differentiates it from others, such as tty1.

pub fn sysnum(&self) -> Option<usize>

Returns the instance number of the device.

The instance number is used to differentiate many devices of the same type. For example, /dev/tty0 and /dev/tty1 are both TTY devices but have instance numbers of 0 and 1, respectively.

Some devices don’t have instance numbers, such as /dev/console, in which case the method returns None.

pub fn devtype(&self) -> Option<&OsStr>

Returns the devtype name of the device (if any), for example “disk”.

pub fn driver(&self) -> Option<&OsStr>

Returns the name of the kernel driver attached to the device.

pub fn property_value<T: AsRef<OsStr>>(&self, property: T) -> Option<&OsStr>

Retrieves the value of a device property.

pub fn attribute_value<T: AsRef<OsStr>>(&self, attribute: T) -> Option<&OsStr>

Retrieves the value of a device attribute.

pub fn set_attribute_value<T: AsRef<OsStr>, U: AsRef<OsStr>>( &mut self, attribute: T, value: U, ) -> Result<()>

Sets the value of a device attribute.

pub fn properties(&self) -> Properties<'_>

Returns an iterator over the device’s properties.

Example

This example prints out all of a device’s properties:

for property in device.properties() {
    println!("{:?} = {:?}", property.name(), property.value());
}

pub fn attributes(&self) -> Attributes<'_>

Returns an iterator over the device’s attributes.

Example

This example prints out all of a device’s attributes:

for attribute in device.attributes() {
    println!("{:?} = {:?}", attribute.name(), attribute.value());
}

pub fn action(&self) -> Option<&OsStr>

Returns the device action for the device.

Trait Implementations

impl AsRawWithContext<udev_device> for Device

fn as_raw(&self) -> *mut udev_device

Get a reference of the underlying struct.

fn udev(&self) -> &Udev

The udev context with which this struct was created. This must live at least as long as the struct itself or undefined behavior will result.

fn into_raw_with_context(self) -> (*mut udev, *mut udev_device)

Convert the object into the raw udev pointer and the underlying pointer for this object.

impl Clone for Device

fn clone(&self) -> Self

Returns a copy of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for Device

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

Formats the value using the given formatter.

impl Drop for Device

fn drop(&mut self)

Executes the destructor for this type.

impl FromRawWithContext<udev_device> for Device

unsafe fn from_raw_with_context(udev: *mut udev, t: *mut udev_device) -> Self

Create an object from a given raw pointer and udev context pointer.