Debian Codegraph @

upstream/debian-unstable/man3/sd_bus_wait.3

raw
1 '\" t
2 .TH "SD_BUS_WAIT" "3" "" "systemd 261~rc3" "sd_bus_wait"
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_wait \- Wait for I/O on a bus 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_wait('u
32 .BI "int sd_bus_wait(sd_bus\ *" "bus" ", uint64_t\ " "timeout_usec" ");"
33 .SH "DESCRIPTION"
34 .PP
35 \fBsd_bus_wait()\fR
36 synchronously waits for I/O on the specified bus connection object\&. This function is supposed to be called whenever
37 \fBsd_bus_process\fR(3)
38 returns zero, indicating that no work is pending on the connection\&. Internally, this call invokes
39 \fBppoll\fR(2), to wait for I/O on the bus connection\&. If the
40 \fItimeout_usec\fR
41 parameter is specified, the call will block at most for the specified amount of time in μs\&. Pass
42 \fBUINT64_MAX\fR
43 to permit it to sleep indefinitely\&.
44 .PP
45 After each invocation of
46 \fBsd_bus_wait()\fR
47 the
48 \fBsd_bus_process()\fR
49 call should be invoked in order to process any now pending I/O work\&.
50 .PP
51 Note that
52 \fBsd_bus_wait()\fR
53 is suitable only for simple programs as it does not permit waiting for other I/O events\&. For more complex programs either connect the bus connection object to an external event loop using
54 \fBsd_bus_get_fd\fR(3)
55 or to an
56 \fBsd-event\fR(3)
57 event loop using
58 \fBsd_bus_attach_event\fR(3)\&.
59 .SH "RETURN VALUE"
60 .PP
61 If any I/O was seen, a positive value is returned, zero otherwise\&. If an error occurs, a negative
62 \fIerrno\fR\-style error code is returned\&.
63 .SS "Errors"
64 .PP
65 Returned errors may indicate the following problems:
66 .PP
67 \fB\-EINVAL\fR
68 .RS 4
69 An invalid bus object was passed\&.
70 .RE
71 .PP
72 \fB\-ECHILD\fR
73 .RS 4
74 The bus connection was allocated in a parent process and is being reused in a child process after
75 \fBfork()\fR\&.
76 .RE
77 .PP
78 \fB\-ENOTCONN\fR
79 .RS 4
80 The bus connection has been terminated already\&.
81 .RE
82 .SH "NOTES"
83 .PP
84 Functions described here are available as a shared library, which can be compiled against and linked to with the
85 \fBlibsystemd\fR\ \&\fBpkg-config\fR(1)
86 file\&.
87 .PP
88 The code described here uses
89 \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
90 \fBsetenv\fR(3)
91 from a parallel thread\&. It is recommended to only do calls to
92 \fBsetenv()\fR
93 from an early phase of the program when no other threads have been started\&.
94 .SH "HISTORY"
95 .PP
96 \fBsd_bus_wait()\fR
97 was added in version 240\&.
98 .SH "SEE ALSO"
99 .PP
100 \fBsystemd\fR(1), \fBsd-bus\fR(3), \fBsd_bus_process\fR(3), \fBsd_bus_get_fd\fR(3), \fBsd-event\fR(3), \fBsd_bus_attach_event\fR(3)