man/udev_device_new_from_syspath.xml

   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+ -->
   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>