sd_hwdb_get, sd_hwdb_seek, sd_hwdb_enumerate, SD_HWDB_FOREACH_PROPERTY - Seek to a location in hwdb or

Description

sd_hwdb_get() queries the hwdb object created earlier with 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) 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) 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.

Examples

Example1.LookuphwdbentriesforaUSBdevice /* 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-hwdbqueryusb:v046DpC534.

History

sd_hwdb_get(), sd_hwdb_seek(), sd_hwdb_enumerate(), and SD_HWDB_FOREACH_PROPERTY() were added in version 246.

Name

sd_hwdb_get, sd_hwdb_seek, sd_hwdb_enumerate, SD_HWDB_FOREACH_PROPERTY - Seek to a location in hwdb or access entries

Notes

Functions described here are available as a shared library, which can be compiled against and linked to with the libsystemdpkg-config(1) file. The code described here uses 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) 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.

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. -EAGAINsd_hwdb_seek() was not called before sd_hwdb_enumerate(). Added in version 246.

Synopsis

#include<systemd/sd-hwdb.h>intsd_hwdb_get(sd_hwdb*hwdb,constchar*modalias,constchar*key,constchar**value);intsd_hwdb_seek(sd_hwdb*hwdb,constchar*modalias);intsd_hwdb_enumerate(sd_hwdb*hwdb,constchar**key,constchar**value);SD_HWDB_FOREACH_PROPERTY(hwdb,modalias,key,value);