Debian Codegraph @

upstream/mageia-cauldron/man3/udev_device_new_from_syspath.3

raw
1 '\" t
2 .TH "UDEV_DEVICE_NEW_FROM_SYSPATH" "3" "" "systemd 258.7" "udev_device_new_from_syspath"
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 udev_device_new_from_syspath, udev_device_new_from_devnum, udev_device_new_from_subsystem_sysname, udev_device_new_from_device_id, udev_device_new_from_environment, udev_device_ref, udev_device_unref \- Create, acquire and release a udev device object
24 .SH "SYNOPSIS"
25 .sp
26 .ft B
27 .nf
28 #include <libudev\&.h>
29 .fi
30 .ft
31 .HP \w'struct\ udev_device\ *udev_device_new_from_syspath('u
32 .BI "struct udev_device *udev_device_new_from_syspath(struct\ udev\ *" "udev" ", const\ char\ *" "syspath" ");"
33 .HP \w'struct\ udev_device\ *udev_device_new_from_devnum('u
34 .BI "struct udev_device *udev_device_new_from_devnum(struct\ udev\ *" "udev" ", char\ " "type" ", dev_t\ " "devnum" ");"
35 .HP \w'struct\ udev_device\ *udev_device_new_from_subsystem_sysname('u
36 .BI "struct udev_device *udev_device_new_from_subsystem_sysname(struct\ udev\ *" "udev" ", const\ char\ *" "subsystem" ", const\ char\ *" "sysname" ");"
37 .HP \w'struct\ udev_device\ *udev_device_new_from_device_id('u
38 .BI "struct udev_device *udev_device_new_from_device_id(struct\ udev\ *" "udev" ", const\ char\ *" "id" ");"
39 .HP \w'struct\ udev_device\ *udev_device_new_from_environment('u
40 .BI "struct udev_device *udev_device_new_from_environment(struct\ udev\ *" "udev" ");"
41 .HP \w'struct\ udev_device\ *udev_device_ref('u
42 .BI "struct udev_device *udev_device_ref(struct\ udev_device\ *" "udev_device" ");"
43 .HP \w'struct\ udev_device\ *udev_device_unref('u
44 .BI "struct udev_device *udev_device_unref(struct\ udev_device\ *" "udev_device" ");"
45 .SH "DESCRIPTION"
46 .PP
47 \fBudev_device_new_from_syspath()\fR,
48 \fBudev_device_new_from_devnum()\fR,
49 \fBudev_device_new_from_subsystem_sysname()\fR,
50 \fBudev_device_new_from_device_id()\fR, and
51 \fBudev_device_new_from_environment()\fR
52 allocate a new udev device object and returns a pointer to it\&. This object is opaque and must not be accessed by the caller via different means than functions provided by libudev\&. Initially, the reference count of the device is 1\&. You can acquire further references, and drop gained references via
53 \fBudev_device_ref()\fR
54 and
55 \fBudev_device_unref()\fR\&. Once the reference count hits 0, the device object is destroyed and freed\&.
56 .PP
57 \fBudev_device_new_from_syspath()\fR,
58 \fBudev_device_new_from_devnum()\fR,
59 \fBudev_device_new_from_subsystem_sysname()\fR, and
60 \fBudev_device_new_from_device_id()\fR
61 create the device object based on information found in
62 /sys/, annotated with properties from the udev\-internal device database\&. A syspath is any subdirectory of
63 /sys/, with the restriction that a subdirectory of
64 /sys/devices
65 (or a symlink to one) represents a real device and as such must contain a
66 uevent
67 file\&.
68 \fBudev_device_new_from_devnum()\fR
69 takes a device type, which can be
70 \fBb\fR
71 for block devices or
72 \fBc\fR
73 for character devices, as well as a devnum (see
74 \fBmakedev\fR(3))\&.
75 \fBudev_device_new_from_subsystem_sysname()\fR
76 looks up devices based on the provided subsystem and sysname (see
77 \fBudev_device_get_subsystem\fR(3)
78 and
79 \fBudev_device_get_sysname\fR(3)) and
80 \fBudev_device_new_from_device_id()\fR
81 looks up devices based on the provided device ID, which is a special string in one of the following four forms:
82 .sp
83 .it 1 an-trap
84 .nr an-no-space-flag 1
85 .nr an-break-flag 1
86 .br
87 .B Table\ \&1.\ \&Device ID strings
88 .TS
89 allbox tab(:);
90 lB lB.
91 T{
92 Example
93 T}:T{
94 Explanation
95 T}
96 .T&
97 l l
98 l l
99 l l
100 l l.
101 T{
102 \fIb8:2\fR
103 T}:T{
104 block device major:minor
105 T}
106 T{
107 \fIc128:1\fR
108 T}:T{
109 char device major:minor
110 T}
111 T{
112 \fIn3\fR
113 T}:T{
114 network device ifindex
115 T}
116 T{
117 \fI+sound:card29\fR
118 T}:T{
119 kernel driver core subsystem:device name
120 T}
121 .TE
122 .sp 1
123 .PP
124 \fBudev_device_new_from_environment()\fR
125 creates a device from the current environment (see
126 \fBenviron\fR(7))\&. Each key\-value pair is interpreted in the same way as if it was received in an uevent (see
127 \fBudev_monitor_receive_device\fR(3))\&. The keys
128 \fBDEVPATH\fR,
129 \fBSUBSYSTEM\fR,
130 \fBACTION\fR, and
131 \fBSEQNUM\fR
132 are mandatory\&.
133 .SH "RETURN VALUE"
134 .PP
135 On success,
136 \fBudev_device_new_from_syspath()\fR,
137 \fBudev_device_new_from_devnum()\fR,
138 \fBudev_device_new_from_subsystem_sysname()\fR,
139 \fBudev_device_new_from_device_id()\fR
140 and
141 \fBudev_device_new_from_environment()\fR
142 return a pointer to the allocated udev device\&. On failure,
143 \fBNULL\fR
144 is returned, and
145 \fIerrno\fR
146 is set appropriately\&.
147 \fBudev_device_ref()\fR
148 returns the argument that it was passed, unmodified\&.
149 \fBudev_device_unref()\fR
150 always returns
151 \fBNULL\fR\&.
152 .SH "HISTORY"
153 .PP
154 \fBudev_device_new_from_syspath()\fR,
155 \fBudev_device_new_from_devnum()\fR,
156 \fBudev_device_new_from_subsystem_sysname()\fR,
157 \fBudev_device_new_from_device_id()\fR,
158 \fBudev_device_new_from_environment()\fR,
159 \fBudev_device_ref()\fR, and
160 \fBudev_device_unref()\fR
161 were added in version 221\&.
162 .SH "SEE ALSO"
163 .PP
164 \fBudev_new\fR(3), \fBudev_device_get_syspath\fR(3), \fBudev_device_has_tag\fR(3), \fBudev_enumerate_new\fR(3), \fBudev_monitor_new_from_netlink\fR(3), \fBudev_list_entry\fR(3), \fBsystemd\fR(1)