sd_hwdb_get(3) — Linux manual page

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | NOTES | EXAMPLES | SEE ALSO | COLOPHON

SD_HWDB_GET(3)                 sd_hwdb_get                SD_HWDB_GET(3)

NAME         top

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

SYNOPSIS         top

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

       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.

RETURN VALUE         top

       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.

       -ENOENT
           An entry for the specified modalias was not found.

       -EAGAIN
           sd_hwdb_seek() was not called before sd_hwdb_enumerate().

NOTES         top

       These APIs are implemented as a shared library, which can be
       compiled and linked to with the libsystemd pkg-config(1) file.

EXAMPLES         top

       Example 1. Look up hwdb entries for a USB device

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

           #include <stdio.h>
           #include <stdint.h>
           #include <sd-hwdb.h>

           int print_usb_properties(uint16_t vid, uint16_t pid) {
             char match[STRLEN("usb:vp") + DECIMAL_STR_MAX(uint16_t) * 2];
             sd_hwdb *hwdb;
             const char *key, *value;
             int r;

             /* Match this USB vendor and product ID combination */
             xsprintf(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.

SEE ALSO         top

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

COLOPHON         top

       This page is part of the systemd (systemd system and service
       manager) project.  Information about the project can be found at
       ⟨http://www.freedesktop.org/wiki/Software/systemd⟩.  If you have
       a bug report for this manual page, see
       ⟨http://www.freedesktop.org/wiki/Software/systemd/#bugreports⟩.
       This page was obtained from the project's upstream Git repository
       ⟨https://github.com/systemd/systemd.git⟩ on 2022-12-17.  (At that
       time, the date of the most recent commit that was found in the
       repository was 2022-12-16.)  If you discover any rendering
       problems in this HTML version of the page, or you believe there
       is a better or more up-to-date source for the page, or you have
       corrections or improvements to the information in this COLOPHON
       (which is not part of the original manual page), send a mail to
       man-pages@man7.org

systemd 252                                               SD_HWDB_GET(3)

Pages that refer to this page: sd-hwdb(3)sd_hwdb_new(3)systemd.directives(7)systemd.index(7)