---
name: "SD_HWDB_FOREACH_PROPERTY"
section: "3"
platform: "linux"
package: "libsystemd-dev"
version: "257.13-1~deb13u1"
release: "Debian 13 (Trixie)"
platforms: ["linux"]
url: "https://new.carta.tech/sd_hwdb_get"
---

# SD\_HWDB\_FOREACH\_PROPERTY(3)

Seek to a location in hwdb or access entries

Part of [sd\_hwdb\_get(3)](/sd_hwdb_get/3.md).

## NAME

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

## 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

**sd\_hwdb\_get()** queries the *hwdb* object created earlier with [**sd\_hwdb\_new**(3)](/sd_hwdb_new/3.md) 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)](/hwdb/7.md) for details.

**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.

**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)](/hwdb/7.md) for details.

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.

## 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()** 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.

### Errors

Returned errors may indicate the following problems:

**-EINVAL**

A parameter is **NULL**.

Added in version 246.

**-ENOENT**

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

Added in version 246.

**-EAGAIN**

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

Added in version 246.

## NOTES

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

The code described here uses [**getenv**(3)](/getenv/3.md), which is declared to be not multi-thread-safe. This means that the code calling the functions described here must not call [**setenv**(3)](/setenv/3.md) 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.

## 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**.

## HISTORY

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

## SEE ALSO

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