1<?xml version='1.0'?> <!--*-nxml-*-->
2<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
3  "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd" [
4<!ENTITY % entities SYSTEM "custom-entities.ent" >
5%entities;
6]>
7<!-- SPDX-License-Identifier: LGPL-2.1-or-later -->
8
9<refentry id="udev_device_new_from_syspath"
10  xmlns:xi="http://www.w3.org/2001/XInclude">
11
12  <refentryinfo>
13    <title>udev_device_new_from_syspath</title>
14    <productname>systemd</productname>
15  </refentryinfo>
16
17  <refmeta>
18    <refentrytitle>udev_device_new_from_syspath</refentrytitle>
19    <manvolnum>3</manvolnum>
20  </refmeta>
21
22  <refnamediv>
23    <refname>udev_device_new_from_syspath</refname>
24    <refname>udev_device_new_from_devnum</refname>
25    <refname>udev_device_new_from_subsystem_sysname</refname>
26    <refname>udev_device_new_from_device_id</refname>
27    <refname>udev_device_new_from_environment</refname>
28    <refname>udev_device_ref</refname>
29    <refname>udev_device_unref</refname>
30
31    <refpurpose>Create, acquire and release a udev device object</refpurpose>
32  </refnamediv>
33
34  <refsynopsisdiv>
35    <funcsynopsis>
36      <funcsynopsisinfo>#include &lt;libudev.h&gt;</funcsynopsisinfo>
37
38      <funcprototype>
39        <funcdef>struct udev_device *<function>udev_device_new_from_syspath</function></funcdef>
40        <paramdef>struct udev *<parameter>udev</parameter></paramdef>
41        <paramdef>const char *<parameter>syspath</parameter></paramdef>
42      </funcprototype>
43
44      <funcprototype>
45        <funcdef>struct udev_device *<function>udev_device_new_from_devnum</function></funcdef>
46        <paramdef>struct udev *<parameter>udev</parameter></paramdef>
47        <paramdef>char <parameter>type</parameter></paramdef>
48        <paramdef>dev_t <parameter>devnum</parameter></paramdef>
49      </funcprototype>
50
51      <funcprototype>
52        <funcdef>struct udev_device *<function>udev_device_new_from_subsystem_sysname</function></funcdef>
53        <paramdef>struct udev *<parameter>udev</parameter></paramdef>
54        <paramdef>const char *<parameter>subsystem</parameter></paramdef>
55        <paramdef>const char *<parameter>sysname</parameter></paramdef>
56      </funcprototype>
57
58      <funcprototype>
59        <funcdef>struct udev_device *<function>udev_device_new_from_device_id</function></funcdef>
60        <paramdef>struct udev *<parameter>udev</parameter></paramdef>
61        <paramdef>const char *<parameter>id</parameter></paramdef>
62      </funcprototype>
63
64      <funcprototype>
65        <funcdef>struct udev_device *<function>udev_device_new_from_environment</function></funcdef>
66        <paramdef>struct udev *<parameter>udev</parameter></paramdef>
67      </funcprototype>
68
69      <funcprototype>
70        <funcdef>struct udev_device *<function>udev_device_ref</function></funcdef>
71        <paramdef>struct udev_device *<parameter>udev_device</parameter></paramdef>
72      </funcprototype>
73
74      <funcprototype>
75        <funcdef>struct udev_device *<function>udev_device_unref</function></funcdef>
76        <paramdef>struct udev_device *<parameter>udev_device</parameter></paramdef>
77      </funcprototype>
78
79    </funcsynopsis>
80  </refsynopsisdiv>
81
82  <refsect1>
83    <title>Description</title>
84
85    <para><function>udev_device_new_from_syspath()</function>,
86    <function>udev_device_new_from_devnum()</function>,
87    <function>udev_device_new_from_subsystem_sysname()</function>,
88    <function>udev_device_new_from_device_id()</function>, and
89    <function>udev_device_new_from_environment()</function>
90    allocate a new udev device object and returns a pointer to it. This
91    object is opaque and must not be accessed by the caller via different
92    means than functions provided by libudev. Initially, the reference count
93    of the device is 1. You can acquire further references, and drop
94    gained references via <function>udev_device_ref()</function> and
95    <function>udev_device_unref()</function>. Once the reference count hits 0,
96    the device object is destroyed and freed.</para>
97
98    <para><function>udev_device_new_from_syspath()</function>,
99    <function>udev_device_new_from_devnum()</function>,
100    <function>udev_device_new_from_subsystem_sysname()</function>, and
101    <function>udev_device_new_from_device_id()</function>
102    create the device object based on information found in
103    <filename>/sys/</filename>, annotated with properties from the udev-internal
104    device database. A syspath is any subdirectory of <filename>/sys/</filename>,
105    with the restriction that a subdirectory of <filename>/sys/devices</filename>
106    (or a symlink to one) represents a real device and as such must contain
107    a <filename>uevent</filename> file. <function>udev_device_new_from_devnum()</function>
108    takes a device type, which can be <constant>b</constant> for block devices or
109    <constant>c</constant> for character devices, as well as a devnum (see
110    <citerefentry project='man-pages'><refentrytitle>makedev</refentrytitle><manvolnum>3</manvolnum></citerefentry>).
111    <function>udev_device_new_from_subsystem_sysname()</function> looks up devices based
112    on the provided subsystem and sysname
113    (see <citerefentry><refentrytitle>udev_device_get_subsystem</refentrytitle><manvolnum>3</manvolnum></citerefentry>
114    and
115    <citerefentry><refentrytitle>udev_device_get_sysname</refentrytitle><manvolnum>3</manvolnum></citerefentry>)
116    and <function>udev_device_new_from_device_id()</function> looks up devices based on the provided
117    device ID, which is a special string in one of the following four forms:
118    <table>
119      <title>Device ID strings</title>
120
121      <tgroup cols='2'>
122        <colspec colname='example' />
123        <colspec colname='explanation' />
124        <thead><row>
125          <entry>Example</entry>
126          <entry>Explanation</entry>
127        </row></thead>
128        <tbody>
129          <row><entry><varname>b8:2</varname></entry>
130          <entry>block device major:minor</entry></row>
131
132          <row><entry><varname>c128:1</varname></entry>
133          <entry>char device major:minor</entry></row>
134
135          <row><entry><varname>n3</varname></entry>
136          <entry>network device ifindex</entry></row>
137
138          <row><entry><varname>+sound:card29</varname></entry>
139          <entry>kernel driver core subsystem:device name</entry></row>
140        </tbody>
141      </tgroup>
142    </table>
143    </para>
144
145    <para><function>udev_device_new_from_environment()</function>
146    creates a device from the current environment (see
147    <citerefentry project='man-pages'><refentrytitle>environ</refentrytitle><manvolnum>7</manvolnum></citerefentry>).
148    Each key-value pair is interpreted in the same way as if it was
149    received in an uevent (see
150    <citerefentry><refentrytitle>udev_monitor_receive_device</refentrytitle><manvolnum>3</manvolnum></citerefentry>).
151    The keys <constant>DEVPATH</constant>, <constant>SUBSYSTEM</constant>,
152    <constant>ACTION</constant>, and <constant>SEQNUM</constant> are mandatory.</para>
153
154  </refsect1>
155
156  <refsect1>
157    <title>Return Value</title>
158
159    <para>On success, <function>udev_device_new_from_syspath()</function>,
160    <function>udev_device_new_from_devnum()</function>,
161    <function>udev_device_new_from_subsystem_sysname()</function>,
162    <function>udev_device_new_from_device_id()</function> and
163    <function>udev_device_new_from_environment()</function> return a
164    pointer to the allocated udev device. On failure,
165    <constant>NULL</constant> is returned,
166    and <varname>errno</varname> is set appropriately.
167    <function>udev_device_ref()</function> returns the argument
168    that it was passed, unmodified.
169    <function>udev_device_unref()</function> always returns
170    <constant>NULL</constant>.</para>
171  </refsect1>
172
173  <refsect1>
174    <title>See Also</title>
175
176    <para>
177      <citerefentry><refentrytitle>udev_new</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
178      <citerefentry><refentrytitle>udev_device_get_syspath</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
179      <citerefentry><refentrytitle>udev_device_has_tag</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
180      <citerefentry><refentrytitle>udev_enumerate_new</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
181      <citerefentry><refentrytitle>udev_monitor_new_from_netlink</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
182      <citerefentry><refentrytitle>udev_list_entry</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
183      <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
184    </para>
185  </refsect1>
186
187</refentry>
188