Debian Codegraph @

upstream/debian-unstable/man3/sd_bus_close.3

raw
1 '\" t
2 .TH "SD_BUS_CLOSE" "3" "" "systemd 261~rc3" "sd_bus_close"
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_close, sd_bus_flush, sd_bus_default_flush_close \- Close and flush 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'void\ sd_bus_close('u
32 .BI "void sd_bus_close(sd_bus\ *" "bus" ");"
33 .HP \w'int\ sd_bus_flush('u
34 .BI "int sd_bus_flush(sd_bus\ *" "bus" ");"
35 .HP \w'void\ sd_bus_default_flush_close('u
36 .BI "void sd_bus_default_flush_close(void);"
37 .SH "DESCRIPTION"
38 .PP
39 \fBsd_bus_close()\fR
40 disconnects the specified bus connection\&. When this call is invoked and the specified bus object refers to an active connection it is immediately terminated\&. No further messages may be sent or received on it\&. Any messages queued in the bus object (both incoming and outgoing) are released\&. If invoked on
41 \fBNULL\fR
42 bus object or when the bus connection is already closed this function executes no operation\&. This call does not free or unreference the bus object itself\&. Use
43 \fBsd_bus_unref\fR(3)
44 for that\&.
45 .PP
46 \fBsd_bus_flush()\fR
47 synchronously writes out all outgoing queued message on a bus connection if there are any\&. This function call may block if the peer is not processing bus messages quickly\&.
48 .PP
49 Before a program exits it is usually a good idea to flush any pending messages with
50 \fBsd_bus_flush()\fR
51 and then close connections with
52 \fBsd_bus_close()\fR
53 to ensure that no unwritten messages are lost, no further messages may be queued and all incoming but unprocessed messages are released\&. After both operations have been done, it is a good idea to also drop any remaining references to the bus object so that it may be freed\&. Since these three operations are frequently done together a helper call
54 \fBsd_bus_flush_close_unref\fR(3)
55 is provided that combines them into one\&.
56 .PP
57 \fBsd_bus_default_flush_close()\fR
58 is similar to
59 \fBsd_bus_flush_close_unref()\fR, but does not take a bus pointer argument and instead iterates over any of the "default" buses opened by
60 \fBsd_bus_default\fR(3),
61 \fBsd_bus_default_user\fR(3),
62 \fBsd_bus_default_system\fR(3), and similar calls\&.
63 \fBsd_bus_default_flush_close()\fR
64 is particularly useful to clean up any buses opened using those calls before the program exits\&.
65 .SH "RETURN VALUE"
66 .PP
67 On success,
68 \fBsd_bus_flush()\fR
69 returns a non\-negative integer\&. On failure, it returns a negative errno\-style error code\&.
70 .SS "Errors"
71 .PP
72 Returned errors may indicate the following problems:
73 .PP
74 \fB\-ECHILD\fR
75 .RS 4
76 The bus connection has been created in a different process, library or module instance\&.
77 .RE
78 .SH "NOTES"
79 .PP
80 Functions described here are available as a shared library, which can be compiled against and linked to with the
81 \fBlibsystemd\fR\ \&\fBpkg-config\fR(1)
82 file\&.
83 .PP
84 The code described here uses
85 \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
86 \fBsetenv\fR(3)
87 from a parallel thread\&. It is recommended to only do calls to
88 \fBsetenv()\fR
89 from an early phase of the program when no other threads have been started\&.
90 .SH "HISTORY"
91 .PP
92 \fBsd_bus_close()\fR
93 and
94 \fBsd_bus_flush()\fR
95 were added in version 221\&.
96 .PP
97 \fBsd_bus_default_flush_close()\fR
98 was added in version 227\&.
99 .SH "SEE ALSO"
100 .PP
101 \fBsystemd\fR(1), \fBsd-bus\fR(3), \fBsd_bus_unref\fR(3), \fBsd_bus_set_close_on_exit\fR(3)