Debian Codegraph @

upstream/debian-unstable/man3/sd_bus_new.3

raw
1 '\" t
2 .TH "SD_BUS_NEW" "3" "" "systemd 261~rc3" "sd_bus_new"
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_new, sd_bus_ref, sd_bus_unref, sd_bus_unrefp, sd_bus_close_unref, sd_bus_close_unrefp, sd_bus_flush_close_unref, sd_bus_flush_close_unrefp \- Create a new bus object and create or destroy references to it
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_new('u
32 .BI "int sd_bus_new(sd_bus\ **" "bus" ");"
33 .HP \w'sd_bus\ *sd_bus_ref('u
34 .BI "sd_bus *sd_bus_ref(sd_bus\ *" "bus" ");"
35 .HP \w'sd_bus\ *sd_bus_unref('u
36 .BI "sd_bus *sd_bus_unref(sd_bus\ *" "bus" ");"
37 .HP \w'sd_bus\ *sd_bus_close_unref('u
38 .BI "sd_bus *sd_bus_close_unref(sd_bus\ *" "bus" ");"
39 .HP \w'sd_bus\ *sd_bus_flush_close_unref('u
40 .BI "sd_bus *sd_bus_flush_close_unref(sd_bus\ *" "bus" ");"
41 .HP \w'void\ sd_bus_unrefp('u
42 .BI "void sd_bus_unrefp(sd_bus\ **" "busp" ");"
43 .HP \w'void\ sd_bus_close_unrefp('u
44 .BI "void sd_bus_close_unrefp(sd_bus\ **" "busp" ");"
45 .HP \w'void\ sd_bus_flush_close_unrefp('u
46 .BI "void sd_bus_flush_close_unrefp(sd_bus\ **" "busp" ");"
47 .SH "DESCRIPTION"
48 .PP
49 \fBsd_bus_new()\fR
50 creates a new bus object\&. This object is reference\-counted, and will be destroyed when all references are gone\&. Initially, the caller of this function owns the sole reference and the bus object will not be connected to any bus\&. To connect it to a bus, make sure to set an address with
51 \fBsd_bus_set_address\fR(3)
52 or a related call, and then start the connection with
53 \fBsd_bus_start\fR(3)\&.
54 .PP
55 In most cases, it is better to use
56 \fBsd_bus_default_user\fR(3),
57 \fBsd_bus_default_system\fR(3)
58 or related calls instead of the more low\-level
59 \fBsd_bus_new()\fR
60 and
61 \fBsd_bus_start()\fR\&. The higher\-level functions not only allocate a bus object but also start the connection to a well\-known bus in a single function call\&.
62 .PP
63 \fBsd_bus_ref()\fR
64 increases the reference counter of
65 \fIbus\fR
66 by one\&.
67 .PP
68 \fBsd_bus_unref()\fR
69 decreases the reference counter of
70 \fIbus\fR
71 by one\&. Once the reference count has dropped to zero,
72 \fIbus\fR
73 is destroyed and cannot be used anymore, so further calls to
74 \fBsd_bus_ref()\fR
75 or
76 \fBsd_bus_unref()\fR
77 are illegal\&.
78 .PP
79 \fBsd_bus_unrefp()\fR
80 is similar to
81 \fBsd_bus_unref()\fR
82 but takes a pointer to a pointer to an
83 \fBsd_bus\fR
84 object\&. This call is useful in conjunction with GCC\*(Aqs and LLVM\*(Aqs
85 \m[blue]\fBClean\-up Variable Attribute\fR\m[]\&\s-2\u[1]\d\s+2\&. Note that this function is defined as an inline function\&. Use a declaration like the following, in order to allocate a bus object that is freed automatically as the code block is left:
86 .sp
87 .if n \{\
88 .RS 4
89 .\}
90 .nf
91 {
92 __attribute__((cleanup(sd_bus_unrefp))) sd_bus *bus = NULL;
93 int r;
94 \&...
95 r = sd_bus_default(&bus);
96 if (r < 0) {
97 errno = \-r;
98 fprintf(stderr, "Failed to allocate bus: %m\en");
99 }
100 \&...
101 }
102 .fi
103 .if n \{\
104 .RE
105 .\}
106 .PP
107 \fBsd_bus_ref()\fR
108 and
109 \fBsd_bus_unref()\fR
110 execute no operation if the argument is
111 \fBNULL\fR\&.
112 \fBsd_bus_unrefp()\fR
113 will first dereference its argument, which must not be
114 \fBNULL\fR, and will execute no operation if
115 \fIthat\fR
116 is
117 \fBNULL\fR\&.
118 .PP
119 \fBsd_bus_close_unref()\fR
120 is similar to
121 \fBsd_bus_unref()\fR, but first executes
122 \fBsd_bus_close\fR(3), ensuring that the connection is terminated before the reference to the connection is dropped and possibly the object freed\&.
123 .PP
124 \fBsd_bus_flush_close_unref()\fR
125 is similar to
126 \fBsd_bus_unref()\fR, but first executes
127 \fBsd_bus_flush\fR(3)
128 as well as
129 \fBsd_bus_close\fR(3), ensuring that any pending messages are synchronously flushed out before the reference to the connection is dropped and possibly the object freed\&. This call is particularly useful immediately before exiting from a program as it ensures that any pending outgoing messages are written out, and unprocessed but queued incoming messages released before the connection is terminated and released\&.
130 .PP
131 \fBsd_bus_close_unrefp()\fR
132 is similar to
133 \fBsd_bus_close_unref()\fR, but may be used in GCC\*(Aqs and LLVM\*(Aqs Clean\-up Variable Attribute, see above\&. Similarly,
134 \fBsd_bus_flush_close_unrefp()\fR
135 is similar to
136 \fBsd_bus_flush_close_unref()\fR\&.
137 .SH "RETURN VALUE"
138 .PP
139 On success,
140 \fBsd_bus_new()\fR
141 returns 0 or a positive integer\&. On failure, it returns a negative errno\-style error code\&.
142 .PP
143 \fBsd_bus_ref()\fR
144 always returns the argument\&.
145 .PP
146 \fBsd_bus_unref()\fR
147 and
148 \fBsd_bus_flush_close_unref()\fR
149 always return
150 \fBNULL\fR\&.
151 .SS "Errors"
152 .PP
153 Returned errors may indicate the following problems:
154 .PP
155 \fB\-ENOMEM\fR
156 .RS 4
157 Memory allocation failed\&.
158 .RE
159 .SH "NOTES"
160 .PP
161 Functions described here are available as a shared library, which can be compiled against and linked to with the
162 \fBlibsystemd\fR\ \&\fBpkg-config\fR(1)
163 file\&.
164 .PP
165 The code described here uses
166 \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
167 \fBsetenv\fR(3)
168 from a parallel thread\&. It is recommended to only do calls to
169 \fBsetenv()\fR
170 from an early phase of the program when no other threads have been started\&.
171 .SH "HISTORY"
172 .PP
173 \fBsd_bus_new()\fR,
174 \fBsd_bus_ref()\fR, and
175 \fBsd_bus_unref()\fR
176 were added in version 209\&.
177 .PP
178 \fBsd_bus_unrefp()\fR
179 was added in version 229\&.
180 .PP
181 \fBsd_bus_flush_close_unref()\fR
182 and
183 \fBsd_bus_flush_close_unrefp()\fR
184 were added in version 240\&.
185 .PP
186 \fBsd_bus_close_unref()\fR
187 and
188 \fBsd_bus_close_unrefp()\fR
189 were added in version 241\&.
190 .SH "SEE ALSO"
191 .PP
192 \fBsystemd\fR(1), \fBsd-bus\fR(3), \fBsd_bus_default_user\fR(3), \fBsd_bus_default_system\fR(3), \fBsd_bus_open_user\fR(3), \fBsd_bus_open_system\fR(3), \fBsd_bus_close\fR(3)
193 .SH "NOTES"
194 .IP " 1." 4
195 Clean-up Variable Attribute
196 .RS 4
197 \%https://gcc.gnu.org/onlinedocs/gcc/Common-Variable-Attributes.html
198 .RE