Debian Codegraph @

upstream/debian-unstable/man3/sd_device_enumerator_new.3

raw
1 '\" t
2 .TH "SD_DEVICE_ENUMERATOR_NEW" "3" "" "systemd 261~rc3" "sd_device_enumerator_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_device_enumerator_new, sd_device_enumerator_ref, sd_device_enumerator_unref, sd_device_enumerator_unrefp \- Create, reference, and release a device enumerator object
24 .SH "SYNOPSIS"
25 .sp
26 .ft B
27 .nf
28 #include <systemd/sd\-device\&.h>
29 .fi
30 .ft
31 .HP \w'int\ sd_device_enumerator_new('u
32 .BI "int sd_device_enumerator_new(sd_device_enumerator\ **" "ret" ");"
33 .HP \w'sd_device_enumerator*\ sd_device_enumerator_ref('u
34 .BI "sd_device_enumerator* sd_device_enumerator_ref(sd_device_enumerator\ *" "enumerator" ");"
35 .HP \w'sd_device_enumerator*\ sd_device_enumerator_unref('u
36 .BI "sd_device_enumerator* sd_device_enumerator_unref(sd_device_enumerator\ *" "enumerator" ");"
37 .HP \w'void\ sd_device_enumerator_unrefp('u
38 .BI "void sd_device_enumerator_unrefp(sd_device_enumerator\ **" "enumerator" ");"
39 .SH "DESCRIPTION"
40 .PP
41 The
42 \fBsd_device_enumerator\fR
43 family of functions provides a way to iterate over devices recognized by
44 \fBsystemd-udevd\fR(8)\&. The enumerator allows filtering and matching devices by subsystem, properties and other attributes\&.
45 .PP
46 \fBsd_device_enumerator_new()\fR
47 creates a new device enumerator object and stores the result in the pointer referenced by
48 \fIret\fR\&. Returns 0 on success, or a negative errno\-style error code on failure\&.
49 .PP
50 \fBsd_device_enumerator_ref()\fR
51 increases the reference count of the specified
52 \fIenumerator\fR
53 by one\&.
54 .PP
55 \fBsd_device_enumerator_unref()\fR
56 decreases the reference count of the
57 \fIenumerator\fR
58 by one\&. When the reference count reaches zero, the enumerator object is destroyed and cannot be used anymore, so further calls to
59 \fBsd_device_enumerator_unref() \fR
60 or
61 \fBsd_device_enumerator_unrefp()\fR
62 are illegal\&.
63 .PP
64 \fBsd_device_enumerator_unrefp()\fR
65 is similar to
66 \fBsd_device_enumerator_unref()\fR
67 but takes a pointer to a pointer to an
68 \fBsd_device_enumerator\fR
69 object\&. This call is useful in conjunction with GCC\*(Aqs and LLVM\*(Aqs
70 \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
71 \fBsd_device_enumerator\fR
72 object that is freed automatically as the code block is left:
73 .sp
74 .if n \{\
75 .RS 4
76 .\}
77 .nf
78 {
79 __attribute__((cleanup(sd_device_enumerator_unrefp))) sd_device_enumerator *enumerator = NULL;
80 int r;
81 \&...
82 r = sd_device_enumerator_new(&enumerator);
83 if (r < 0)
84 fprintf(stderr, "Failed to allocate sd_device_enumerator: %s\en", strerror(\-r));
85 \&...
86 }
87 .fi
88 .if n \{\
89 .RE
90 .\}
91 .PP
92 \fBsd_device_enumerator_ref()\fR
93 and
94 \fBsd_device_enumerator_unref()\fR
95 execute no operation if the
96 \fIenumerator\fR
97 is
98 \fBNULL\fR\&.
99 \fBsd_device_enumerator_unrefp()\fR
100 will first dereference its argument, which must not be
101 \fBNULL\fR, and will execute no operation if
102 \fIthat\fR
103 is
104 \fBNULL\fR\&.
105 .SH "RETURN VALUE"
106 .PP
107 \fBsd_device_enumerator_new()\fR
108 returns 0 on success or a negative errno\-style error code on failure\&.
109 .PP
110 \fBsd_device_enumerator_ref()\fR
111 always returns the enumerator pointer\&.
112 .PP
113 \fBsd_device_enumerator_unref()\fR
114 always returns
115 \fBNULL\fR\&.
116 .SS "Errors"
117 .PP
118 Returned errors may indicate the following problems:
119 .PP
120 \fB\-ENOMEM\fR
121 .RS 4
122 Memory allocation failed\&.
123 .RE
124 .PP
125 \fB\-EINVAL\fR
126 .RS 4
127 The argument is invalid\&.
128 .RE
129 .SH "EXAMPLE"
130 .PP
131 \fBExample\ \&1.\ \&Using sd_device_enumerator_new()\fR
132 .sp
133 .if n \{\
134 .RS 4
135 .\}
136 .nf
137 /* SPDX\-License\-Identifier: MIT\-0 */
138
139 #include <stdio\&.h>
140 #include <systemd/sd\-device\&.h>
141
142 int main(void) {
143 sd_device_enumerator *enumerator;
144 int r;
145
146 r = sd_device_enumerator_new(&enumerator);
147 if (r < 0) {
148 fprintf(stderr, "Failed to create enumerator: %s\en", strerror(\-r));
149 return 1;
150 }
151
152 sd_device_enumerator_ref(enumerator);
153 sd_device_enumerator_unref(enumerator);
154
155 sd_device_enumerator_unref(enumerator);
156
157 return 0;
158 }
159 .fi
160 .if n \{\
161 .RE
162 .\}
163 .SH "HISTORY"
164 .PP
165 \fBsd_device_enumerator_new()\fR,
166 \fBsd_device_enumerator_ref()\fR,
167 \fBsd_device_enumerator_unref()\fR, and
168 \fBsd_device_enumerator_unrefp()\fR
169 were added in version 240\&.
170 .SH "SEE ALSO"
171 .PP
172 \fBsd_device_ref\fR(3), \fBsd_device_enumerator_add_match_parent\fR(3)
173 .SH "NOTES"
174 .IP " 1." 4
175 Clean-up Variable Attribute
176 .RS 4
177 \%https://gcc.gnu.org/onlinedocs/gcc/Common-Variable-Attributes.html
178 .RE