Debian Codegraph @

upstream/debian-unstable/man3/sd_bus_track_new.3

raw
1 '\" t
2 .TH "SD_BUS_TRACK_NEW" "3" "" "systemd 261~rc3" "sd_bus_track_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_track_new, sd_bus_track_ref, sd_bus_track_unref, sd_bus_track_unrefp, sd_bus_track_set_recursive, sd_bus_track_get_recursive, sd_bus_track_get_bus, sd_bus_track_get_userdata, sd_bus_track_set_userdata \- Track bus peers
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_track_handler_t)('u
32 .BI "typedef int (*sd_bus_track_handler_t)(sd_bus_track\ *" "track" ", void\ *" "userdata" ");"
33 .HP \w'int\ sd_bus_track_new('u
34 .BI "int sd_bus_track_new(sd_bus*\ " "bus" ", sd_bus_track**\ " "ret" ", sd_bus_track_handler_t\ " "handler" ", void*\ " "userdata" ");"
35 .HP \w'sd_bus_track\ *sd_bus_track_ref('u
36 .BI "sd_bus_track *sd_bus_track_ref(sd_bus_track\ *" "t" ");"
37 .HP \w'sd_bus_track\ *sd_bus_track_unref('u
38 .BI "sd_bus_track *sd_bus_track_unref(sd_bus_track\ *" "t" ");"
39 .HP \w'void\ sd_bus_track_unrefp('u
40 .BI "void sd_bus_track_unrefp(sd_bus_track\ **" "t" ");"
41 .HP \w'int\ sd_bus_track_get_recursive('u
42 .BI "int sd_bus_track_get_recursive(sd_bus_track\ *" "t" ");"
43 .HP \w'int\ sd_bus_track_set_recursive('u
44 .BI "int sd_bus_track_set_recursive(sd_bus_track\ *" "t" ", int\ " "b" ");"
45 .HP \w'sd_bus*\ sd_bus_track_get_bus('u
46 .BI "sd_bus* sd_bus_track_get_bus(sd_bus_track\ *" "t" ");"
47 .HP \w'void*\ sd_bus_track_get_userdata('u
48 .BI "void* sd_bus_track_get_userdata(sd_bus_track\ *" "t" ");"
49 .HP \w'void*\ sd_bus_track_set_userdata('u
50 .BI "void* sd_bus_track_set_userdata(sd_bus_track\ *" "t" ", void\ *userdata);"
51 .SH "DESCRIPTION"
52 .PP
53 \fBsd_bus_track_new()\fR
54 creates a new bus peer tracking object\&. The object is allocated for the specified bus, and returned in the
55 \fI*ret\fR
56 parameter\&. After use, the object should be freed again by dropping the acquired reference with
57 \fBsd_bus_track_unref()\fR
58 (see below)\&. A bus peer tracking object may be used to keep track of peers on a specific IPC bus, for cases where peers are making use of one or more local objects, in order to control the lifecycle of the local objects and ensure they stay around as long as the peers needing them are around, and unreferenced (and possibly destroyed) as soon as all relevant peers have vanished\&. Each bus peer tracking object may be used to track zero, one or more peers add a time\&. References to specific bus peers are added via
59 \fBsd_bus_track_add_name\fR(3)
60 or
61 \fBsd_bus_track_add_sender()\fR\&. They may be dropped again via
62 \fBsd_bus_track_remove_name()\fR
63 and
64 \fBsd_bus_track_remove_sender()\fR\&. Alternatively, references on peers are removed automatically when they disconnect from the bus\&. If non\-\fBNULL\fR
65 the
66 \fIhandler\fR
67 may specify a function that is invoked whenever the last reference is dropped, regardless whether the reference is dropped explicitly via
68 \fBsd_bus_track_remove_name()\fR
69 or implicitly because the peer disconnected from the bus\&. The final argument
70 \fIuserdata\fR
71 may be used to attach a generic user data pointer to the object\&. This pointer is passed to the handler callback when it is invoked\&.
72 .PP
73 \fBsd_bus_track_ref()\fR
74 creates a new reference to a bus peer tracking object\&. This object will not be destroyed until
75 \fBsd_bus_track_unref()\fR
76 has been called as many times plus once more\&. Once the reference count has dropped to zero, the specified object cannot be used anymore, further calls to
77 \fBsd_bus_track_ref()\fR
78 or
79 \fBsd_bus_track_unref()\fR
80 on the same object are illegal\&.
81 .PP
82 \fBsd_bus_track_unref()\fR
83 destroys a reference to a bus peer tracking object\&.
84 .PP
85 \fBsd_bus_track_unrefp()\fR
86 is similar to
87 \fBsd_bus_track_unref()\fR
88 but takes a pointer to a pointer to an
89 \fBsd_bus_track\fR
90 object\&. This call is useful in conjunction with GCC\*(Aqs and LLVM\*(Aqs
91 \m[blue]\fBClean\-up Variable Attribute\fR\m[]\&\s-2\u[1]\d\s+2\&. Note that this function is defined as inline function\&.
92 .PP
93 \fBsd_bus_track_ref()\fR,
94 \fBsd_bus_track_unref()\fR
95 and
96 \fBsd_bus_track_unrefp()\fR
97 execute no operation if the passed in bus peer tracking object is
98 \fBNULL\fR\&.
99 .PP
100 Bus peer tracking objects may exist in two modes: by default they operate in non\-recursive mode, but may optionally be switched into recursive mode\&. If operating in the default non\-recursive mode a peer is either tracked or not tracked\&. In this mode invoking
101 \fBsd_bus_track_add_name()\fR
102 multiple times in a row for the same peer is fully equivalent to calling it just once, as the call adds the peer to the set of tracked peers if necessary, and executes no operation if the peer is already being tracked\&. A single invocation of
103 \fBsd_bus_track_remove_name()\fR
104 removes the reference on the peer again, regardless how many times
105 \fBsd_bus_track_add_name()\fR
106 was called before\&. If operating in recursive mode, the number of times
107 \fBsd_bus_track_add_name()\fR
108 is invoked for the same peer name is counted and
109 \fBsd_bus_track_remove_name()\fR
110 must be called the same number of times before the peer is not tracked anymore, with the exception when the tracked peer vanishes from the bus, in which case the count is irrelevant and the tracking of the specific peer is immediately removed\&.
111 \fBsd_bus_track_get_recursive()\fR
112 may be used to determine whether the bus peer tracking object is operating in recursive mode\&.
113 \fBsd_bus_track_set_recursive()\fR
114 may be used to enable or disable recursive mode\&. By default, a bus peer tracking object operates in non\-recursive mode, and
115 \fBsd_bus_track_get_recursive()\fR
116 for a newly allocated object hence returns a value equal to zero\&. Use
117 \fBsd_bus_track_set_recursive()\fR
118 to enable recursive mode, right after allocation\&. It takes a boolean argument to enable or disable recursive mode\&. Note that tracking objects for which
119 \fBsd_bus_track_add_name()\fR
120 was already invoked at least once (and which hence track already one or more peers) may not be switched from recursive to non\-recursive mode anymore\&.
121 .PP
122 \fBsd_bus_track_get_bus()\fR
123 returns the bus object the bus peer tracking object belongs to\&. It returns the bus object initially passed to
124 \fBsd_bus_track_new()\fR
125 when the object was allocated\&.
126 .PP
127 \fBsd_bus_track_get_userdata()\fR
128 returns the generic user data pointer set on the bus peer tracking object at the time of creation using
129 \fBsd_bus_track_new()\fR
130 or at a later time, using
131 \fBsd_bus_track_set_userdata()\fR\&.
132 .SH "RETURN VALUE"
133 .PP
134 On success,
135 \fBsd_bus_track_new()\fR
136 and
137 \fBsd_bus_track_set_recursive()\fR
138 return 0 or a positive integer\&. On failure, they return a negative errno\-style error code\&.
139 .PP
140 \fBsd_bus_track_ref()\fR
141 always returns the argument\&.
142 .PP
143 \fBsd_bus_track_unref()\fR
144 always returns
145 \fBNULL\fR\&.
146 .PP
147 \fBsd_bus_track_get_recursive()\fR
148 returns 0 if non\-recursive mode is selected (default), and greater than 0 if recursive mode is selected\&. On failure a negative errno\-style error code is returned\&.
149 .PP
150 \fBsd_bus_track_get_bus()\fR
151 returns the bus object associated to the bus peer tracking object\&.
152 .PP
153 \fBsd_bus_track_get_userdata()\fR
154 returns the generic user data pointer associated with the bus peer tracking object\&.
155 \fBsd_bus_track_set_userdata()\fR
156 returns the previous user data pointer set\&.
157 .SH "REFERENCE OWNERSHIP"
158 .PP
159 The
160 \fBsd_bus_track_new()\fR
161 function creates a new object and the caller owns the sole reference\&. When not needed anymore, this reference should be destroyed with
162 \fBsd_bus_track_unref()\fR\&.
163 .SS "Errors"
164 .PP
165 Returned errors may indicate the following problems:
166 .PP
167 \fB\-EBUSY\fR
168 .RS 4
169 Bus peers have already been added to the bus peer tracking object and
170 \fBsd_bus_track_set_recursive()\fR
171 was called to change tracking mode\&.
172 .RE
173 .PP
174 \fB\-EINVAL\fR
175 .RS 4
176 Specified parameter is invalid (\fBNULL\fR
177 in case of output parameters)\&.
178 .RE
179 .PP
180 \fB\-ENOMEM\fR
181 .RS 4
182 Memory allocation failed\&.
183 .RE
184 .SH "NOTES"
185 .PP
186 Functions described here are available as a shared library, which can be compiled against and linked to with the
187 \fBlibsystemd\fR\ \&\fBpkg-config\fR(1)
188 file\&.
189 .PP
190 The code described here uses
191 \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
192 \fBsetenv\fR(3)
193 from a parallel thread\&. It is recommended to only do calls to
194 \fBsetenv()\fR
195 from an early phase of the program when no other threads have been started\&.
196 .SH "HISTORY"
197 .PP
198 \fBsd_bus_track_new()\fR,
199 \fBsd_bus_track_handler_t()\fR,
200 \fBsd_bus_track_ref()\fR,
201 \fBsd_bus_track_unref()\fR,
202 \fBsd_bus_track_unrefp()\fR,
203 \fBsd_bus_track_get_recursive()\fR,
204 \fBsd_bus_track_set_recursive()\fR,
205 \fBsd_bus_track_get_bus()\fR,
206 \fBsd_bus_track_get_userdata()\fR, and
207 \fBsd_bus_track_set_userdata()\fR
208 were added in version 232\&.
209 .SH "SEE ALSO"
210 .PP
211 \fBsystemd\fR(1), \fBsd-bus\fR(3), \fBsd_bus_track_add_name\fR(3)
212 .SH "NOTES"
213 .IP " 1." 4
214 Clean-up Variable Attribute
215 .RS 4
216 \%https://gcc.gnu.org/onlinedocs/gcc/Common-Variable-Attributes.html
217 .RE