diff --git a/man/hwdb-usb-device.c b/man/hwdb-usb-device.c new file mode 100644 index 0000000000..8a4b86e7bd --- /dev/null +++ b/man/hwdb-usb-device.c @@ -0,0 +1,28 @@ +#include +#include +#include + +int print_usb_properties(uint16_t vid, uint16_t pid) { + char match[15]; + 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; +} diff --git a/man/rules/meson.build b/man/rules/meson.build index 7b5b13b176..222c0d2919 100644 --- a/man/rules/meson.build +++ b/man/rules/meson.build @@ -107,6 +107,7 @@ manpages = [ 'SD_WARNING'], ''], ['sd-event', '3', [], ''], + ['sd-hwdb', '3', [], ''], ['sd-id128', '3', ['SD_ID128_CONST_STR', @@ -563,6 +564,11 @@ manpages = [ '3', ['sd_get_machine_names', 'sd_get_sessions', 'sd_get_uids'], 'HAVE_PAM'], + ['sd_hwdb_get', + '3', + ['SD_HWDB_FOREACH_PROPERTY', 'sd_hwdb_enumerate', 'sd_hwdb_seek'], + ''], + ['sd_hwdb_new', '3', ['sd_hwdb_ref', 'sd_hwdb_unref'], ''], ['sd_id128_get_machine', '3', ['sd_id128_get_boot', @@ -641,15 +647,21 @@ manpages = [ 'sd_journal_open_directory', 'sd_journal_open_directory_fd', 'sd_journal_open_files', - 'sd_journal_open_files_fd'], + 'sd_journal_open_files_fd', + 'sd_journal_open_namespace'], ''], ['sd_journal_print', '3', ['SD_JOURNAL_SUPPRESS_LOCATION', 'sd_journal_perror', + 'sd_journal_perror_with_location', + 'sd_journal_print_with_location', 'sd_journal_printv', + 'sd_journal_printv_with_location', 'sd_journal_send', - 'sd_journal_sendv'], + 'sd_journal_send_with_location', + 'sd_journal_sendv', + 'sd_journal_sendv_with_location'], ''], ['sd_journal_query_unique', '3', diff --git a/man/sd-hwdb.xml b/man/sd-hwdb.xml new file mode 100644 index 0000000000..13552e5846 --- /dev/null +++ b/man/sd-hwdb.xml @@ -0,0 +1,57 @@ + + + + + + + + sd-hwdb + systemd + + + + sd-hwdb + 3 + + + + sd-hwdb + Read-only access to the hardware description database + + + + + #include <systemd/sd-hwdb.h> + + + + pkg-config --cflags --libs libsystemd + + + + + + Description + + sd-hwdb.h allows read-only access the systemd database of hardware properties. + See hwdb7 and + systemd-hwdb8 for more + information about the database. + + See sd_hwdb_new3 + and sd_hwdb_get3 for + information about the functions available. + + + + + + See Also + + systemd1, + systemd-udevd.service8 + + + + diff --git a/man/sd_hwdb_get.xml b/man/sd_hwdb_get.xml new file mode 100644 index 0000000000..58e6e57e0f --- /dev/null +++ b/man/sd_hwdb_get.xml @@ -0,0 +1,157 @@ + + + + + + + sd_hwdb_get + systemd + + + + sd_hwdb_get + 3 + + + + sd_hwdb_get + sd_hwdb_seek + sd_hwdb_enumerate + SD_HWDB_FOREACH_PROPERTY + + Seek to a location in hwdb or access entries + + + + + #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_new3 for + entries matching the specified string modalias, and returns the value + corresponding to the 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 hwdb7 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 + hwdb7 for + details. + + The SD_HWDB_FOREACH_PROPERTY macro combines + sd_hwdb_seek() and sd_hwdb_enumerate(). No error handling is + performed and interation 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. + + + + -ENOENT + + An entry for the specified modalias was not found. + + + + + -EAGAIN + + sd_hwdb_seek() was not called before + sd_hwdb_enumerate(). + + + + + + + + + Examples + + + Look up hwdb entries for a USB device + + + + The effect is similar to calling systemd-hwdb query usb:v046DpC534. + + + + + + See Also + + + systemd1, + systemd-udev.service8, + sd-hwdb3, + systemd-hwdb8 + + + + diff --git a/man/sd_hwdb_new.xml b/man/sd_hwdb_new.xml new file mode 100644 index 0000000000..257b347b9b --- /dev/null +++ b/man/sd_hwdb_new.xml @@ -0,0 +1,121 @@ + + + + + + + sd_hwdb_new + systemd + + + + sd_hwdb_new + 3 + + + + sd_hwdb_new + sd_hwdb_ref + sd_hwdb_unref + + Create a new hwdb object and create or destroy references to it + + + + + #include <systemd/sd-hwdb.h> + + + int sd_hwdb_new + sd_hwdb **hwdb + + + + sd_hwdb* sd_hwdb_ref + sd_hwdb *hwdb + + + + sd_hwdb* sd_hwdb_unref + sd_hwdb *hwdb + + + + + + Description + + sd_hwdb_new() creates a new hwdb object to access the binary hwdb + database. Upon initialization, the file containing the binary representation of the hardware database is + located and opened. The new object is returned in hwdb. + + The hwdb object is reference counted. sd_hwdb_ref() and + sd_hwdb_unref() may be used to get a new reference or destroy an existing reference + to an object. The caller must dispose of the reference acquired with sd_hwdb_new() + by calling sd_hwdb_unref() when done with the object. + + Use + sd_hwdb_seek3, + sd_hwdb_get3, and + sd_hwdb_enumerate3 to + access entries. + + + + Return Value + + On success, sd_hwdb_new() returns a non-negative integer. On + failure, it returns a negative errno-style error code. + + sd_hwdb_ref() always returns the argument. + + + sd_hwdb_unref() always returns NULL. + + + + Errors + + Returned errors may indicate the following problems: + + + + -ENOENT + + The binary hardware database file could not be located. See + systemd-hwdb8 + for more information. + + + + + -EINVAL + + The located binary hardware database file is in an incompatible format. + + + + + -ENOMEM + + Memory allocation failed. + + + + + + + + + See Also + + + systemd1, + systemd-udev.service8, + sd-hwdb3, + systemd-hwdb3 + + + + diff --git a/man/sd_journal_open.xml b/man/sd_journal_open.xml index 9884beae1a..bdece26ccc 100644 --- a/man/sd_journal_open.xml +++ b/man/sd_journal_open.xml @@ -22,6 +22,7 @@ sd_journal_open_directory_fd sd_journal_open_files sd_journal_open_files_fd + sd_journal_open_namespace sd_journal_close sd_journal SD_JOURNAL_LOCAL_ONLY diff --git a/man/sd_journal_print.xml b/man/sd_journal_print.xml index f6973087f3..84adab5c7b 100644 --- a/man/sd_journal_print.xml +++ b/man/sd_journal_print.xml @@ -22,6 +22,12 @@ sd_journal_sendv sd_journal_perror SD_JOURNAL_SUPPRESS_LOCATION + sd_journal_print_with_location + sd_journal_printv_with_location + sd_journal_send_with_location + sd_journal_sendv_with_location + sd_journal_perror_with_location + Submit log entries to the journal @@ -60,6 +66,51 @@ const char *message + + int sd_journal_print_with_location + const char *file + const char *line + const char *func + int priority + const char *format + … + + + + int sd_journal_printv_with_location + int priority + const char *file + const char *line + const char *func + const char *format + va_list ap + + + + int sd_journal_send_with_location + const char *file + const char *line + const char *func + const char *format + … + + + + int sd_journal_sendv_with_location + const char *file + const char *line + const char *func + const struct iovec *iov + int n + + + + int sd_journal_perror_with_location + const char *file + const char *line + const char *func + const char *message + @@ -136,11 +187,20 @@ sd_journal_send("MESSAGE=Hello World, this is PID %lu!", (unsigned long) getpid( "PRIORITY=%i", LOG_INFO, NULL); - Note that these calls implicitly add fields for the source - file, function name and code line where invoked. This is - implemented with macros. If this is not desired, it can be turned - off by defining SD_JOURNAL_SUPPRESS_LOCATION before including - sd-journal.h. + Note that these calls implicitly add fields for the source file, function name and code line where + invoked. This is implemented with macros. If this is not desired, it can be turned off by defining + SD_JOURNAL_SUPPRESS_LOCATION before including sd-journal.h. + + + sd_journal_print_with_location, + sd_journal_printv_with_location, sd_journal_send_with_location, + sd_journal_sendv_with_location, and + sd_journal_perror_with_location are similar to their counterparts without + _with_location, but accept additional parameters to explicitly set the source file + name, function, and line. Those arguments must contain valid journal entries including the variable name, + e.g. CODE_FILE=src/foo.c, CODE_LINE=666, + CODE_FUNC=myfunc. These variants are primarily useful when writing custom wrappers, + for example in bindings for a different language. syslog3 and sd_journal_print() may @@ -163,9 +223,9 @@ sd_journal_send("MESSAGE=Hello World, this is PID %lu!", (unsigned long) getpid( Return Value - The five calls return 0 on success or a negative errno-style error code. The errno3 variable itself is - not altered. + The ten functions return 0 on success or a negative errno-style error code. The + errno3 + variable itself is not altered. If systemd-journald8 @@ -178,15 +238,17 @@ sd_journal_send("MESSAGE=Hello World, this is PID %lu!", (unsigned long) getpid( - sd_journal_sendv() is "async signal safe" in the meaning of signal-safety7. + sd_journal_sendv() and sd_journal_sendv_with_location() + are "async signal safe" in the meaning of + signal-safety7. sd_journal_print, sd_journal_printv, - sd_journal_send, and - sd_journal_perror are - not async signal safe. + sd_journal_send, + sd_journal_perror, + and their counterparts with _with_location + are not async signal safe. diff --git a/tools/meson-check-api-docs.sh b/tools/meson-check-api-docs.sh index adaf23883e..1094101e08 100755 --- a/tools/meson-check-api-docs.sh +++ b/tools/meson-check-api-docs.sh @@ -12,6 +12,7 @@ deprecated=" -e sd_bus_message_get_priority -e sd_bus_message_set_priority -e sd_seat_can_multi_session + -e sd_journal_open_container " for symbol in `nm -g --defined-only "$@" | grep " T " | cut -d" " -f3 | grep -wv $deprecated | sort -u` ; do