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   </refentryinfo>
  21
  22   <refmeta>
  23     <refentrytitle>udev_device_new_from_syspath</refentrytitle>
  24     <manvolnum>3</manvolnum>
  25   </refmeta>
  26
  27   <refnamediv>
  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>
  35
  36     <refpurpose>Create, acquire and release a udev device object</refpurpose>
  37   </refnamediv>
  38
  39   <refsynopsisdiv>
  40     <funcsynopsis>
  41       <funcsynopsisinfo>#include &lt;libudev.h&gt;</funcsynopsisinfo>
  42
  43       <funcprototype>
  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>
  47       </funcprototype>
  48
  49       <funcprototype>
  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>
  54       </funcprototype>
  55
  56       <funcprototype>
  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>
  61       </funcprototype>
  62
  63       <funcprototype>
  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>
  67       </funcprototype>
  68
  69       <funcprototype>
  70         <funcdef>struct udev_device *<function>udev_device_new_from_environment</function></funcdef>
  71         <paramdef>struct udev *<parameter>udev</parameter></paramdef>
  72       </funcprototype>
  73
  74       <funcprototype>
  75         <funcdef>struct udev_device *<function>udev_device_ref</function></funcdef>
  76         <paramdef>struct udev_device *<parameter>udev_device</parameter></paramdef>
  77       </funcprototype>
  78
  79       <funcprototype>
  80         <funcdef>struct udev_device *<function>udev_device_unref</function></funcdef>
  81         <paramdef>struct udev_device *<parameter>udev_device</parameter></paramdef>
  82       </funcprototype>
  83
  84     </funcsynopsis>
  85   </refsynopsisdiv>
  86
  87   <refsect1>
  88     <title>Description</title>
  89
  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>
 102
 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>
 119     and
 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:
 123     <table>
 124       <title>Device ID strings</title>
 125
 126       <tgroup cols='2'>
 127         <colspec colname='example' />
 128         <colspec colname='explanation' />
 129         <thead><row>
 130           <entry>Example</entry>
 131           <entry>Explanation</entry>
 132         </row></thead>
 133         <tbody>
 134           <row><entry><varname>b8:2</varname></entry>
 135           <entry>block device major:minor</entry></row>
 136
 137           <row><entry><varname>c128:1</varname></entry>
 138           <entry>char device major:minor</entry></row>
 139
 140           <row><entry><varname>n3</varname></entry>
 141           <entry>network device ifindex</entry></row>
 142
 143           <row><entry><varname>+sound:card29</varname></entry>
 144           <entry>kernel driver core subsystem:device name</entry></row>
 145         </tbody>
 146       </tgroup>
 147     </table>
 148     </para>
 149
 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>
 158
 159   </refsect1>
 160
 161   <refsect1>
 162     <title>Return Value</title>
 163
 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>
 176   </refsect1>
 177
 178   <refsect1>
 179     <title>See Also</title>
 180
 181     <para>
 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>,
 189     </para>
 190   </refsect1>
 191
 192 </refentry>