SD_DEVICE_GET_SYSPATH(3)

📦
version 261.3 · 14 versions
, in ubuntu stonking

💅 sd_device_get_syspath(3) — the sd_device_get_* girlies ✨

okay so this is one of those sd-device manual pages, bestie — section 3, the library-call section, and it's literally a whole little family of functions that just... hand you fields off a device object. no cap. let's get into it 🫶

🌸 NAME 🌸

sd_device_get_syspath, sd_device_get_devpath, sd_device_get_sysname, sd_device_get_sysnum, sd_device_get_subsystem, sd_device_get_driver_subsystem, sd_device_get_devtype, sd_device_get_devname, sd_device_get_devnum, sd_device_get_ifindex, sd_device_get_driver, sd_device_get_diskseq, sd_device_get_device_id — these all just return various fields of device objects. that's the whole gig. like a little vending machine of device metadata 💖

✨ SYNOPSIS ✨

#include <systemd/sd-device.h>

int sd_device_get_syspath(sd_device *device, const char **ret);

int sd_device_get_devpath(sd_device *device, const char **ret);

int sd_device_get_sysname(sd_device *device, const char **ret);

int sd_device_get_sysnum(sd_device *device, const char **ret);

int sd_device_get_subsystem(sd_device *device, const char **ret);

int sd_device_get_driver_subsystem(sd_device *device, const char **ret);

int sd_device_get_devtype(sd_device *device, const char **ret);

int sd_device_get_devname(sd_device *device, const char **ret);

int sd_device_get_devnum(sd_device *device, dev_t *ret);

int sd_device_get_ifindex(sd_device *device, int *ret);

int sd_device_get_driver(sd_device *device, const char **ret);

int sd_device_get_diskseq(sd_device *device, uint64_t *ret);

int sd_device_get_device_id(sd_device *device, const char **ret);

🦋 DESCRIPTION 🦋

so every single one of these takes your sd_device *device and drops the answer into ret. and like, the type of ret matters — some are const char **, some are dev_t *, one is int *, one is uint64_t *. read the synopsis, don't be feral about it 😭

  • sd_device_get_syspath() — gives you the sysfs path of the device record, and yes it includes the /sys prefix. example: /sys/devices/virtual/tty/tty7 💅
  • sd_device_get_devpath() — same sysfs path, but this time excluding the /sys prefix. example: /devices/virtual/tty/tty7
  • sd_device_get_sysname() — the sysfs name, aka the last component of the sysfs path. example: "tty7" for the device /sys/devices/virtual/tty/tty7 ✨
  • sd_device_get_sysnum() — the sysfs device number, aka the numeric suffix of the last component of the sysfs path. example: "7" for the device /sys/devices/virtual/tty/tty7 🔢
  • sd_device_get_subsystem() — the kernel subsystem of the device record. it's a short string that fits into a filename, so it has no slash in it and it can't be empty, periodt. example: "tty", "block" or "net" 💖
  • sd_device_get_driver_subsystem() — the connected bus type of the devices loaded by this driver device record. like, when you pass the "iwlwifi" driver device (which is what the wireless network interfaces on the PCI bus use), this returns "pci". heads up tho: this only succeeds when sd_device_get_subsystem() returns "drivers". example: "pci", "i2c", or "hid" 🚌
  • sd_device_get_devtype() — the device type of the record, but only if the subsystem manages multiple types of devices. example: for devices of the "block" subsystem this can be "disk" or "partition" 🎀
  • sd_device_get_devname() — the device node path, if the device even has a device node. example: for /sys/devices/virtual/tty/tty7 you'd typically get back the string /dev/tty7 🎯
  • sd_device_get_devnum() — the device node major/minor (i.e. dev_t) of the record, if the device has a device node (the one sd_device_get_devname() returns, iykyk). for "block" subsystem devices this refers to a block device node; in all other cases it's a character device node. example: for the /sys/devices/virtual/tty/tty7 device this typically returns the device number with major/minor "4:7" 🔥
  • sd_device_get_ifindex() — the network interface index, if the device encapsulates a network interface device, i.e. it belongs to the "net" subsystem. example: the "lo" interface typically has interface index 1 🌐
  • sd_device_get_driver() — the kernel driver name attached to the device. lowkey important note: the driver field is set on the devices consumed by the driver, not on the device created by it. example: a PCI device /sys/bus/pci/devices/0000:00:1f.6 might be attached to a driver "e1000e" 🚗
  • sd_device_get_diskseq() — the kernel disk sequence number of the block device. this number monotonically increases whenever a backing medium of a block device changes without the device name changing, and it's relevant for block devices encapsulating devices with changing media (e.g. floppy or CD-ROM), or loopback block devices. and it is only defined for block devices, i.e. those of subsystem "block" — so don't come asking for it on anything else 🙈
  • sd_device_get_device_id() — the short string identifying the device record. and the slay part? when you pass the device ID you got from this function into sd_device_new_from_device_id(), you get a new instance of the same device record back. iconic. the format depends on the device:
    • for a block or character device that has a corresponding device node: "b" or "c" respectively, followed by the device node major and minor numbers separated with a colon. example: "b259:1" or "c10:121"
    • for a network interface device: "n" followed by the interface index, which you can get with sd_device_get_ifindex(). example: "n1"
    • for a device in the "driver" subsystem: "+drivers:" followed by its driver subsystem and sysfs name separated with a colon. example: "+drivers:pci:iwlwifi" for a driver device record whose driver subsystem is "pci" and sysfs name is "iwlwifi"
    • for another type of device: "+" followed by its subsystem and sysfs name separated with a colon. example: "+acpi:ACPI0003:00", "+input:input16", or "+pci:0000:00:1f.6" 👑

🌈 RETURN VALUE 🌈

on success these calls return 0 or a positive integer. on failure they return a negative errno-style error code. that's it, that's the contract 💜

💀 Errors

the errors you might get back mean the following:

  • -EINVAL — a specified parameter is invalid.
added in version 251 🎀
  • -ENOENT — the requested field is not present in the device record.
added in version 251 🎀

🧚 NOTES 🧚

these functions are available as a shared library, and you can compile against and link to it with the libsystemd pkg-config(1) file. standard systemd girlie behaviour ✨

also — and this one actually matters, so listen up — the code described here uses getenv(3), which is declared to be not multi-thread-safe. that means any code calling these functions must not call setenv(3) from a parallel thread 😭 the recommendation is to only do your setenv() calls in an early phase of the program, when no other threads have been started. fr fr, don't skip this one.

👑 HISTORY 👑

sd_device_get_syspath(), sd_device_get_devpath(), sd_device_get_sysname(), sd_device_get_sysnum(), sd_device_get_subsystem(), sd_device_get_devtype(), sd_device_get_devname(), sd_device_get_devnum(), sd_device_get_ifindex(), sd_device_get_driver(), and sd_device_get_diskseq() were added in version 251. the OGs 💖

sd_device_get_driver_subsystem() and sd_device_get_device_id() were added in version 257. the newer iconiques 🦋

🌸 SEE ALSO 🌸

okay that's the whole page bestie, go read your device fields in peace 🫶 this was systemd 261.3 — mwah, catch you on the next manpage 💅✨🎀

📦 where this page comes from