man/udev_device_new_from_syspath.xml

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