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