Debian Codegraph @

upstream/debian-unstable/man3/sd_bus_process.3

raw
1 '\" t
2 .TH "SD_BUS_PROCESS" "3" "" "systemd 261~rc3" "sd_bus_process"
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_process \- Drive the connection
24 .SH "SYNOPSIS"
25 .sp
26 .ft B
27 .nf
28 #include <systemd/sd\-bus\&.h>
29 .fi
30 .ft
31 .HP \w'int\ sd_bus_process('u
32 .BI "int sd_bus_process(sd_bus\ *" "bus" ", sd_bus_message\ **" "ret" ");"
33 .SH "DESCRIPTION"
34 .PP
35 \fBsd_bus_process()\fR
36 drives the connection between the client and the message bus\&. That is, it handles connecting, authentication, and processing of messages\&. When invoked, pending I/O work is executed, and queued incoming messages are dispatched to registered callbacks\&. Each time it is invoked a single operation is executed\&. It returns zero when no operations were pending and positive if a message was processed\&. When zero is returned the caller should poll for I/O events before calling into
37 \fBsd_bus_process()\fR
38 again\&. For that either use the simple, blocking
39 \fBsd_bus_wait\fR(3)
40 call, or hook up the bus connection object to an external or manual event loop using
41 \fBsd_bus_get_fd\fR(3)\&.
42 .PP
43 \fBsd_bus_process()\fR
44 processes at most one incoming message per call\&. If the parameter
45 \fIret\fR
46 is not
47 \fBNULL\fR
48 and the call processed a message,
49 \fI*ret\fR
50 is set to this message\&. The caller owns a reference to this message and should call
51 \fBsd_bus_message_unref\fR(3)
52 when the message is no longer needed\&. If
53 \fIret\fR
54 is not
55 \fBNULL\fR
56 and progress was made, but no message was processed,
57 \fI*ret\fR
58 is set to
59 \fBNULL\fR\&. Note that only messages not already handled by the various types of registered message handlers (i\&.e\&. by filters registered via
60 \fBsd_bus_add_filter\fR(3), object handlers registered via
61 \fBsd_bus_add_object\fR(3), matches registered via
62 \fBsd_bus_add_match\fR(3), and related) will be returned through this parameter\&. Also note that if such a message handler returns a zero return value (as opposed to some value > 0) an incoming message will not be considered handled, and be passed to other suitable handlers (until one returns > > 0), or returned by
63 \fBsd_bus_process()\fR
64 (in case none returns > 0)\&.
65 .PP
66 If the bus object is connected to an
67 \fBsd-event\fR(3)
68 event loop (with
69 \fBsd_bus_attach_event\fR(3)), it is not necessary to call
70 \fBsd_bus_process()\fR
71 directly as it is invoked automatically when necessary\&.
72 .SH "RETURN VALUE"
73 .PP
74 If progress was made, a positive integer is returned\&. If no progress was made, 0 is returned\&. If an error occurs, a negative
75 \fIerrno\fR\-style error code is returned\&.
76 .SS "Errors"
77 .PP
78 Returned errors may indicate the following problems:
79 .PP
80 \fB\-EINVAL\fR
81 .RS 4
82 An invalid bus object was passed\&.
83 .RE
84 .PP
85 \fB\-ECHILD\fR
86 .RS 4
87 The bus connection was allocated in a parent process and is being reused in a child process after
88 \fBfork()\fR\&.
89 .RE
90 .PP
91 \fB\-ENOTCONN\fR
92 .RS 4
93 The bus connection has been terminated already\&.
94 .RE
95 .PP
96 \fB\-ECONNRESET\fR
97 .RS 4
98 The bus connection has been terminated just now\&.
99 .RE
100 .PP
101 \fB\-EBUSY\fR
102 .RS 4
103 This function is already being called, i\&.e\&.
104 \fBsd_bus_process()\fR
105 has been called from a callback function that itself was called by
106 \fBsd_bus_process()\fR\&.
107 .RE
108 .SH "NOTES"
109 .PP
110 Functions described here are available as a shared library, which can be compiled against and linked to with the
111 \fBlibsystemd\fR\ \&\fBpkg-config\fR(1)
112 file\&.
113 .PP
114 The code described here uses
115 \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
116 \fBsetenv\fR(3)
117 from a parallel thread\&. It is recommended to only do calls to
118 \fBsetenv()\fR
119 from an early phase of the program when no other threads have been started\&.
120 .SH "HISTORY"
121 .PP
122 \fBsd_bus_process()\fR
123 was added in version 221\&.
124 .SH "SEE ALSO"
125 .PP
126 \fBsystemd\fR(1), \fBsd-bus\fR(3), \fBsd_bus_wait\fR(3), \fBsd_bus_get_fd\fR(3), \fBsd_bus_message_unref\fR(3), \fBsd-event\fR(3), \fBsd_bus_attach_event\fR(3)