SD\_HWDB\_GET(3) sd\_hwdb\_get SD\_HWDB\_GET(3)

.SH "NAME" sd\_hwdb\_get, sd\_hwdb\_seek, sd\_hwdb\_enumerate, SD\_HWDB\_FOREACH\_PROPERTY - Seek to a location in hwdb or access entries

.SH "SYNOPSIS"

```
#include <systemd/sd-hwdb.h>
```

.HP 384u **int sd\_hwdb\_get(sd\_hwdb \*hwdb, const char \*modalias, const char \*key, const char \*\*value);**

.HP 408u **int sd\_hwdb\_seek(sd\_hwdb \*hwdb, const char \*modalias);**

.HP 528u **int sd\_hwdb\_enumerate(sd\_hwdb \*hwdb, const char \*\*key, const char \*\*value);**

.HP 600u **SD\_HWDB\_FOREACH\_PROPERTY(hwdb, modalias, key, value);**

.SH "DESCRIPTION"

.PP **sd\_hwdb\_get()** queries the *hwdb* object created earlier with [**sd\_hwdb\_new**(3)](/man/os/systemd/sd_hwdb_new.3) for entries matching the specified string *modalias*, and returns the value corresponding to the key *key*. The value is returned as a **NUL**-terminated string in *value*. It must not be modified by the caller and is valid as long as a reference to *hwdb* is kept. When multiple patterns in the database match *modalias*, the one with the highest priority is used. See [**hwdb**(7)](/man/os/systemd/hwdb.7) for details.

.PP **sd\_hwdb\_seek()** selects entries matching the specified string *modalias*. Subsequent queries with **sd\_hwdb\_enumerate()** will access the key-value pairs for that string.

.PP **sd\_hwdb\_enumerate()** returns (in turn) all the key-value pairs defined for the string used with **sd\_hwdb\_seek()**. Each pair is returned as **NUL**-terminated strings in *key* and *value*. The strings must not be modified by the caller and are valid as long as a reference to *hwdb* is kept. When multiple patterns in the database match *modalias*, the combination of all matching key-value pairs is used. See [**hwdb**(7)](/man/os/systemd/hwdb.7) for details.

.PP The **SD\_HWDB\_FOREACH\_PROPERTY()** macro combines **sd\_hwdb\_seek()** and **sd\_hwdb\_enumerate()**. No error handling is performed and iteration simply stops on error. See the example below.

.SH "RETURN VALUE"

.PP On success, **sd\_hwdb\_get()** and **sd\_hwdb\_seek()** return a non-negative integer. On failure, they return a negative errno-style error code.

.PP **sd\_hwdb\_enumerate()** returns a positive integer if another key-value pair was found or zero if all entries have already been enumerated. On failure, it returns a negative errno-style error code.

.SS "Errors"

.PP Returned errors may indicate the following problems:

.PP **-EINVAL**

A parameter is **NULL**.

Added in version 246.

.RE

.PP **-ENOENT**

An entry for the specified *modalias* was not found.

Added in version 246.

.RE

.PP **-EAGAIN**

**sd\_hwdb\_seek()** was not called before **sd\_hwdb\_enumerate()**.

Added in version 246.

.RE

.SH "NOTES"

.PP Functions described here are available as a shared library, which can be compiled against and linked to with the **libsystemd** [**pkg-config**(1)](/man/os/systemd/pkg-config.1) file.

.PP The code described here uses [**getenv**(3)](/man/os/systemd/getenv.3), which is declared to be not multi-thread-safe. This means that the code calling the functions described here must not call [**setenv**(3)](/man/os/systemd/setenv.3) from a parallel thread. It is recommended to only do calls to **setenv()** from an early phase of the program when no other threads have been started.

.SH "EXAMPLES"

.PP **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;
}
```

.PP The effect is similar to calling **systemd-hwdb query usb:v046DpC534**.

.SH "HISTORY"

.PP **sd\_hwdb\_get()**, **sd\_hwdb\_seek()**, **sd\_hwdb\_enumerate()**, and **SD\_HWDB\_FOREACH\_PROPERTY()** were added in version 246.

.SH "SEE ALSO"

.PP [**systemd**(1)](/man/os/systemd/systemd.1), [**systemd-udevd.service**(8)](/man/os/systemd/systemd-udevd.service.8), [**sd-hwdb**(3)](/man/os/systemd/sd-hwdb.3), [**systemd-hwdb**(8)](/man/os/systemd/systemd-hwdb.8)

systemd 262.2

---

Document: sd_hwdb_get(3) from systemd 262.2-r1 (Chainguard OS)
Source: https://github.com/systemd/systemd