[systemd-devel] Reasoning behind sd_bus_error argument to sd_bus_call?

[Simon McVittie]

On Tue, 17 Mar 2020 at 20:17:05 +0100, Daan De Meyer wrote:
> I'm documenting sd_bus_call and its async variant and I was wondering about the
> sd_bus_error output parameter that's passed to it. [...] I don't
> see immediately see the benefit of the sd_bus_error parameter in a D-Bus client
> since I can simply check the return value instead which seems to contain the
> same information looking at the implementation.

The return value is a single int, which according to systemd conventions
is probably a negative errno value. That's a lot less information than
a D-Bus error (systemd sd_bus_error, libdbus DBusError or equivalent):
D-Bus errors consist of a machine-readable name (namespaced by a reversed
domain name) and a human-readable message.

For the information about *whether* an error occurred, sure, you get the
same information, but for information about *which* error occurred and why,
a sd_bus_error is a lot better.

Let's pretend your D-Bus client is interacting with a D-Bus service that
resembles systemd-timedated. An errno value can give you, at best,
something like this (where *** marks the part that came from the service's
reply):

    my-client: Error: Unable to set time zone to America/Gotham:
    ***No such file or directory (errno 2)***

whereas a D-Bus error (sd_bus_error) from a well-implemented service can
give you something a lot more detailed. For example, after you ispect
the sd_bus_error, you might find that the error above was either of these:

    my-client: Error: Unable to set time zone to America/Gotham:
    ***No time zone file for "America/Gotham" found (tried
    "/usr/share/zoneinfo/America/Gotham",
    "/usr/local/share/zoneinfo/America/Gotham")
    (error code com.example.NotTimedated.Error.NoSuchTimezone)***

    my-client: Error: Unable to set time zone to America/Gotham:
    ***No time zone data installed (tried "/usr/share/zoneinfo",
    "/usr/local/share/zoneinfo")
    (error code com.example.NotTimedated.Error.TzdataNotInstalled)***

In this example a programmatic client would also be able
to respond differently to the distinct machine-readable
errors com.example.NotTimedated.Error.NoSuchTimezone and
com.example.NotTimedated.Error.TzdataNotInstalled if it wanted to;
for example it could respond to the second error by trying to use
PackageKit to install tzdata, which obviously wouldn't be appropriate
for the first error.

D-Bus errors were inspired by GLib's GError, which is basically a triple
{ domain: interned string, code: int, message: string }, where the domain
provides extensible uniqueness, and the code is a member of an enum
determined by the domain.

    smcv