Debian Codegraph @

upstream/debian-unstable/man3/sd_bus_slot_ref.3

raw
1 '\" t
2 .TH "SD_BUS_SLOT_REF" "3" "" "systemd 261~rc3" "sd_bus_slot_ref"
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_slot_ref, sd_bus_slot_unref, sd_bus_slot_unrefp \- Create and destroy references to a bus slot object
24 .SH "SYNOPSIS"
25 .sp
26 .ft B
27 .nf
28 #include <systemd/sd\-bus\&.h>
29 .fi
30 .ft
31 .HP \w'sd_bus_slot\ *sd_bus_slot_ref('u
32 .BI "sd_bus_slot *sd_bus_slot_ref(sd_bus_slot\ *" "slot" ");"
33 .HP \w'sd_bus_slot\ *sd_bus_slot_unref('u
34 .BI "sd_bus_slot *sd_bus_slot_unref(sd_bus_slot\ *" "slot" ");"
35 .HP \w'void\ sd_bus_slot_unrefp('u
36 .BI "void sd_bus_slot_unrefp(sd_bus_slot\ **" "slotp" ");"
37 .SH "DESCRIPTION"
38 .PP
39 \fBsd_bus_slot_ref()\fR
40 increases the internal reference counter of
41 \fIslot\fR
42 by one\&.
43 .PP
44 \fBsd_bus_slot_unref()\fR
45 decreases the internal reference counter of
46 \fIslot\fR
47 by one\&. Once the reference count has dropped to zero, slot object is destroyed and cannot be used anymore, so further calls to
48 \fBsd_bus_slot_ref()\fR
49 or
50 \fBsd_bus_slot_unref()\fR
51 are illegal\&.
52 .PP
53 \fBsd_bus_slot_unrefp()\fR
54 is similar to
55 \fBsd_bus_slot_unref()\fR
56 but takes a pointer to a pointer to an
57 \fBsd_bus_slot\fR
58 object\&. This call is useful in conjunction with GCC\*(Aqs and LLVM\*(Aqs
59 \m[blue]\fBClean\-up Variable Attribute\fR\m[]\&\s-2\u[1]\d\s+2\&. See
60 \fBsd_bus_new\fR(3)
61 for an example how to use the cleanup attribute\&.
62 .PP
63 \fBsd_bus_slot_ref()\fR
64 and
65 \fBsd_bus_slot_unref()\fR
66 execute no operation if the passed in bus object address is
67 \fBNULL\fR\&.
68 \fBsd_bus_slot_unrefp()\fR
69 will first dereference its argument, which must not be
70 \fBNULL\fR, and will execute no operation if
71 \fIthat\fR
72 is
73 \fBNULL\fR\&.
74 .SH "RETURN VALUE"
75 .PP
76 \fBsd_bus_slot_ref()\fR
77 always returns the argument\&.
78 .PP
79 \fBsd_bus_slot_unref()\fR
80 always returns
81 \fBNULL\fR\&.
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_slot_ref()\fR,
97 \fBsd_bus_slot_unref()\fR, and
98 \fBsd_bus_slot_unrefp()\fR
99 were added in version 240\&.
100 .SH "SEE ALSO"
101 .PP
102 \fBsystemd\fR(1), \fBsd-bus\fR(3), \fBsd_bus_new\fR(3), \fBsd_bus_message_new\fR(3), \fBsd_bus_call_method_async\fR(3)
103 .SH "NOTES"
104 .IP " 1." 4
105 Clean-up Variable Attribute
106 .RS 4
107 \%https://gcc.gnu.org/onlinedocs/gcc/Common-Variable-Attributes.html
108 .RE