Debian Codegraph @

upstream/debian-unstable/man3/sd_bus_add_match.3

raw
1 '\" t
2 .TH "SD_BUS_ADD_MATCH" "3" "" "systemd 261~rc3" "sd_bus_add_match"
3 .\" -----------------------------------------------------------------
4 .\" * Define some portability stuff
5 .\" -----------------------------------------------------------------
6 .\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
7 .\" http://bugs.debian.org/507673
8 .\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html
9 .\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
10 .ie \n(.g .ds Aq \(aq
11 .el .ds Aq '
12 .\" -----------------------------------------------------------------
13 .\" * set default formatting
14 .\" -----------------------------------------------------------------
15 .\" disable hyphenation
16 .nh
17 .\" disable justification (adjust text to left margin only)
18 .ad l
19 .\" -----------------------------------------------------------------
20 .\" * MAIN CONTENT STARTS HERE *
21 .\" -----------------------------------------------------------------
22 .SH "NAME"
23 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
24 .SH "SYNOPSIS"
25 .sp
26 .ft B
27 .nf
28 #include <systemd/sd\-bus\&.h>
29 .fi
30 .ft
31 .HP \w'typedef\ int\ (*sd_bus_message_handler_t)('u
32 .BI "typedef int (*sd_bus_message_handler_t)(sd_bus_message\ *" "m" ", void\ *" "userdata" ", sd_bus_error\ *" "ret_error" ");"
33 .HP \w'int\ sd_bus_add_match('u
34 .BI "int sd_bus_add_match(sd_bus\ *" "bus" ", sd_bus_slot\ **" "slot" ", const\ char\ *" "match" ", sd_bus_message_handler_t\ " "callback" ", void\ *" "userdata" ");"
35 .HP \w'int\ sd_bus_add_match_async('u
36 .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" ");"
37 .HP \w'int\ sd_bus_match_signal('u
38 .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" ");"
39 .HP \w'int\ sd_bus_match_signal_async('u
40 .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" ");"
41 .SH "DESCRIPTION"
42 .PP
43 \fBsd_bus_add_match()\fR
44 installs a match rule for messages received on the specified bus connection object
45 \fIbus\fR\&. The syntax of the match rule expression passed in
46 \fImatch\fR
47 is described in the
48 \m[blue]\fBD\-Bus Specification\fR\m[]\&\s-2\u[1]\d\s+2\&. The specified handler function
49 \fIcallback\fR
50 is called for each incoming message matching the specified expression, the
51 \fIuserdata\fR
52 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\&.
53 .PP
54 \fBsd_bus_add_match_async()\fR
55 operates very similarly to
56 \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
57 \fIinstall_callback\fR
58 function is called when the response is later received, with the response message from the broker as parameter\&. If this function is specified as
59 \fBNULL\fR
60 a default implementation is used that terminates the bus connection should installing the match fail\&.
61 .PP
62 \fBsd_bus_match_signal()\fR
63 is very similar to
64 \fBsd_bus_add_match()\fR, but only matches signals, and instead of a match expression accepts four parameters:
65 \fIsender\fR
66 (the service name of the sender),
67 \fIpath\fR
68 (the object path of the emitting object),
69 \fIinterface\fR
70 (the interface the signal belongs to),
71 \fImember\fR
72 (the signal name), from which the match string is internally generated\&. Optionally, these parameters may be specified as
73 \fBNULL\fR
74 in which case the relevant field of incoming signals is not tested\&.
75 .PP
76 \fBsd_bus_match_signal_async()\fR
77 combines the signal matching logic of
78 \fBsd_bus_match_signal()\fR
79 with the asynchronous behaviour of
80 \fBsd_bus_add_match_async()\fR\&.
81 .PP
82 On success, and if non\-\fBNULL\fR, the
83 \fIslot\fR
84 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
85 \fBsd_bus_slot_unref\fR(3)\&. If specified as
86 \fBNULL\fR
87 the lifetime of the match is bound to the lifetime of the bus object itself, and the match is generally not removed independently\&. See
88 \fBsd_bus_slot_set_floating\fR(3)
89 for details\&.
90 .PP
91 The message
92 \fIm\fR
93 passed to the callback is only borrowed, that is, the callback should not call
94 \fBsd_bus_message_unref\fR(3)
95 on it\&. If the callback wants to hold on to the message beyond the lifetime of the callback, it needs to call
96 \fBsd_bus_message_ref\fR(3)
97 to create a new reference\&.
98 .PP
99 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
100 \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\&.
101 .PP
102 If the
103 \fIbus\fR
104 refers to a direct connection (i\&.e\&. not a bus connection, as set with
105 \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\&.
106 .SH "RETURN VALUE"
107 .PP
108 On success,
109 \fBsd_bus_add_match()\fR
110 and the other calls return 0 or a positive integer\&. On failure, they return a negative errno\-style error code\&.
111 .SH "NOTES"
112 .PP
113 Functions described here are available as a shared library, which can be compiled against and linked to with the
114 \fBlibsystemd\fR\ \&\fBpkg-config\fR(1)
115 file\&.
116 .PP
117 The code described here uses
118 \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
119 \fBsetenv\fR(3)
120 from a parallel thread\&. It is recommended to only do calls to
121 \fBsetenv()\fR
122 from an early phase of the program when no other threads have been started\&.
123 .SH "HISTORY"
124 .PP
125 \fBsd_bus_add_match()\fR
126 and
127 \fBsd_bus_message_handler_t()\fR
128 were added in version 221\&.
129 .PP
130 \fBsd_bus_add_match_async()\fR,
131 \fBsd_bus_match_signal()\fR, and
132 \fBsd_bus_match_signal_async()\fR
133 were added in version 237\&.
134 .SH "SEE ALSO"
135 .PP
136 \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)
137 .SH "NOTES"
138 .IP " 1." 4
139 D-Bus Specification
140 .RS 4
141 \%https://dbus.freedesktop.org/doc/dbus-specification.html
142 .RE