mirror of
https://github.com/systemd/systemd.git
synced 2024-11-23 10:13:34 +08:00
199 lines
9.0 KiB
XML
199 lines
9.0 KiB
XML
<?xml version='1.0'?> <!--*-nxml-*-->
|
|
<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
|
|
"http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
|
|
<!ENTITY % entities SYSTEM "custom-entities.ent" >
|
|
%entities;
|
|
]>
|
|
<!-- SPDX-License-Identifier: LGPL-2.1-or-later -->
|
|
|
|
<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>
|
|
</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 project='man-pages'><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 project='man-pages'><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,
|
|
and <varname>errno</varname> is set appropriately.
|
|
<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>History</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>,
|
|
<function>udev_device_new_from_environment()</function>,
|
|
<function>udev_device_ref()</function>, and
|
|
<function>udev_device_unref()</function> were added in version 221.</para>
|
|
</refsect1>
|
|
|
|
<refsect1>
|
|
<title>See Also</title>
|
|
|
|
<para><simplelist type="inline">
|
|
<member><citerefentry><refentrytitle>udev_new</refentrytitle><manvolnum>3</manvolnum></citerefentry></member>
|
|
<member><citerefentry><refentrytitle>udev_device_get_syspath</refentrytitle><manvolnum>3</manvolnum></citerefentry></member>
|
|
<member><citerefentry><refentrytitle>udev_device_has_tag</refentrytitle><manvolnum>3</manvolnum></citerefentry></member>
|
|
<member><citerefentry><refentrytitle>udev_enumerate_new</refentrytitle><manvolnum>3</manvolnum></citerefentry></member>
|
|
<member><citerefentry><refentrytitle>udev_monitor_new_from_netlink</refentrytitle><manvolnum>3</manvolnum></citerefentry></member>
|
|
<member><citerefentry><refentrytitle>udev_list_entry</refentrytitle><manvolnum>3</manvolnum></citerefentry></member>
|
|
<member><citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry></member>
|
|
</simplelist></para>
|
|
</refsect1>
|
|
|
|
</refentry>
|