214 lines
9.1 KiB
XML
214 lines
9.1 KiB
XML
<?xml version='1.0'?> <!--*-nxml-*-->
|
|
<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
|
|
"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd" [
|
|
<!ENTITY % entities SYSTEM "custom-entities.ent" >
|
|
%entities;
|
|
]>
|
|
|
|
<!--
|
|
This file is part of systemd.
|
|
|
|
Copyright 2015 David Herrmann <dh.herrmann@gmail.com>
|
|
|
|
systemd is free software; you can redistribute it and/or modify it
|
|
under the terms of the GNU Lesser General Public License as published by
|
|
the Free Software Foundation; either version 2.1 of the License, or
|
|
(at your option) any later version.
|
|
|
|
systemd is distributed in the hope that it will be useful, but
|
|
WITHOUT ANY WARRANTY; without even the implied warranty of
|
|
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
|
|
Lesser General Public License for more details.
|
|
|
|
You should have received a copy of the GNU Lesser General Public License
|
|
along with systemd; If not, see <http://www.gnu.org/licenses/>.
|
|
-->
|
|
|
|
<refentry id="udev_device_new_from_syspath"
|
|
xmlns:xi="http://www.w3.org/2001/XInclude">
|
|
|
|
<refentryinfo>
|
|
<title>udev_device_new_from_syspath</title>
|
|
<productname>systemd</productname>
|
|
|
|
<authorgroup>
|
|
<author>
|
|
<contrib>Developer</contrib>
|
|
<firstname>David</firstname>
|
|
<surname>Herrmann</surname>
|
|
<email>dh.herrmann@gmail.com</email>
|
|
</author>
|
|
</authorgroup>
|
|
</refentryinfo>
|
|
|
|
<refmeta>
|
|
<refentrytitle>udev_device_new_from_syspath</refentrytitle>
|
|
<manvolnum>3</manvolnum>
|
|
</refmeta>
|
|
|
|
<refnamediv>
|
|
<refname>udev_device_new_from_syspath</refname>
|
|
<refname>udev_device_new_from_devnum</refname>
|
|
<refname>udev_device_new_from_subsystem_sysname</refname>
|
|
<refname>udev_device_new_from_device_id</refname>
|
|
<refname>udev_device_new_from_environment</refname>
|
|
<refname>udev_device_ref</refname>
|
|
<refname>udev_device_unref</refname>
|
|
|
|
<refpurpose>Create, acquire and release a udev device object</refpurpose>
|
|
</refnamediv>
|
|
|
|
<refsynopsisdiv>
|
|
<funcsynopsis>
|
|
<funcsynopsisinfo>#include <libudev.h></funcsynopsisinfo>
|
|
|
|
<funcprototype>
|
|
<funcdef>struct udev_device *<function>udev_device_new_from_syspath</function></funcdef>
|
|
<paramdef>struct udev *<parameter>udev</parameter></paramdef>
|
|
<paramdef>const char *<parameter>syspath</parameter></paramdef>
|
|
</funcprototype>
|
|
|
|
<funcprototype>
|
|
<funcdef>struct udev_device *<function>udev_device_new_from_devnum</function></funcdef>
|
|
<paramdef>struct udev *<parameter>udev</parameter></paramdef>
|
|
<paramdef>char <parameter>type</parameter></paramdef>
|
|
<paramdef>dev_t <parameter>devnum</parameter></paramdef>
|
|
</funcprototype>
|
|
|
|
<funcprototype>
|
|
<funcdef>struct udev_device *<function>udev_device_new_from_subsystem_sysname</function></funcdef>
|
|
<paramdef>struct udev *<parameter>udev</parameter></paramdef>
|
|
<paramdef>const char *<parameter>subsystem</parameter></paramdef>
|
|
<paramdef>const char *<parameter>sysname</parameter></paramdef>
|
|
</funcprototype>
|
|
|
|
<funcprototype>
|
|
<funcdef>struct udev_device *<function>udev_device_new_from_device_id</function></funcdef>
|
|
<paramdef>struct udev *<parameter>udev</parameter></paramdef>
|
|
<paramdef>const char *<parameter>id</parameter></paramdef>
|
|
</funcprototype>
|
|
|
|
<funcprototype>
|
|
<funcdef>struct udev_device *<function>udev_device_new_from_environment</function></funcdef>
|
|
<paramdef>struct udev *<parameter>udev</parameter></paramdef>
|
|
</funcprototype>
|
|
|
|
<funcprototype>
|
|
<funcdef>struct udev_device *<function>udev_device_ref</function></funcdef>
|
|
<paramdef>struct udev_device *<parameter>udev_device</parameter></paramdef>
|
|
</funcprototype>
|
|
|
|
<funcprototype>
|
|
<funcdef>struct udev_device *<function>udev_device_unref</function></funcdef>
|
|
<paramdef>struct udev_device *<parameter>udev_device</parameter></paramdef>
|
|
</funcprototype>
|
|
|
|
</funcsynopsis>
|
|
</refsynopsisdiv>
|
|
|
|
<refsect1>
|
|
<title>Description</title>
|
|
|
|
<para><function>udev_device_new_from_syspath</function>,
|
|
<function>udev_device_new_from_devnum</function>,
|
|
<function>udev_device_new_from_subsystem_sysname</function>,
|
|
<function>udev_device_new_from_device_id</function>, and
|
|
<function>udev_device_new_from_environment</function>
|
|
allocate a new udev device object and returns a pointer to it. This
|
|
object is opaque and must not be accessed by the caller via different
|
|
means than functions provided by libudev. Initially, the reference count
|
|
of the device is 1. You can acquire further references, and drop
|
|
gained references via <function>udev_device_ref()</function> and
|
|
<function>udev_device_unref()</function>. Once the reference count hits 0,
|
|
the device object is destroyed and freed.</para>
|
|
|
|
<para><function>udev_device_new_from_syspath</function>,
|
|
<function>udev_device_new_from_devnum</function>,
|
|
<function>udev_device_new_from_subsystem_sysname</function>, and
|
|
<function>udev_device_new_from_device_id</function>
|
|
create the device object based on information found in
|
|
<filename>/sys</filename>, annotated with properties from the udev-internal
|
|
device database. A syspath is any subdirectory of <filename>/sys</filename>,
|
|
with the restriction that a subdirectory of <filename>/sys/devices</filename>
|
|
(or a symlink to one) represents a real device and as such must contain
|
|
a <filename>uevent</filename> file. <function>udev_device_new_from_devnum</function>
|
|
takes a device type, which can be <constant>b</constant> for block devices or
|
|
<constant>c</constant> for character devices, as well as a devnum (see
|
|
<citerefentry><refentrytitle>makedev</refentrytitle><manvolnum>3</manvolnum></citerefentry>).
|
|
<function>udev_device_new_from_subsystem_sysname</function> looks up devices based
|
|
on the provided subsystem and sysname
|
|
(see <citerefentry><refentrytitle>udev_device_get_subsystem</refentrytitle><manvolnum>3</manvolnum></citerefentry>
|
|
and
|
|
<citerefentry><refentrytitle>udev_device_get_sysname</refentrytitle><manvolnum>3</manvolnum></citerefentry>)
|
|
and <function>udev_device_new_from_device_id</function> looks up devices based on the provided
|
|
device ID, which is a special string in one of the following four forms:
|
|
<table>
|
|
<title>Device ID strings</title>
|
|
|
|
<tgroup cols='2'>
|
|
<colspec colname='example' />
|
|
<colspec colname='explanation' />
|
|
<thead><row>
|
|
<entry>Example</entry>
|
|
<entry>Explanation</entry>
|
|
</row></thead>
|
|
<tbody>
|
|
<row><entry><varname>b8:2</varname></entry>
|
|
<entry>block device major:minor</entry></row>
|
|
|
|
<row><entry><varname>c128:1</varname></entry>
|
|
<entry>char device major:minor</entry></row>
|
|
|
|
<row><entry><varname>n3</varname></entry>
|
|
<entry>network device ifindex</entry></row>
|
|
|
|
<row><entry><varname>+sound:card29</varname></entry>
|
|
<entry>kernel driver core subsystem:device name</entry></row>
|
|
</tbody>
|
|
</tgroup>
|
|
</table>
|
|
</para>
|
|
|
|
<para><function>udev_device_new_from_environment</function>
|
|
creates a device from the current environment (see
|
|
<citerefentry><refentrytitle>environ</refentrytitle><manvolnum>7</manvolnum></citerefentry>).
|
|
Each key-value pair is interpreted in the same way as if it was
|
|
received in an uevent (see
|
|
<citerefentry><refentrytitle>udev_monitor_receive_device</refentrytitle><manvolnum>3</manvolnum></citerefentry>).
|
|
The keys <constant>DEVPATH</constant>, <constant>SUBSYSTEM</constant>,
|
|
<constant>ACTION</constant>, and <constant>SEQNUM</constant> are mandatory.</para>
|
|
|
|
</refsect1>
|
|
|
|
<refsect1>
|
|
<title>Return Value</title>
|
|
|
|
<para>On success, <function>udev_device_new_from_syspath()</function>,
|
|
<function>udev_device_new_from_devnum()</function>,
|
|
<function>udev_device_new_from_subsystem_sysname()</function>,
|
|
<function>udev_device_new_from_device_id()</function> and
|
|
<function>udev_device_new_from_environment()</function> return a
|
|
pointer to the allocated udev device. On failure,
|
|
<constant>NULL</constant> is returned.
|
|
<function>udev_device_ref()</function> returns the argument
|
|
that it was passed, unmodified.
|
|
<function>udev_device_unref()</function> always returns
|
|
<constant>NULL</constant>.</para>
|
|
</refsect1>
|
|
|
|
<refsect1>
|
|
<title>See Also</title>
|
|
|
|
<para>
|
|
<citerefentry><refentrytitle>udev_new</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
|
|
<citerefentry><refentrytitle>udev_device_get_syspath</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
|
|
<citerefentry><refentrytitle>udev_device_has_tag</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
|
|
<citerefentry><refentrytitle>udev_enumerate_new</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
|
|
<citerefentry><refentrytitle>udev_monitor_new_from_netlink</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
|
|
<citerefentry><refentrytitle>udev_list_entry</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
|
|
<citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
|
|
</para>
|
|
</refsect1>
|
|
|
|
</refentry>
|