SD_HWDB_GET(3)

💅 sd_hwdb_get — the hwdb girlies' guide

okay so bestie, this page is sd_hwdb_get(3) from the sd_hwdb_get manual family, and it's literally the whole "look stuff up in the hardware database" situation. sit down, hydrate, let's go 🫶

---

✨ NAME ✨

sd_hwdb_get, sd_hwdb_seek, sd_hwdb_enumerate, SD_HWDB_FOREACH_PROPERTY — the four functions/macros that let you seek to a location in hwdb or access entries. that's the whole vibe check.

---

🌸 SYNOPSIS 🌸

#include <systemd/sd-hwdb.h>

int sd_hwdb_get(sd_hwdb *hwdb, const char *modalias, const char *key,
                const char **value);

int sd_hwdb_seek(sd_hwdb *hwdb, const char *modalias);

int sd_hwdb_enumerate(sd_hwdb *hwdb, const char **key,
                      const char **value);

SD_HWDB_FOREACH_PROPERTY(hwdb, modalias, key, value);

---

🦋 DESCRIPTION 🦋

So. sd_hwdb_get() queries the hwdb object you already made earlier with sd_hwdb_new(3) — it goes looking for entries matching the string modalias and hands you back the value that corresponds to the key key. That value comes back as a NUL-terminated string in value. 🎀

⚠️ bestie, listen: that string must not be modified by the caller, and it's only valid as long as you keep a reference to hwdb. keep the ref alive, keep the string alive. periodt.

When multiple patterns in the database match modalias, the one with the highest priority wins. that's the rule. See hwdb(7) for details — iykyk.

sd_hwdb_seek() picks out the entries matching your modalias string. after that, all your sd_hwdb_enumerate() calls will walk through the key-value pairs for that string. it's giving "setting the scene" ✨

sd_hwdb_enumerate() returns — in turn, one at a time, no skipping — all the key-value pairs defined for the string you passed to sd_hwdb_seek(). each pair lands in key and value as NUL-terminated strings. same deal as before: don't modify them, and they're valid as long as you keep a reference to hwdb. and when multiple patterns match modalias, the combo of all matching key-value pairs gets used (not just one — different from sd_hwdb_get(), no cap). See hwdb(7) for details.

The SD_HWDB_FOREACH_PROPERTY() macro is the icon that just glues sd_hwdb_seek() and sd_hwdb_enumerate() together for you. heads up though: no error handling is performed, iteration just... stops on error. 💀 it doesn't complain, it doesn't return anything to you, it simply stops. check the example below for the ~vibes~.

---

⭐ RETURN VALUE ⭐

On success, sd_hwdb_get() and sd_hwdb_seek() return a non-negative integer. on failure they return a negative errno-style error code.

sd_hwdb_enumerate() is the quirky one: it returns a positive integer if another key-value pair was found, or zero if you've already enumerated everything. on failure? yep, negative errno-style error code. 😭

🙈 Errors

the errors it might throw at you mean the following, bestie:

• -EINVAL — a parameter is NULL. classic. 🫠

Added in version 246.

• -ENOENT — an entry for the specified modalias was not found. it's not there, babe. it's simply not there.

Added in version 246.

• -EAGAIN — sd_hwdb_seek() was not called before sd_hwdb_enumerate(). you skipped a step!! you can't enumerate what you didn't seek 💀

Added in version 246.

---

🧚 NOTES 🧚

the functions described here are available as a shared library, which you can compile against and link to with the libsystemd pkg-config(1) file. slay, standard systemd behaviour.

The code described here uses getenv(3), which is declared to be not multi-thread-safe. so: the code calling these functions must not call setenv(3) from a parallel thread. the recommendation is to only call setenv() from an early phase of the program, when no other threads have been started. like, do it before the party starts, not mid-party. 🎀

---

🔥 EXAMPLES 🔥

Example 1. Look up hwdb entries for a USB device

/* SPDX-License-Identifier: MIT-0 */

#define _GNU_SOURCE 1
#include <stdio.h>
#include <stdint.h>
#include <systemd/sd-hwdb.h>

int print_usb_properties(uint16_t vid, uint16_t pid) {
  char match[128];
  sd_hwdb *hwdb;
  const char *key, *value;
  int r;

  /* Match this USB vendor and product ID combination */
  snprintf(match, sizeof match, "usb:v%04Xp%04X", vid, pid);

  r = sd_hwdb_new(&hwdb);
  if (r < 0)
    return r;

  SD_HWDB_FOREACH_PROPERTY(hwdb, match, key, value)
    printf("%s: \"%s\" → \"%s\"\n", match, key, value);

  sd_hwdb_unref(hwdb);
  return 0;
}

int main(int argc, char **argv) {
  print_usb_properties(0x046D, 0xC534);
  return 0;
}

the effect is similar to calling systemd-hwdb query usb:v046DpC534. same energy, different entry point. 💅

---

👑 HISTORY 👑

sd_hwdb_get(), sd_hwdb_seek(), sd_hwdb_enumerate(), and SD_HWDB_FOREACH_PROPERTY() were all added in version 246. glow-up complete.

---

🌈 SEE ALSO 🌈

systemd(1), systemd-udevd.service(8), sd-hwdb(3), systemd-hwdb(8)

---

okay that's the whole page bestie, go query some hardware 🍓

💖 this has been SD_HWDB_GET(3) from systemd 261.3 — mwah, hope this helped, ily, bye 🫶✨