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