From c11edfee986ecef0cacd803e65b5a26373db87af Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Zbigniew=20J=C4=99drzejewski-Szmek?= Date: Mon, 20 Apr 2020 20:45:14 +0200 Subject: [PATCH 1/5] man: document sd_journal_*_with_location --- man/rules/meson.build | 7 +++- man/sd_journal_print.xml | 88 ++++++++++++++++++++++++++++++++++------ 2 files changed, 81 insertions(+), 14 deletions(-) diff --git a/man/rules/meson.build b/man/rules/meson.build index 3b52d33e37..a15a30f67a 100644 --- a/man/rules/meson.build +++ b/man/rules/meson.build @@ -643,9 +643,14 @@ manpages = [ '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_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. From 622018c5b46a98be67e1bc596312b21d5b6bbabf Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Zbigniew=20J=C4=99drzejewski-Szmek?= Date: Mon, 20 Apr 2020 20:47:34 +0200 Subject: [PATCH 2/5] check-api-docs: sd_journal_open_container is deprecated --- tools/meson-check-api-docs.sh | 1 + 1 file changed, 1 insertion(+) 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 From 21dc5e82ade4fa8686d1a118a5091d9abe88e264 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Zbigniew=20J=C4=99drzejewski-Szmek?= Date: Mon, 20 Apr 2020 20:51:12 +0200 Subject: [PATCH 3/5] man: add sd_j_open_namespace as refname This was forgotten in 241c8f67f65a1051068a1728daaca5bc49183c69. --- man/rules/meson.build | 3 ++- man/sd_journal_open.xml | 1 + 2 files changed, 3 insertions(+), 1 deletion(-) diff --git a/man/rules/meson.build b/man/rules/meson.build index a15a30f67a..ef11525ef2 100644 --- a/man/rules/meson.build +++ b/man/rules/meson.build @@ -637,7 +637,8 @@ 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', 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 From ec7ea47dae738b7bd0d52ac4bd5e3e652cea4d4f Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Zbigniew=20J=C4=99drzejewski-Szmek?= Date: Mon, 20 Apr 2020 22:18:33 +0200 Subject: [PATCH 4/5] man: add description of all the sd-hwdb funtions --- man/rules/meson.build | 3 + man/sd-hwdb.xml | 57 ++++++++++++++++++ man/sd_hwdb_get.xml | 132 ++++++++++++++++++++++++++++++++++++++++++ man/sd_hwdb_new.xml | 121 ++++++++++++++++++++++++++++++++++++++ 4 files changed, 313 insertions(+) create mode 100644 man/sd-hwdb.xml create mode 100644 man/sd_hwdb_get.xml create mode 100644 man/sd_hwdb_new.xml diff --git a/man/rules/meson.build b/man/rules/meson.build index ef11525ef2..d3457e7ccc 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', @@ -559,6 +560,8 @@ manpages = [ '3', ['sd_get_machine_names', 'sd_get_sessions', 'sd_get_uids'], 'HAVE_PAM'], + ['sd_hwdb_get', '3', ['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', 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..b5c5b1cc6f --- /dev/null +++ b/man/sd_hwdb_get.xml @@ -0,0 +1,132 @@ + + + + + + + sd_hwdb_get + systemd + + + + sd_hwdb_get + 3 + + + + sd_hwdb_get + sd_hwdb_seek + sd_hwdb_enumerate + + 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 + + + + + + + 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. + + + + 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(). + + + + + + + + + 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 + + + + From 32c4d2ba627b8f5fccba05ca3558782c5d72a78a Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Zbigniew=20J=C4=99drzejewski-Szmek?= Date: Tue, 21 Apr 2020 09:07:08 +0200 Subject: [PATCH 5/5] man: add SD_HWDB_FOREACH_PROPERTY with an example --- man/hwdb-usb-device.c | 28 ++++++++++++++++++++++++++++ man/rules/meson.build | 5 ++++- man/sd_hwdb_get.xml | 25 +++++++++++++++++++++++++ 3 files changed, 57 insertions(+), 1 deletion(-) create mode 100644 man/hwdb-usb-device.c 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 d3457e7ccc..8c20c86544 100644 --- a/man/rules/meson.build +++ b/man/rules/meson.build @@ -560,7 +560,10 @@ manpages = [ '3', ['sd_get_machine_names', 'sd_get_sessions', 'sd_get_uids'], 'HAVE_PAM'], - ['sd_hwdb_get', '3', ['sd_hwdb_enumerate', 'sd_hwdb_seek'], ''], + ['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', diff --git a/man/sd_hwdb_get.xml b/man/sd_hwdb_get.xml index b5c5b1cc6f..58e6e57e0f 100644 --- a/man/sd_hwdb_get.xml +++ b/man/sd_hwdb_get.xml @@ -18,6 +18,7 @@ sd_hwdb_get sd_hwdb_seek sd_hwdb_enumerate + SD_HWDB_FOREACH_PROPERTY Seek to a location in hwdb or access entries @@ -47,6 +48,13 @@ const char **value + + SD_HWDB_FOREACH_PROPERTY + hwdb + modalias + key + value + @@ -75,6 +83,10 @@ 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. @@ -118,6 +130,19 @@ + + Examples + + + Look up hwdb entries for a USB device + + + + The effect is similar to calling systemd-hwdb query usb:v046DpC534. + + + + See Also