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   This file is part of systemd.
  10
  11   Copyright 2015 David Herrmann <dh.herrmann@gmail.com>
  12
  13   systemd is free software; you can redistribute it and/or modify it
  14   under the terms of the GNU Lesser General Public License as published by
  15   the Free Software Foundation; either version 2.1 of the License, or
  16   (at your option) any later version.
  17
  18   systemd is distributed in the hope that it will be useful, but
  19   WITHOUT ANY WARRANTY; without even the implied warranty of
  20   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
  21   Lesser General Public License for more details.
  22
  23   You should have received a copy of the GNU Lesser General Public License
  24   along with systemd; If not, see <http://www.gnu.org/licenses/>.
  25 -->
  26
  27 <refentry id="udev_device_new_from_syspath"
  28   xmlns:xi="http://www.w3.org/2001/XInclude">
  29
  30   <refentryinfo>
  31     <title>udev_device_new_from_syspath</title>
  32     <productname>systemd</productname>
  33
  34     <authorgroup>
  35       <author>
  36         <contrib>Developer</contrib>
  37         <firstname>David</firstname>
  38         <surname>Herrmann</surname>
  39         <email>dh.herrmann@gmail.com</email>
  40       </author>
  41     </authorgroup>
  42   </refentryinfo>
  43
  44   <refmeta>
  45     <refentrytitle>udev_device_new_from_syspath</refentrytitle>
  46     <manvolnum>3</manvolnum>
  47   </refmeta>
  48
  49   <refnamediv>
  50     <refname>udev_device_new_from_syspath</refname>
  51     <refname>udev_device_new_from_devnum</refname>
  52     <refname>udev_device_new_from_subsystem_sysname</refname>
  53     <refname>udev_device_new_from_device_id</refname>
  54     <refname>udev_device_new_from_environment</refname>
  55     <refname>udev_device_ref</refname>
  56     <refname>udev_device_unref</refname>
  57
  58     <refpurpose>Create, acquire and release a udev device object</refpurpose>
  59   </refnamediv>
  60
  61   <refsynopsisdiv>
  62     <funcsynopsis>
  63       <funcsynopsisinfo>#include &lt;libudev.h&gt;</funcsynopsisinfo>
  64
  65       <funcprototype>
  66         <funcdef>struct udev_device *<function>udev_device_new_from_syspath</function></funcdef>
  67         <paramdef>struct udev *<parameter>udev</parameter></paramdef>
  68         <paramdef>const char *<parameter>syspath</parameter></paramdef>
  69       </funcprototype>
  70
  71       <funcprototype>
  72         <funcdef>struct udev_device *<function>udev_device_new_from_devnum</function></funcdef>
  73         <paramdef>struct udev *<parameter>udev</parameter></paramdef>
  74         <paramdef>char <parameter>type</parameter></paramdef>
  75         <paramdef>dev_t <parameter>devnum</parameter></paramdef>
  76       </funcprototype>
  77
  78       <funcprototype>
  79         <funcdef>struct udev_device *<function>udev_device_new_from_subsystem_sysname</function></funcdef>
  80         <paramdef>struct udev *<parameter>udev</parameter></paramdef>
  81         <paramdef>const char *<parameter>subsystem</parameter></paramdef>
  82         <paramdef>const char *<parameter>sysname</parameter></paramdef>
  83       </funcprototype>
  84
  85       <funcprototype>
  86         <funcdef>struct udev_device *<function>udev_device_new_from_device_id</function></funcdef>
  87         <paramdef>struct udev *<parameter>udev</parameter></paramdef>
  88         <paramdef>const char *<parameter>id</parameter></paramdef>
  89       </funcprototype>
  90
  91       <funcprototype>
  92         <funcdef>struct udev_device *<function>udev_device_new_from_environment</function></funcdef>
  93         <paramdef>struct udev *<parameter>udev</parameter></paramdef>
  94       </funcprototype>
  95
  96       <funcprototype>
  97         <funcdef>struct udev_device *<function>udev_device_ref</function></funcdef>
  98         <paramdef>struct udev_device *<parameter>udev_device</parameter></paramdef>
  99       </funcprototype>
 100
 101       <funcprototype>
 102         <funcdef>struct udev_device *<function>udev_device_unref</function></funcdef>
 103         <paramdef>struct udev_device *<parameter>udev_device</parameter></paramdef>
 104       </funcprototype>
 105
 106     </funcsynopsis>
 107   </refsynopsisdiv>
 108
 109   <refsect1>
 110     <title>Description</title>
 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>,
 115     <function>udev_device_new_from_device_id</function>, and
 116     <function>udev_device_new_from_environment</function>
 117     allocate a new udev device object and returns a pointer to it. This
 118     object is opaque and must not be accessed by the caller via different
 119     means than functions provided by libudev. Initially, the reference count
 120     of the device is 1. You can acquire further references, and drop
 121     gained references via <function>udev_device_ref()</function> and
 122     <function>udev_device_unref()</function>. Once the reference count hits 0,
 123     the device object is destroyed and freed.</para>
 124
 125     <para><function>udev_device_new_from_syspath</function>,
 126     <function>udev_device_new_from_devnum</function>,
 127     <function>udev_device_new_from_subsystem_sysname</function>, and
 128     <function>udev_device_new_from_device_id</function>
 129     create the device object based on information found in
 130     <filename>/sys</filename> annotated with properties from the udev-internal
 131     device database. A syspath is any subdirectory of <filename>/sys</filename>,
 132     with the restriction that a subdirectory of <filename>/sys/devices</filename>
 133     (or a symlink to one) represents a real device and as such must contain
 134     a <filename>uevent</filename> file. <function>udev_device_new_from_devnum</function>
 135     takes a device type, which can be <constant>b</constant> for block devices or
 136     <constant>c</constant> for character devices, as well as a devnum (see
 137     <citerefentry><refentrytitle>makedev</refentrytitle><manvolnum>3</manvolnum></citerefentry>).
 138     <function>udev_device_new_from_subsystem_sysname</function> looks up devices based
 139     on the provided subsystem and sysname and
 140     <function>udev_device_new_from_device_id</function> looks up devices based on the provided
 141     device id (see
 142     <citerefentry><refentrytitle>udev_device_get_subsystem</refentrytitle><manvolnum>3</manvolnum></citerefentry>).
 143     </para>
 144
 145     <para><function>udev_device_new_from_environment</function>
 146     creates a device from the current environment (see
 147     <citerefentry><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     <function>udev_device_ref()</function> returns the argument
 167     that it was passed, unmodified.
 168     <function>udev_device_unref()</function> always returns
 169     <constant>NULL</constant>.</para>
 170   </refsect1>
 171
 172   <refsect1>
 173     <title>See Also</title>
 174
 175     <para>
 176       <citerefentry><refentrytitle>udev_new</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 177       <citerefentry><refentrytitle>udev_device_get_syspath</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 178       <citerefentry><refentrytitle>udev_device_has_tag</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 179       <citerefentry><refentrytitle>udev_enumerate_new</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 180       <citerefentry><refentrytitle>udev_monitor_new_from_netlink</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 181       <citerefentry><refentrytitle>udev_list_entry</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 182       <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
 183     </para>
 184   </refsect1>
 185
 186 </refentry>