From eb74579d096417bcaa8b74d7a3625ba45df97905 Mon Sep 17 00:00:00 2001 From: Daan De Meyer Date: Sat, 11 Apr 2020 21:08:34 +0200 Subject: [PATCH 1/3] meson: Exclude more deprecated functions from check-api-docs --- tools/meson-check-api-docs.sh | 9 ++++++++- 1 file changed, 8 insertions(+), 1 deletion(-) diff --git a/tools/meson-check-api-docs.sh b/tools/meson-check-api-docs.sh index c33672934d..2ba5010876 100755 --- a/tools/meson-check-api-docs.sh +++ b/tools/meson-check-api-docs.sh @@ -6,7 +6,14 @@ sd_total=0 udev_good=0 udev_total=0 -for symbol in `nm -g --defined-only "$@" | grep " T " | cut -d" " -f3 | grep -wv sd_bus_try_close | sort -u` ; do +deprecated=" + -e sd_bus_try_close + -e sd_bus_process_priority + -e sd_bus_message_get_priority + -e sd_bus_message_set_priority +" + +for symbol in `nm -g --defined-only "$@" | grep " T " | cut -d" " -f3 | grep -wv $deprecated | sort -u` ; do if test -f ${MESON_BUILD_ROOT}/man/$symbol.3 ; then echo "✓ Symbol $symbol() is documented." good=1 From 535f1d0492401163ef78c9b2b1e346b456368769 Mon Sep 17 00:00:00 2001 From: Daan De Meyer Date: Sat, 11 Apr 2020 21:09:05 +0200 Subject: [PATCH 2/3] sd-bus: Fix sd_bus_close.xml line wrapping --- man/sd_bus_close.xml | 48 +++++++++++++++++++++++++------------------- 1 file changed, 27 insertions(+), 21 deletions(-) diff --git a/man/sd_bus_close.xml b/man/sd_bus_close.xml index 953f16ac34..8d9bdb4858 100644 --- a/man/sd_bus_close.xml +++ b/man/sd_bus_close.xml @@ -48,39 +48,44 @@ Description - sd_bus_close() disconnects the specified bus connection. When this call is invoked and - the specified bus object refers to an active connection it is immediately terminated. No further messages may be - sent or received on it. Any messages queued in the bus object (both incoming and outgoing) are released. If - invoked on NULL bus object or when the bus connection is already closed this function executes - no operation. This call does not free or unreference the bus object itself. Use - sd_bus_unref3 for that. + sd_bus_close() disconnects the specified bus connection. When this + call is invoked and the specified bus object refers to an active connection it is immediately + terminated. No further messages may be sent or received on it. Any messages queued in the bus + object (both incoming and outgoing) are released. If invoked on NULL bus + object or when the bus connection is already closed this function executes no operation. This + call does not free or unreference the bus object itself. Use + sd_bus_unref3 + for that. - sd_bus_flush() synchronously writes out all outgoing queued message on a bus connection - if there are any. This function call may block if the peer is not processing bus messages quickly. + sd_bus_flush() synchronously writes out all outgoing queued message + on a bus connection if there are any. This function call may block if the peer is not processing + bus messages quickly. Before a program exits it is usually a good idea to flush any pending messages with - sd_bus_flush() and then close connections with sd_bus_close() to ensure - that no unwritten messages are lost, no further messages may be queued and all incoming but unprocessed messages - are released. After both operations have been done, it is a good idea to also drop any remaining references to the - bus object so that it may be freed. Since these three operations are frequently done together a helper call - sd_bus_flush_close_unref3 is - provided that combines them into one. + sd_bus_flush() and then close connections with + sd_bus_close() to ensure that no unwritten messages are lost, no further + messages may be queued and all incoming but unprocessed messages are released. After both + operations have been done, it is a good idea to also drop any remaining references to the bus + object so that it may be freed. Since these three operations are frequently done together a + helper call + sd_bus_flush_close_unref3 + is provided that combines them into one. sd_bus_default_flush_close() is similar to - sd_bus_flush_close_unref, but does not take a bus pointer argument and instead - iterates over any of the "default" busses opened by + sd_bus_flush_close_unref, but does not take a bus pointer argument and + instead iterates over any of the "default" busses opened by sd_bus_default3, sd_bus_default_user3, sd_bus_default_system3, - and similar calls. sd_bus_default_flush_close() is particularly useful to clean up - any busses opened using those calls before the program exits. + and similar calls. sd_bus_default_flush_close() is particularly useful to + clean up any busses opened using those calls before the program exits. Return Value - On success, sd_bus_flush() returns 0 or a positive integer. On failure, it returns a - negative errno-style error code. + On success, sd_bus_flush() returns a non-negative integer. On + failure, it returns a negative errno-style error code. Errors @@ -91,7 +96,8 @@ -ECHILD - The bus connection has been created in a different process. + The bus connection has been created in a different process. + From 3258aa750e3a5872c0e27ffff3d922607cfe688d Mon Sep 17 00:00:00 2001 From: Daan De Meyer Date: Sat, 11 Apr 2020 21:25:39 +0200 Subject: [PATCH 3/3] sd-bus: Add sd_bus_can_send docs --- man/rules/meson.build | 1 + man/sd-bus.xml | 1 + man/sd_bus_can_send.xml | 93 +++++++++++++++++++++++++++++++++++++++++ 3 files changed, 95 insertions(+) create mode 100644 man/sd_bus_can_send.xml diff --git a/man/rules/meson.build b/man/rules/meson.build index 16e0ffca3f..dd8510c0f1 100644 --- a/man/rules/meson.build +++ b/man/rules/meson.build @@ -146,6 +146,7 @@ manpages = [ 'sd_bus_call_method_asyncv', 'sd_bus_call_methodv'], ''], + ['sd_bus_can_send', '3', [], ''], ['sd_bus_close', '3', ['sd_bus_default_flush_close', 'sd_bus_flush'], ''], ['sd_bus_creds_get_pid', '3', diff --git a/man/sd-bus.xml b/man/sd-bus.xml index 4f1d8355d6..8fbc30a786 100644 --- a/man/sd-bus.xml +++ b/man/sd-bus.xml @@ -50,6 +50,7 @@ sd_bus_call_async3, sd_bus_call_method3, sd_bus_call_method_async3, +sd_bus_can_send3, sd_bus_creds_get_pid3, sd_bus_creds_new_from_pid3, sd_bus_close3, diff --git a/man/sd_bus_can_send.xml b/man/sd_bus_can_send.xml new file mode 100644 index 0000000000..ba2a180ee2 --- /dev/null +++ b/man/sd_bus_can_send.xml @@ -0,0 +1,93 @@ + + + + + + + + sd_bus_can_send + systemd + + + + sd_bus_can_send + 3 + + + + sd_bus_can_send + + Check which types can be sent over a bus object + + + + + #include <systemd/sd-bus.h> + + + void sd_bus_can_send + sd_bus *bus + char type + + + + + + Description + + sd_bus_can_send is mostly used for checking if file descriptor + passing is available on the given bus. type can be any of the + SD_BUS_TYPE constants. + + + + Return Value + + On failure, sd_bus_can_send() returns a negative errno-style error + code. If values of the given type can be sent over the given bus, it returns a positive integer. + Otherwise, it returns zero. + + + Errors + + Returned errors may indicate the following problems: + + + + -ENOPKG + + The bus object bus could not be resolved. + + + + + -ENOTCONN + + The input parameter bus is + NULL or the bus is not connected. + + + + -ECHILD + + The bus object bus was created in a different + process. + + + + + + + + + See Also + + + systemd1, + sd-bus3 + + + +