diff --git a/man/rules/meson.build b/man/rules/meson.build index 6d10df1ab1..0e4c26d074 100644 --- a/man/rules/meson.build +++ b/man/rules/meson.build @@ -139,7 +139,7 @@ manpages = [ ['sd_bus_attach_event', '3', ['sd_bus_detach_event', 'sd_bus_get_event'], ''], ['sd_bus_call', '3', ['sd_bus_call_async'], ''], ['sd_bus_call_method', '3', ['sd_bus_call_method_async'], ''], - ['sd_bus_close', '3', ['sd_bus_flush'], ''], + ['sd_bus_close', '3', ['sd_bus_default_flush_close', 'sd_bus_flush'], ''], ['sd_bus_creds_get_pid', '3', ['sd_bus_creds_get_audit_login_uid', @@ -330,12 +330,15 @@ manpages = [ 'sd_bus_release_name_async', 'sd_bus_request_name_async'], ''], + ['sd_bus_set_address', '3', ['sd_bus_get_address'], ''], ['sd_bus_set_close_on_exit', '3', ['sd_bus_get_close_on_exit'], ''], ['sd_bus_set_connected_signal', '3', ['sd_bus_get_connected_signal'], ''], ['sd_bus_set_description', '3', ['sd_bus_get_allow_interactive_authorization', 'sd_bus_get_description', + 'sd_bus_is_anonymous', + 'sd_bus_is_trusted', 'sd_bus_set_allow_interactive_authorization', 'sd_bus_set_anonymous', 'sd_bus_set_trusted'], @@ -360,6 +363,7 @@ manpages = [ ''], ['sd_bus_slot_set_floating', '3', ['sd_bus_slot_get_floating'], ''], ['sd_bus_slot_set_userdata', '3', ['sd_bus_slot_get_userdata'], ''], + ['sd_bus_start', '3', [], ''], ['sd_bus_track_add_name', '3', ['sd_bus_track_add_sender', diff --git a/man/sd-bus.xml b/man/sd-bus.xml index 9bd6dbcc66..fb55a1b526 100644 --- a/man/sd-bus.xml +++ b/man/sd-bus.xml @@ -54,6 +54,7 @@ sd-bus-errors3, sd_bus_error3, sd_bus_error_add_map3, +sd_bus_get_address3, sd_bus_get_fd3, sd_bus_get_method_call_timeout3, sd_bus_get_n_queued_read3, @@ -86,6 +87,7 @@ sd_bus_process3, sd_bus_reply_method_error3, sd_bus_request_name3, +sd_bus_set_address3, sd_bus_set_connected_signal3, sd_bus_set_description3, sd_bus_set_method_call_timeout3, @@ -96,6 +98,7 @@ sd_bus_slot_set_destroy_callback3, sd_bus_slot_set_floating3, sd_bus_slot_set_userdata3, +sd_bus_start3, sd_bus_track_add_name3, sd_bus_track_new3 diff --git a/man/sd_bus_close.xml b/man/sd_bus_close.xml index d81c593878..953f16ac34 100644 --- a/man/sd_bus_close.xml +++ b/man/sd_bus_close.xml @@ -19,6 +19,7 @@ sd_bus_close sd_bus_flush + sd_bus_default_flush_close Close and flush a bus connection @@ -36,6 +37,11 @@ int sd_bus_flush sd_bus *bus + + + void sd_bus_default_flush_close + void + @@ -59,6 +65,15 @@ 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_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. diff --git a/man/sd_bus_default.xml b/man/sd_bus_default.xml index 51c27f04ff..8532c2bf46 100644 --- a/man/sd_bus_default.xml +++ b/man/sd_bus_default.xml @@ -186,14 +186,14 @@ Note that entering a container is a privileged operation, and will likely only work for the root user on the remote machine. - sd_bus_open_system_machine() connects - to the system bus in the specified machine, - where machine is the name of a local - container. See - machinectl1 - for more information about the "machine" concept. Note that - connections into local containers are only available to privileged - processes at this time. + sd_bus_open_system_machine() connects to the system bus in the specified + machine, where machine is the name of a local + container. See + sd_bus_set_address3 + for a description of the address syntax, and + machinectl1 for more + information about the "machine" concept. Note that connections into local containers are only available + to privileged processes at this time. These calls allocate a bus connection object and initiate the connection to a well-known bus of some form. An alternative to @@ -297,7 +297,7 @@ - In addition, any further connection-related errors may be by returned. See + In addition, other connection-related errors may be returned. See sd_bus_send3. @@ -313,6 +313,7 @@ sd_bus_new3, sd_bus_ref3, sd_bus_unref3, + sd_bus_close3, ssh1, systemd-machined.service8, machinectl1 diff --git a/man/sd_bus_new.xml b/man/sd_bus_new.xml index 7771a78d8b..ceca3350fc 100644 --- a/man/sd_bus_new.xml +++ b/man/sd_bus_new.xml @@ -87,14 +87,12 @@ or a related call, and then start the connection with sd_bus_start3. - In most cases, it is a better idea to invoke + In most cases, it is better to use sd_bus_default_user3, sd_bus_default_system3 - or related calls instead of the more low-level - sd_bus_new() and - sd_bus_start(). The higher-level calls not - only allocate a bus object but also start the connection to a - well-known bus in a single function invocation. + or related calls instead of the more low-level sd_bus_new() and + sd_bus_start(). The higher-level functions not only allocate a bus object but also + start the connection to a well-known bus in a single function call. sd_bus_ref() increases the reference counter of bus by one. diff --git a/man/sd_bus_set_address.xml b/man/sd_bus_set_address.xml new file mode 100644 index 0000000000..b022741ff4 --- /dev/null +++ b/man/sd_bus_set_address.xml @@ -0,0 +1,176 @@ + + + + + + + + sd_bus_set_address + systemd + + + + sd_bus_set_address + 3 + + + + sd_bus_set_address + sd_bus_get_address + + Set or query the address of the bus connection + + + + + #include <systemd/sd-bus.h> + + + int sd_bus_set_address + sd_bus *bus + const char* address + + + + int sd_bus_get_address + sd_bus *bus + const char** address + + + + + + + Description + + sd_bus_set_address() configures a list of addresses of bus brokers to try to + connect to from a subsequent + sd_bus_start3 call. + The argument is a ;-separated list of addresses to try. Each item must be one of the + following: + + + + + A unix socket address specified as + unix:guid=guid,path=path or + unix:guid=guid,abstract=path. + Exactly one of the path= and abstract= keys must be present, + while guid= is optional. + + + + A TCP socket address specified as + tcp:[guid=guid,][host=host][,port=port][,family=family]. + One or both of the host= and port= keys must be present, while + the rest is optional. family may be either or + . + + + + An executable to spawn specified as + unixexec:guid=guid,path=path,argv1=argument,argv2=argument,.... + The path= key must be present, while guid= is optional. + + + + A machine (container) to connect to specified as + x-machine-unix:guid=guid,machine=machine,pid=pid. + Exactly one of the machine= and pid= keys must be present, + while guid= is optional. machine is the name of a local + container. See + machinectl1 for + more information about the "machine" concept. machine=.host may be used to specify + the host machine. A connection to the standard system bus socket inside of the specified machine will + be created. + + + + In all cases, parameter guid is an identifier of the remote peer, in the + syntax accepted by + sd_id128_from_string3. + If specified, the identifier returned by the peer after the connection is established will be checked and + the connection will be rejected in case of a mismatch. + + Note that the addresses passed to sd_bus_set_address() may not be verified + immediately. If they are invalid, an error may be returned e.g. from a subsequent call to + sd_bus_start3. + + + sd_bus_get_address() returns any previously set addresses. In addition to + being explicitly set by sd_bus_set_address(), the address will also be set + automatically by + sd_bus_open3 and + similar calls, based on environment variables or built-in defaults. + + + + Return Value + + On success, these functions return a non-negative integer. On failure, they return a negative + errno-style error code. + + + Errors + + Returned errors may indicate the following problems: + + + + -EINVAL + + The input parameters bus or address are NULL. + + + + + -ENOPKG + + The bus object bus could not be resolved. + + + + + -EPERM + + The input parameter bus is in a wrong state + (sd_bus_set_address() may only be called once on a newly-created bus object). + + + + + -ECHILD + + The bus object bus was created in a different + process. + + + + + -ENODATA + + The bus object bus has no address configured. + + + + + + + + + + See Also + + + systemd1, + sd-bus3, + sd_bus_new3, + sd_bus_start3, + systemd-machined.service8, + machinectl1 + + + + diff --git a/man/sd_bus_set_description.xml b/man/sd_bus_set_description.xml index bee63cb74e..b855008eb8 100644 --- a/man/sd_bus_set_description.xml +++ b/man/sd_bus_set_description.xml @@ -19,7 +19,9 @@ sd_bus_set_description sd_bus_get_description sd_bus_set_anonymous + sd_bus_is_anonymous sd_bus_set_trusted + sd_bus_is_trusted sd_bus_set_allow_interactive_authorization sd_bus_get_allow_interactive_authorization @@ -48,12 +50,22 @@ int b + + int sd_bus_is_anonymous + sd_bus *bus + + int sd_bus_set_trusted sd_bus *bus int b + + int sd_bus_is_trusted + sd_bus *bus + + int sd_bus_set_allow_interactive_authorization sd_bus *bus @@ -75,7 +87,7 @@ and freed when the bus object is deallocated. The description argument may be NULL, in which case the description is unset. This function must be called before the bus - has been started. + is started. sd_bus_get_description() returns a description string in description. This string may have been previously set @@ -87,14 +99,20 @@ sd_bus_set_anonymous() enables or disables "anonymous authentication", i.e. lack of authentication, of the bus peer. This function must - be called before the bus has been started. See the Authentication Mechanisms section of the D-Bus specification for details. + sd_bus_is_anonymous() returns true if the bus connection allows anonymous + authentication (in the sense described in previous paragraph). + sd_bus_set_trusted() sets the "trusted" state on the bus object. If true, all connections on the bus are - trusted and access to all privileged and unprivileged methods is granted. This - function must be called before the bus has been started. + trusted and access to all privileged and unprivileged methods is granted. This + function must be called before the bus is started. + + sd_bus_is_trusted() returns true if the bus connection is trusted (in the + sense described in previous paragraph). sd_bus_set_allow_interactive_authorization() enables or disables interactive authorization for method calls. If true, diff --git a/man/sd_bus_start.xml b/man/sd_bus_start.xml new file mode 100644 index 0000000000..0be07f4777 --- /dev/null +++ b/man/sd_bus_start.xml @@ -0,0 +1,124 @@ + + + + + + + + sd_bus_start + systemd + + + + sd_bus_start + 3 + + + + sd_bus_start + + Initiate a bus connection to the D-bus broker daemon + + + + + + #include <systemd/sd-bus.h> + + + int sd_bus_start + sd_bus *bus + + + + + + Description + + sd_bus_start() connects an existing bus connection object to the D-Bus + broker daemon, usually + dbus-daemon1 + or + dbus-broker1. + The mechanism to use for the connection must be configured before the call to + sd_bus_start(), using one of + sd_bus_set_address3, + sd_bus_set_fd3, or + sd_bus_set_exec3. + sd_bus_start() will open the connection socket or spawn the executable as + needed, and asynchronously start a org.freedesktop.DBus.Hello() call. The + answer to the Hello call will be processed later from + sd_bus_process3. If + opening of the connection or queuing of the asynchronous call fail, the connection will be closed with + sd_bus_close3. + + In most cases, it is better to use + sd_bus_default_user3, + sd_bus_default_system3 + or related calls instead of the more low-level sd_bus_new() and + sd_bus_start(). The higher-level functions not only allocate a bus object but also + start the connection to a well-known bus in a single function call. + + + + Return Value + + On success, this function returns a non-negative integer. On failure, it returns a negative + errno-style error code. + + + Errors + + + + -EINVAL + + The input parameter bus is NULL. + + + + + -ENOPKG + + Bus object bus could not be resolved. + + + + + -EPERM + + The input parameter bus is in a wrong state + (sd_bus_start() may only be called once on a newly-created bus object). + + + + + -ECHILD + + The bus object bus was created in a different + process. + + + + + In addition, other connection-related errors may be returned. See + sd_bus_send3. + + + + + + + See Also + + + systemd1, + sd-bus3, + sd_bus_default3, + sd_bus_call_async3 + + + + diff --git a/src/libsystemd/sd-bus/sd-bus.c b/src/libsystemd/sd-bus/sd-bus.c index 7ad03680f4..e45334c83f 100644 --- a/src/libsystemd/sd-bus/sd-bus.c +++ b/src/libsystemd/sd-bus/sd-bus.c @@ -980,9 +980,8 @@ static int parse_container_unix_address(sd_bus *b, const char **p, char **guid) return -EINVAL; free_and_replace(b->machine, machine); - } else { + } else b->machine = mfree(b->machine); - } if (pid) { r = parse_pid(pid, &b->nspid); @@ -1271,10 +1270,7 @@ int bus_set_address_system(sd_bus *b) { assert(b); e = secure_getenv("DBUS_SYSTEM_BUS_ADDRESS"); - if (e) - return sd_bus_set_address(b, e); - - return sd_bus_set_address(b, DEFAULT_SYSTEM_BUS_ADDRESS); + return sd_bus_set_address(b, e ?: DEFAULT_SYSTEM_BUS_ADDRESS); } _public_ int sd_bus_open_system_with_description(sd_bus **ret, const char *description) { @@ -1319,29 +1315,30 @@ _public_ int sd_bus_open_system(sd_bus **ret) { } int bus_set_address_user(sd_bus *b) { - const char *e; - _cleanup_free_ char *ee = NULL, *s = NULL; + const char *a; + _cleanup_free_ char *_a = NULL; assert(b); - e = secure_getenv("DBUS_SESSION_BUS_ADDRESS"); - if (e) - return sd_bus_set_address(b, e); + a = secure_getenv("DBUS_SESSION_BUS_ADDRESS"); + if (!a) { + const char *e; + _cleanup_free_ char *ee = NULL; - e = secure_getenv("XDG_RUNTIME_DIR"); - if (!e) - return -ENOENT; + e = secure_getenv("XDG_RUNTIME_DIR"); + if (!e) + return -ENOENT; - ee = bus_address_escape(e); - if (!ee) - return -ENOMEM; + ee = bus_address_escape(e); + if (!ee) + return -ENOMEM; - if (asprintf(&s, DEFAULT_USER_BUS_ADDRESS_FMT, ee) < 0) - return -ENOMEM; + if (asprintf(&_a, DEFAULT_USER_BUS_ADDRESS_FMT, ee) < 0) + return -ENOMEM; + a = _a; + } - b->address = TAKE_PTR(s); - - return 0; + return sd_bus_set_address(b, a); } _public_ int sd_bus_open_user_with_description(sd_bus **ret, const char *description) { diff --git a/src/shared/bus-util.c b/src/shared/bus-util.c index 8e6a6e2ce2..4b0a3a3e31 100644 --- a/src/shared/bus-util.c +++ b/src/shared/bus-util.c @@ -115,36 +115,16 @@ int bus_event_loop_with_idle( return r; if (r == 0 && !exiting && idle) { + /* Inform the service manager that we are going down, so that it will queue all + * further start requests, instead of assuming we are already running. */ + sd_notify(false, "STOPPING=1"); - r = sd_bus_try_close(bus); - if (r == -EBUSY) - continue; - - /* Fallback for dbus1 connections: we - * unregister the name and wait for the - * response to come through for it */ - if (r == -EOPNOTSUPP) { - - /* Inform the service manager that we - * are going down, so that it will - * queue all further start requests, - * instead of assuming we are already - * running. */ - sd_notify(false, "STOPPING=1"); - - r = bus_async_unregister_and_exit(e, bus, name); - if (r < 0) - return r; - - exiting = true; - continue; - } - + r = bus_async_unregister_and_exit(e, bus, name); if (r < 0) return r; - sd_event_exit(e, 0); - break; + exiting = true; + continue; } } diff --git a/src/systemd/sd-bus.h b/src/systemd/sd-bus.h index e6f3298745..aed214352b 100644 --- a/src/systemd/sd-bus.h +++ b/src/systemd/sd-bus.h @@ -177,7 +177,7 @@ int sd_bus_get_sender(sd_bus *bus, const char **ret); int sd_bus_start(sd_bus *bus); -int sd_bus_try_close(sd_bus *bus); +int sd_bus_try_close(sd_bus *bus) _sd_deprecated_; /* deprecated */ void sd_bus_close(sd_bus *bus); sd_bus *sd_bus_ref(sd_bus *bus); diff --git a/tools/meson-check-api-docs.sh b/tools/meson-check-api-docs.sh index bd320562ad..c33672934d 100755 --- a/tools/meson-check-api-docs.sh +++ b/tools/meson-check-api-docs.sh @@ -6,7 +6,7 @@ sd_total=0 udev_good=0 udev_total=0 -for symbol in `nm -g --defined-only "$@" | grep " T " | cut -d" " -f3 | sort -u` ; do +for symbol in `nm -g --defined-only "$@" | grep " T " | cut -d" " -f3 | grep -wv sd_bus_try_close | sort -u` ; do if test -f ${MESON_BUILD_ROOT}/man/$symbol.3 ; then echo "✓ Symbol $symbol() is documented." good=1