# sd_hwdb_get

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



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


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


* * *