1 <?xml version='
1.0'
?> <!--*-nxml-*-->
2 <!DOCTYPE refentry PUBLIC
"-//OASIS//DTD DocBook XML V4.2//EN"
3 "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd" [
4 <!ENTITY % entities SYSTEM
"custom-entities.ent" >
9 SPDX-License-Identifier: LGPL-2.1+
11 Copyright © 2015 David Herrmann <dh.herrmann@gmail.com>
14 <refentry id=
"udev_device_new_from_syspath"
15 xmlns:
xi=
"http://www.w3.org/2001/XInclude">
18 <title>udev_device_new_from_syspath
</title>
19 <productname>systemd
</productname>
23 <refentrytitle>udev_device_new_from_syspath
</refentrytitle>
24 <manvolnum>3</manvolnum>
28 <refname>udev_device_new_from_syspath
</refname>
29 <refname>udev_device_new_from_devnum
</refname>
30 <refname>udev_device_new_from_subsystem_sysname
</refname>
31 <refname>udev_device_new_from_device_id
</refname>
32 <refname>udev_device_new_from_environment
</refname>
33 <refname>udev_device_ref
</refname>
34 <refname>udev_device_unref
</refname>
36 <refpurpose>Create, acquire and release a udev device object
</refpurpose>
41 <funcsynopsisinfo>#include
<libudev.h
></funcsynopsisinfo>
44 <funcdef>struct udev_device *
<function>udev_device_new_from_syspath
</function></funcdef>
45 <paramdef>struct udev *
<parameter>udev
</parameter></paramdef>
46 <paramdef>const char *
<parameter>syspath
</parameter></paramdef>
50 <funcdef>struct udev_device *
<function>udev_device_new_from_devnum
</function></funcdef>
51 <paramdef>struct udev *
<parameter>udev
</parameter></paramdef>
52 <paramdef>char
<parameter>type
</parameter></paramdef>
53 <paramdef>dev_t
<parameter>devnum
</parameter></paramdef>
57 <funcdef>struct udev_device *
<function>udev_device_new_from_subsystem_sysname
</function></funcdef>
58 <paramdef>struct udev *
<parameter>udev
</parameter></paramdef>
59 <paramdef>const char *
<parameter>subsystem
</parameter></paramdef>
60 <paramdef>const char *
<parameter>sysname
</parameter></paramdef>
64 <funcdef>struct udev_device *
<function>udev_device_new_from_device_id
</function></funcdef>
65 <paramdef>struct udev *
<parameter>udev
</parameter></paramdef>
66 <paramdef>const char *
<parameter>id
</parameter></paramdef>
70 <funcdef>struct udev_device *
<function>udev_device_new_from_environment
</function></funcdef>
71 <paramdef>struct udev *
<parameter>udev
</parameter></paramdef>
75 <funcdef>struct udev_device *
<function>udev_device_ref
</function></funcdef>
76 <paramdef>struct udev_device *
<parameter>udev_device
</parameter></paramdef>
80 <funcdef>struct udev_device *
<function>udev_device_unref
</function></funcdef>
81 <paramdef>struct udev_device *
<parameter>udev_device
</parameter></paramdef>
88 <title>Description
</title>
90 <para><function>udev_device_new_from_syspath
</function>,
91 <function>udev_device_new_from_devnum
</function>,
92 <function>udev_device_new_from_subsystem_sysname
</function>,
93 <function>udev_device_new_from_device_id
</function>, and
94 <function>udev_device_new_from_environment
</function>
95 allocate a new udev device object and returns a pointer to it. This
96 object is opaque and must not be accessed by the caller via different
97 means than functions provided by libudev. Initially, the reference count
98 of the device is
1. You can acquire further references, and drop
99 gained references via
<function>udev_device_ref()
</function> and
100 <function>udev_device_unref()
</function>. Once the reference count hits
0,
101 the device object is destroyed and freed.
</para>
103 <para><function>udev_device_new_from_syspath
</function>,
104 <function>udev_device_new_from_devnum
</function>,
105 <function>udev_device_new_from_subsystem_sysname
</function>, and
106 <function>udev_device_new_from_device_id
</function>
107 create the device object based on information found in
108 <filename>/sys
</filename>, annotated with properties from the udev-internal
109 device database. A syspath is any subdirectory of
<filename>/sys
</filename>,
110 with the restriction that a subdirectory of
<filename>/sys/devices
</filename>
111 (or a symlink to one) represents a real device and as such must contain
112 a
<filename>uevent
</filename> file.
<function>udev_device_new_from_devnum
</function>
113 takes a device type, which can be
<constant>b
</constant> for block devices or
114 <constant>c
</constant> for character devices, as well as a devnum (see
115 <citerefentry project='man-pages'
><refentrytitle>makedev
</refentrytitle><manvolnum>3</manvolnum></citerefentry>).
116 <function>udev_device_new_from_subsystem_sysname
</function> looks up devices based
117 on the provided subsystem and sysname
118 (see
<citerefentry><refentrytitle>udev_device_get_subsystem
</refentrytitle><manvolnum>3</manvolnum></citerefentry>
120 <citerefentry><refentrytitle>udev_device_get_sysname
</refentrytitle><manvolnum>3</manvolnum></citerefentry>)
121 and
<function>udev_device_new_from_device_id
</function> looks up devices based on the provided
122 device ID, which is a special string in one of the following four forms:
124 <title>Device ID strings
</title>
127 <colspec colname='example'
/>
128 <colspec colname='explanation'
/>
130 <entry>Example
</entry>
131 <entry>Explanation
</entry>
134 <row><entry><varname>b8:
2</varname></entry>
135 <entry>block device major:minor
</entry></row>
137 <row><entry><varname>c128:
1</varname></entry>
138 <entry>char device major:minor
</entry></row>
140 <row><entry><varname>n3
</varname></entry>
141 <entry>network device ifindex
</entry></row>
143 <row><entry><varname>+sound:card29
</varname></entry>
144 <entry>kernel driver core subsystem:device name
</entry></row>
150 <para><function>udev_device_new_from_environment
</function>
151 creates a device from the current environment (see
152 <citerefentry project='man-pages'
><refentrytitle>environ
</refentrytitle><manvolnum>7</manvolnum></citerefentry>).
153 Each key-value pair is interpreted in the same way as if it was
154 received in an uevent (see
155 <citerefentry><refentrytitle>udev_monitor_receive_device
</refentrytitle><manvolnum>3</manvolnum></citerefentry>).
156 The keys
<constant>DEVPATH
</constant>,
<constant>SUBSYSTEM
</constant>,
157 <constant>ACTION
</constant>, and
<constant>SEQNUM
</constant> are mandatory.
</para>
162 <title>Return Value
</title>
164 <para>On success,
<function>udev_device_new_from_syspath()
</function>,
165 <function>udev_device_new_from_devnum()
</function>,
166 <function>udev_device_new_from_subsystem_sysname()
</function>,
167 <function>udev_device_new_from_device_id()
</function> and
168 <function>udev_device_new_from_environment()
</function> return a
169 pointer to the allocated udev device. On failure,
170 <constant>NULL
</constant> is returned,
171 and
<varname>errno
</varname> is set appropriately.
172 <function>udev_device_ref()
</function> returns the argument
173 that it was passed, unmodified.
174 <function>udev_device_unref()
</function> always returns
175 <constant>NULL
</constant>.
</para>
179 <title>See Also
</title>
182 <citerefentry><refentrytitle>udev_new
</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
183 <citerefentry><refentrytitle>udev_device_get_syspath
</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
184 <citerefentry><refentrytitle>udev_device_has_tag
</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
185 <citerefentry><refentrytitle>udev_enumerate_new
</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
186 <citerefentry><refentrytitle>udev_monitor_new_from_netlink
</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
187 <citerefentry><refentrytitle>udev_list_entry
</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
188 <citerefentry><refentrytitle>systemd
</refentrytitle><manvolnum>1</manvolnum></citerefentry>,