GLIB has recently started to officially support the gcc cleanup
attribute in its public API, hence let's do the same for our APIs.
With this patch we'll define an xyz_unrefp() call for each public
xyz_unref() call, to make it easy to use inside a
__attribute__((cleanup())) expression. Then, all code is ported over to
make use of this.
The new calls are also documented in the man pages, with examples how to
use them (well, I only added docs where the _unref() call itself already
had docs, and the examples, only cover sd_bus_unrefp() and
sd_event_unrefp()).
This also renames sd_lldp_free() to sd_lldp_unref(), since that's how we
tend to call our destructors these days.
Note that this defines no public macro that wraps gcc's attribute and
makes it easier to use. While I think it's our duty in the library to
make our stuff easy to use, I figure it's not our duty to make gcc's own
features easy to use on its own. Most likely, client code which wants to
make use of this should define its own:
#define _cleanup_(function) __attribute__((cleanup(function)))
Or similar, to make the gcc feature easier to use.
Making this logic public has the benefit that we can remove three header
files whose only purpose was to define these functions internally.
See #2008.
This introduces two new helpers alongside sd_bus_path_{encode,decode}(),
which work similarly to their counterparts, but accept a format-string as
input. This allows encoding and decoding multiple labels of a format
string at the same time.
If code enqueues a message on one of the default busses, but doesn't
sync on it, and immediately drops the reference to the bus again, it
will stay queued and consume memory. Intrdouce a new call
sd_bus_default_flush_close() that can be invoked at the end of programs
(or threads) and flushes out all unsent messages on any of the default
busses.
All other *_get_description() functions use 'const char**', so make sure
sd_bus_slot_get_description() does the same.
This changes API, but ABI stays stable. I think this is fine, but I
wouldn't mind bumping SONAME.
Reported in #528.
sd_bus_flush_close_unref() is a call that simply combines sd_bus_flush()
(which writes all unwritten messages out) + sd_bus_close() (which
terminates the connection, releasing all unread messages) +
sd_bus_unref() (which frees the connection).
The combination of this call is used pretty frequently in systemd tools
right before exiting, and should also be relevant for most external
clients, and is hence useful to cover in a call of its own.
Previously the combination of the three calls was already done in the
_cleanup_bus_close_unref_ macro, but this was only available internally.
Also see #327
With the v221 release these APIs should be public, stable APIs, hence
let's install their headers by default now, and add their symbols to the
.sym file.
This should simplify the prototype a bit. The bus parameter is redundant
in most cases, and in the few where it matters it can be derived from
the message via sd_bus_message_get_bus().
Most of our client tools want to set this bit for all their method
calls, even though it defaults to off in sd-bus, and rightfully so.
Hence, to simplify thing, introduce a per sd_bus-object flag that sets
the default value for all messages created on the connection.
This implements two new helpers, discussed on systemd-devel about 1 year
ago:
sd_bus_emit_object_added()
sd_bus_emit_object_removed()
Both calls are equivalent to their respective counterpart
sd_bus_emit_interfaces_{added/removed}(), but can figure out the list of
interfaces themselves, instead of requiring the caller to provide them.
Furthermore, both calls properly deal with builtin interfaces provided via
org.freedesktop.DBus.* and alike.
Both calls simply traverse a node and all its parent nodes to figure out a
list of all interfaces registered as vtable or fallback. It then appends
each of them, similar to the interfaces_{added/removed}() helpers.
Note that interfaces_{added/removed}() runs a parent traversal for *each*
passed interface. Therefore, it can simply bail out, once it found a
parent node that implements a given interface.
With object_{added/removed}() we cannot know the registered interfaces in
advance, thus, we cannot run one traversal per node. Instead, we run a
single traversal and remember all interfaces that we added. Therefore, a
child-interface overrides all conflicting parent-interfaces. We keep a
"Set *s" context to track those while climbing up the tree.
Pretty much everywhere else we use the generic term "machine" when
referring to containers in API, so let's do though in sd-bus too. In
particular, since the concept of a "container" exists in sd-bus too, but
as part of the marshalling system.
The ELF magic cannot work for consumers of our shard library, since they
are in a different module. Hence make all the ELF magic private, and
instead introduce a public function to register additional static
mapping table.
The ID returned really doesn't identify the owner, but the bus instance,
hence fix this misnaming.
Also, update "busctl status" to show the ID in its output.
Also:
- adds support for euid, suid, fsuid, egid, sgid, fsgid fields.
- makes augmentation of creds with data from /proc explicitly
controllable to give apps better control over this, given that this is
racy.
- enables augmentation for kdbus connections (previously we only did it
for dbus1). This is useful since with recent kdbus versions it is
possible for clients to control the metadata they want to send.
- changes sd_bus_query_sender_privilege() to take the euid of the client
into consideration, if known
- when we don't have permissions to read augmentation data from /proc,
don't fail, just don't add the data in
In kdbus a "server id" is mostly a misnomer, as there isn't any "server"
involved anymore. Let's rename this to "owner" id hence, since it is an
ID that is picked by the owner of a bus or direct connection. This
matches nicely the sd_bus_get_owner_creds() call we already have.
__attribute__((used)) is not enough to force static variables to
be carried over to a compiled program from a library. Mappings defined
in libsystemd-shared.a were not visible in the compiled binaries.
To ensure that the mappings are present in the final binary, the
tables are made non-static and are given a real unique name by which
they can be referenced.
To use a mapping defined not in the local compilation unit (e.g. in
a library) a reference to the mapping table is added. This is done
by including a declaration in the header file.
Expected values in test-engine are fixed to reflect the new mappings.
Clean up the function namespace by renaming the following:
sd_bus_get_owner_uid() → sd_bus_get_name_creds_uid()
sd_bus_get_owner_machine_id() → sd_bus_get_name_machine_id()
sd_bus_get_peer_creds() → sd_bus_get_owner_creds()
Remove the sd_ prefix from internal functions and get rid of the sd_memfd
type. As a memfd is now just a native file descriptor, we can get rid of our
own wrapper type, and also use close() and dup() on them directly.
This is a generalization of the vtable privilege check we already have,
but exported, and hence useful when preparing for a polkit change.
This will deal with the complexity that on dbus1 one cannot trust the
capability field we retrieve via the bus, since it is read via
/proc/$$/stat (and thus might be out-of-date) rather than directly from
the message (like on kdbus) or bus connection (as for uid creds on
dbus1).
Also, port over all code to this new API.
This makes callback behaviour more like sd-event or sd-resolve, and
creates proper object for unregistering callbacks.
Taking the refernce to the slot is optional. If not taken life time of
the slot will be bound to the underlying bus object (or in the case of
an async call until the reply has been recieved).
The new calls work similarly, but enforce a that a common, fixed bus
path prefix is used.
This follows discussions with Simon McVittie on IRC that it should be a
good idea to make sure that people don't use the escaping applied here
too wildly as anything other than the last label of a bus path.
This is primarily useful for services that need to track clients which
reference certain objects they maintain, or which explicitly want to
subscribe to certain events. Something like this is done in a large
number of services, and not trivial to do. Hence, let's unify this at
one place.
This also ports over PID 1 to use this to ensure that subscriptions to
job and manager events are correctly tracked. As a side-effect this
makes sure we properly serialize and restore the track list across
daemon reexec/reload, which didn't work correctly before.
This also simplifies how we distribute messages to broadcast to the
direct busses: we only track subscriptions for the API bus and
implicitly assume that all direct busses are subscribed. This should be
a pretty OK simplification since clients connected via direct bus
connections are shortlived anyway.
Previously the returned object of constructor functions where sometimes
returned as last, sometimes as first and sometimes as second parameter.
Let's clean this up a bit. Here are the new rules:
1. The object the new object is derived from is put first, if there is any
2. The object we are creating will be returned in the next arguments
3. This is followed by any additional arguments
Rationale:
For functions that operate on an object we always put that object first.
Constructors should probably not be too different in this regard. Also,
if the additional parameters might want to use varargs which suggests to
put them last.
Note that this new scheme only applies to constructor functions, not to
all other functions. We do give a lot of freedom for those.
Note that this commit only changes the order of the new functions we
added, for old ones we accept the wrong order and leave it like that.
Add new calls sd_bus_open() and sd_bus_default() for connecting to the
starter bus a service was invoked for, or -- if the process is not a
bus-activated service -- the appropriate bus for the scope the process
has been started in.
This brings the calls into similar style as the respective functions in
libsystemd-journal, and also is a bi shorter and more descriptive since
it clarifies the time unit used.
Even if the lower-leveld dbus1 protocol calls it "serial", let's expose
the word "cookie" for this instead, as this is what kdbus uses and since
it doesn't imply monotonicity the same way "serial" does.
Introduces a new concept of "trusted" vs. "untrusted" busses. For the
latter libsystemd-bus will automatically do per-method access control,
for the former all access is automatically granted. Per-method access
control is encoded in the vtables: by default all methods are only
accessible to privileged clients. If the SD_BUS_VTABLE_UNPRIVILEGED flag
is set for a method it is accessible to unprivileged clients too. By
default whether a client is privileged is determined via checking for
its CAP_SYS_ADMIN capability, but this can be altered via the
SD_BUS_VTABLE_CAPABILITY() macro that can be ORed into the flags field
of the method.
Writable properties are also subject to SD_BUS_VTABLE_UNPRIVILEGED and
SD_BUS_VTABLE_CAPABILITY() for controlling write access to them. Note
however that read access is unrestricted, as PropertiesChanged messages
might send out the values anyway as an unrestricted broadcast.
By default the system bus is set to "untrusted" and the user bus is
"trusted" since per-method access control on the latter is unnecessary.
On dbus1 busses we check the UID of the caller rather than the
configured capability since the capability cannot be determined without
race. On kdbus the capability is checked if possible from the attached
meta-data of a message and otherwise queried from the sending peer.
This also decorates the vtables of the various daemons we ship with
these flags.
Instead of returning an enum of return codes, make them return error
codes like kdbus does internally.
Also, document this behaviour so that clients can stick to it.
(Also rework bus-control.c to always have to functions for dbus1 vs.
kernel implementation of the various calls.)
(also, rename _SD_BUS_CREDS_MAX to _SD_BUX_CRED_ALL, since "MAX" so far
was used to indicate one higher than the highest valid value, and this
is not correct here.)
This way we can unify handling of credentials that are attached to
messages, or can be queried for bus name owners or connection peers.
This also adds the ability to extend incomplete credential information
with data from /proc,
Also, provide a convenience call that will automatically determine the
most appropriate credential object for an incoming message, by using the
the attached information if possible, the sending name information if
available and otherwise the peer's credentials.
Message handler callbacks can be simplified drastically if the
dispatcher automatically replies to method calls if errors are returned.
Thus: add an sd_bus_error argument to all message handlers. When we
dispatch a message handler and it returns negative or a set sd_bus_error
we send this as message error back to the client. This means errors
returned by handlers by default are given back to clients instead of
rippling all the way up to the event loop, which is desirable to make
things robust.
As a side-effect we can now easily turn the SELinux checks into normal
function calls, since the method call dispatcher will generate the right
error replies automatically now.
Also, make sure we always pass the error structure to all property and
method handlers as last argument to follow the usual style of passing
variables for return values as last argument.
This patch converts PID 1 to libsystemd-bus and thus drops the
dependency on libdbus. The only remaining code using libdbus is a test
case that validates our bus marshalling against libdbus' marshalling,
and this dependency can be turned off.
This patch also adds a couple of things to libsystem-bus, that are
necessary to make the port work:
- Synthesizing of "Disconnected" messages when bus connections are
severed.
- Support for attaching multiple vtables for the same interface on the
same path.
This patch also fixes the SetDefaultTarget() and GetDefaultTarget() bus
calls which used an inappropriate signature.
As a side effect we will now generate PropertiesChanged messages which
carry property contents, rather than just invalidation information.
We want to emphasize bus connections as per-thread communication
primitives, hence introduce a concept of a per-thread default bus, and
make use of it everywhere.
