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