Debian Codegraph @

upstream/debian-unstable/man3/sd_device_ref.3

raw
1 '\" t
2 .TH "SD_DEVICE_REF" "3" "" "systemd 261~rc3" "sd_device_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_device_ref, sd_device_unref, sd_device_unrefp \- Create or destroy references to a device object
24 .SH "SYNOPSIS"
25 .sp
26 .ft B
27 .nf
28 #include <systemd/sd\-device\&.h>
29 .fi
30 .ft
31 .HP \w'sd_device*\ sd_device_ref('u
32 .BI "sd_device* sd_device_ref(sd_device\ *" "device" ");"
33 .HP \w'sd_device*\ sd_device_unref('u
34 .BI "sd_device* sd_device_unref(sd_device\ *" "device" ");"
35 .HP \w'void\ sd_device_unrefp('u
36 .BI "void sd_device_unrefp(sd_device\ **" "device" ");"
37 .PP
38 \fBsd_device_ref()\fR
39 increases the internal reference counter of
40 \fIdevice\fR
41 by one\&.
42 .PP
43 \fBsd_device_unref()\fR
44 decreases the internal reference counter of
45 \fIdevice\fR
46 by one\&. Once the reference count has dropped to zero,
47 \fIdevice\fR
48 is destroyed and cannot be used anymore, so further calls to
49 \fBsd_device_ref()\fR
50 or
51 \fBsd_device_unref()\fR
52 are illegal\&.
53 .PP
54 \fBsd_device_unrefp()\fR
55 is similar to
56 \fBsd_device_unref()\fR
57 but takes a pointer to a pointer to an
58 \fBsd_device\fR
59 object\&. This call is useful in conjunction with GCC\*(Aqs and LLVM\*(Aqs
60 \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 device object that is freed automatically as the code block is left:
61 .sp
62 .nf
63 {
64 __attribute__((cleanup(sd_device_unrefp))) sd_device *device = NULL;
65 int r;
66 \&...
67 r = sd_device_new_from_syspath(&device, "\&...");
68 if (r < 0) {
69 errno = \-r;
70 fprintf(stderr, "Failed to allocate device: %m\en");
71 }
72 \&...
73 }
74 .fi
75 .PP
76 \fBsd_device_ref()\fR
77 and
78 \fBsd_device_unref()\fR
79 execute no operation if the argument is
80 \fBNULL\fR\&.
81 \fBsd_device_unrefp()\fR
82 will first dereference its argument, which must not be
83 \fBNULL\fR, and will execute no operation if
84 \fIthat\fR
85 is
86 \fBNULL\fR\&.
87 .SH "RETURN VALUE"
88 .PP
89 \fBsd_device_ref()\fR
90 always returns the argument, and
91 \fBsd_device_unref()\fR
92 always returns
93 \fBNULL\fR\&.
94 .SH "HISTORY"
95 .PP
96 \fBsd_device_ref()\fR,
97 \fBsd_device_unref()\fR, and
98 \fBsd_device_unrefp()\fR
99 were added in version 251\&.
100 .SH "NOTES"
101 .IP " 1." 4
102 Clean-up Variable Attribute
103 .RS 4
104 \%https://gcc.gnu.org/onlinedocs/gcc/Common-Variable-Attributes.html
105 .RE