Adding upstream version 4.22.0.upstream/4.22.0

Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>

1 files changed, 147 insertions, 0 deletions

diff --git a/upstream/mageia-cauldron/man3/sd_bus_add_match.3 b/upstream/mageia-cauldron/man3/sd_bus_add_match.3
new file mode 100644
index 00000000..26a1a815
--- /dev/null
+++ b/upstream/mageia-cauldron/man3/sd_bus_add_match.3
@@ -0,0 +1,147 @@
+'\" t
+.TH "SD_BUS_ADD_MATCH" "3" "" "systemd 255" "sd_bus_add_match"
+.\" -----------------------------------------------------------------
+.\" * Define some portability stuff
+.\" -----------------------------------------------------------------
+.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+.\" http://bugs.debian.org/507673
+.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html
+.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+.ie \n(.g .ds Aq \(aq
+.el       .ds Aq '
+.\" -----------------------------------------------------------------
+.\" * set default formatting
+.\" -----------------------------------------------------------------
+.\" disable hyphenation
+.nh
+.\" disable justification (adjust text to left margin only)
+.ad l
+.\" -----------------------------------------------------------------
+.\" * MAIN CONTENT STARTS HERE *
+.\" -----------------------------------------------------------------
+.SH "NAME"
+sd_bus_add_match, sd_bus_add_match_async, sd_bus_match_signal, sd_bus_match_signal_async \- Add a match rule for incoming message dispatching
+.SH "SYNOPSIS"
+.sp
+.ft B
+.nf
+#include <systemd/sd\-bus\&.h>
+.fi
+.ft
+.HP \w'typedef\ int\ (*sd_bus_message_handler_t)('u
+.BI "typedef int (*sd_bus_message_handler_t)(sd_bus_message\ *" "m" ", void\ *" "userdata" ", sd_bus_error\ *" "ret_error" ");"
+.HP \w'int\ sd_bus_add_match('u
+.BI "int sd_bus_add_match(sd_bus\ *" "bus" ", sd_bus_slot\ **" "slot" ", const\ char\ *" "match" ", sd_bus_message_handler_t\ " "callback" ", void\ *" "userdata" ");"
+.HP \w'int\ sd_bus_add_match_async('u
+.BI "int sd_bus_add_match_async(sd_bus\ *" "bus" ", sd_bus_slot\ **" "slot" ", const\ char\ *" "match" ", sd_bus_message_handler_t\ " "callback" ", sd_bus_message_handler_t\ " "install_callback" ", void\ *" "userdata" ");"
+.HP \w'int\ sd_bus_match_signal('u
+.BI "int sd_bus_match_signal(sd_bus\ *" "bus" ", sd_bus_slot\ **" "slot" ", const\ char\ *" "sender" ", const\ char\ *" "path" ", const\ char\ *" "interface" ", const\ char\ *" "member" ", sd_bus_message_handler_t\ " "callback" ", void\ *" "userdata" ");"
+.HP \w'int\ sd_bus_match_signal_async('u
+.BI "int sd_bus_match_signal_async(sd_bus\ *" "bus" ", sd_bus_slot\ **" "slot" ", const\ char\ *" "sender" ", const\ char\ *" "path" ", const\ char\ *" "interface" ", const\ char\ *" "member" ", sd_bus_message_handler_t\ " "callback" ", sd_bus_message_handler_t\ " "install_callback" ", void\ *" "userdata" ");"
+.SH "DESCRIPTION"
+.PP
+\fBsd_bus_add_match()\fR
+installs a match rule for messages received on the specified bus connection object
+\fIbus\fR\&. The syntax of the match rule expression passed in
+\fImatch\fR
+is described in the
+\m[blue]\fBD\-Bus Specification\fR\m[]\&\s-2\u[1]\d\s+2\&. The specified handler function
+\fIcallback\fR
+is called for each incoming message matching the specified expression, the
+\fIuserdata\fR
+parameter is passed as\-is to the callback function\&. The match is installed synchronously when connected to a bus broker, i\&.e\&. the call sends a control message requested the match to be added to the broker and waits until the broker confirms the match has been installed successfully\&.
+.PP
+\fBsd_bus_add_match_async()\fR
+operates very similarly to
+\fBsd_bus_add_match()\fR, however it installs the match asynchronously, in a non\-blocking fashion: a request is sent to the broker, but the call does not wait for a response\&. The
+\fIinstall_callback\fR
+function is called when the response is later received, with the response message from the broker as parameter\&. If this function is specified as
+\fBNULL\fR
+a default implementation is used that terminates the bus connection should installing the match fail\&.
+.PP
+\fBsd_bus_match_signal()\fR
+is very similar to
+\fBsd_bus_add_match()\fR, but only matches signals, and instead of a match expression accepts four parameters:
+\fIsender\fR
+(the service name of the sender),
+\fIpath\fR
+(the object path of the emitting object),
+\fIinterface\fR
+(the interface the signal belongs to),
+\fImember\fR
+(the signal name), from which the match string is internally generated\&. Optionally, these parameters may be specified as
+\fBNULL\fR
+in which case the relevant field of incoming signals is not tested\&.
+.PP
+\fBsd_bus_match_signal_async()\fR
+combines the signal matching logic of
+\fBsd_bus_match_signal()\fR
+with the asynchronous behaviour of
+\fBsd_bus_add_match_async()\fR\&.
+.PP
+On success, and if non\-\fBNULL\fR, the
+\fIslot\fR
+return parameter will be set to a slot object that may be used as a reference to the installed match, and may be utilized to remove it again at a later time with
+\fBsd_bus_slot_unref\fR(3)\&. If specified as
+\fBNULL\fR
+the lifetime of the match is bound to the lifetime of the bus object itself, and the match is generally not removed independently\&. See
+\fBsd_bus_slot_set_floating\fR(3)
+for details\&.
+.PP
+The message
+\fIm\fR
+passed to the callback is only borrowed, that is, the callback should not call
+\fBsd_bus_message_unref\fR(3)
+on it\&. If the callback wants to hold on to the message beyond the lifetime of the callback, it needs to call
+\fBsd_bus_message_ref\fR(3)
+to create a new reference\&.
+.PP
+If an error occurs during the callback invocation, the callback should return a negative error number (optionally, a more precise error may be returned in
+\fIret_error\fR, as well)\&. If it wants other callbacks that match the same rule to be called, it should return 0\&. Otherwise it should return a positive integer\&.
+.PP
+If the
+\fIbus\fR
+refers to a direct connection (i\&.e\&. not a bus connection, as set with
+\fBsd_bus_set_bus_client\fR(3)) the match is only installed on the client side, and the synchronous and asynchronous functions operate the same\&.
+.SH "RETURN VALUE"
+.PP
+On success,
+\fBsd_bus_add_match()\fR
+and the other calls return 0 or a positive integer\&. On failure, they return a negative errno\-style error code\&.
+.SH "NOTES"
+.PP
+Functions described here are available as a shared library, which can be compiled against and linked to with the
+\fBlibsystemd\fR\ \&\fBpkg-config\fR(1)
+file\&.
+.PP
+The code described here uses
+\fBgetenv\fR(3), which is declared to be not multi\-thread\-safe\&. This means that the code calling the functions described here must not call
+\fBsetenv\fR(3)
+from a parallel thread\&. It is recommended to only do calls to
+\fBsetenv()\fR
+from an early phase of the program when no other threads have been started\&.
+.SH "HISTORY"
+.PP
+\fBsd_bus_add_match()\fR
+and
+\fBsd_bus_message_handler_t()\fR
+were added in version 231\&.
+.PP
+\fBsd_bus_add_match_async()\fR,
+\fBsd_bus_match_signal()\fR, and
+\fBsd_bus_match_signal_async()\fR
+were added in version 237\&.
+.SH "SEE ALSO"
+.PP
+\fBsystemd\fR(1),
+\fBsd-bus\fR(3),
+\fBsd_bus_slot_unref\fR(3),
+\fBsd_bus_message_ref\fR(3),
+\fBsd_bus_set_bus_client\fR(3),
+\fBsd_bus_slot_set_floating\fR(3)
+.SH "NOTES"
+.IP " 1." 4
+D-Bus Specification
+.RS 4
+\%https://dbus.freedesktop.org/doc/dbus-specification.html
+.RE