06255d6f76f3f630a9634d745a48910b1ea3e4d3David Herrmann<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
06255d6f76f3f630a9634d745a48910b1ea3e4d3David Herrmann "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd" [
06255d6f76f3f630a9634d745a48910b1ea3e4d3David Herrmann<!ENTITY % entities SYSTEM "custom-entities.ent" >
06255d6f76f3f630a9634d745a48910b1ea3e4d3David Herrmann This file is part of systemd.
06255d6f76f3f630a9634d745a48910b1ea3e4d3David Herrmann Copyright 2015 David Herrmann <dh.herrmann@gmail.com>
06255d6f76f3f630a9634d745a48910b1ea3e4d3David Herrmann systemd is free software; you can redistribute it and/or modify it
06255d6f76f3f630a9634d745a48910b1ea3e4d3David Herrmann under the terms of the GNU Lesser General Public License as published by
06255d6f76f3f630a9634d745a48910b1ea3e4d3David Herrmann the Free Software Foundation; either version 2.1 of the License, or
06255d6f76f3f630a9634d745a48910b1ea3e4d3David Herrmann (at your option) any later version.
06255d6f76f3f630a9634d745a48910b1ea3e4d3David Herrmann systemd is distributed in the hope that it will be useful, but
06255d6f76f3f630a9634d745a48910b1ea3e4d3David Herrmann WITHOUT ANY WARRANTY; without even the implied warranty of
06255d6f76f3f630a9634d745a48910b1ea3e4d3David Herrmann MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
06255d6f76f3f630a9634d745a48910b1ea3e4d3David Herrmann Lesser General Public License for more details.
06255d6f76f3f630a9634d745a48910b1ea3e4d3David Herrmann You should have received a copy of the GNU Lesser General Public License
06255d6f76f3f630a9634d745a48910b1ea3e4d3David Herrmann along with systemd; If not, see <http://www.gnu.org/licenses/>.
06255d6f76f3f630a9634d745a48910b1ea3e4d3David Herrmann <refentryinfo>
06255d6f76f3f630a9634d745a48910b1ea3e4d3David Herrmann <authorgroup>
06255d6f76f3f630a9634d745a48910b1ea3e4d3David Herrmann </authorgroup>
06255d6f76f3f630a9634d745a48910b1ea3e4d3David Herrmann </refentryinfo>
06255d6f76f3f630a9634d745a48910b1ea3e4d3David Herrmann <refentrytitle>udev_device_new_from_syspath</refentrytitle>
06255d6f76f3f630a9634d745a48910b1ea3e4d3David Herrmann <refname>udev_device_new_from_syspath</refname>
06255d6f76f3f630a9634d745a48910b1ea3e4d3David Herrmann <refname>udev_device_new_from_devnum</refname>
06255d6f76f3f630a9634d745a48910b1ea3e4d3David Herrmann <refname>udev_device_new_from_subsystem_sysname</refname>
06255d6f76f3f630a9634d745a48910b1ea3e4d3David Herrmann <refname>udev_device_new_from_device_id</refname>
06255d6f76f3f630a9634d745a48910b1ea3e4d3David Herrmann <refname>udev_device_new_from_environment</refname>
06255d6f76f3f630a9634d745a48910b1ea3e4d3David Herrmann <refpurpose>Create, acquire and release a udev device object</refpurpose>
06255d6f76f3f630a9634d745a48910b1ea3e4d3David Herrmann </refnamediv>
06255d6f76f3f630a9634d745a48910b1ea3e4d3David Herrmann <refsynopsisdiv>
06255d6f76f3f630a9634d745a48910b1ea3e4d3David Herrmann <funcsynopsis>
06255d6f76f3f630a9634d745a48910b1ea3e4d3David Herrmann <funcsynopsisinfo>#include <libudev.h></funcsynopsisinfo>
06255d6f76f3f630a9634d745a48910b1ea3e4d3David Herrmann <funcprototype>
06255d6f76f3f630a9634d745a48910b1ea3e4d3David Herrmann <funcdef>struct udev_device *<function>udev_device_new_from_syspath</function></funcdef>
06255d6f76f3f630a9634d745a48910b1ea3e4d3David Herrmann <paramdef>struct udev *<parameter>udev</parameter></paramdef>
06255d6f76f3f630a9634d745a48910b1ea3e4d3David Herrmann <paramdef>const char *<parameter>syspath</parameter></paramdef>
06255d6f76f3f630a9634d745a48910b1ea3e4d3David Herrmann </funcprototype>
06255d6f76f3f630a9634d745a48910b1ea3e4d3David Herrmann <funcprototype>
06255d6f76f3f630a9634d745a48910b1ea3e4d3David Herrmann <funcdef>struct udev_device *<function>udev_device_new_from_devnum</function></funcdef>
06255d6f76f3f630a9634d745a48910b1ea3e4d3David Herrmann <paramdef>struct udev *<parameter>udev</parameter></paramdef>
06255d6f76f3f630a9634d745a48910b1ea3e4d3David Herrmann <paramdef>char <parameter>type</parameter></paramdef>
06255d6f76f3f630a9634d745a48910b1ea3e4d3David Herrmann <paramdef>dev_t <parameter>devnum</parameter></paramdef>
06255d6f76f3f630a9634d745a48910b1ea3e4d3David Herrmann </funcprototype>
06255d6f76f3f630a9634d745a48910b1ea3e4d3David Herrmann <funcprototype>
06255d6f76f3f630a9634d745a48910b1ea3e4d3David Herrmann <funcdef>struct udev_device *<function>udev_device_new_from_subsystem_sysname</function></funcdef>
06255d6f76f3f630a9634d745a48910b1ea3e4d3David Herrmann <paramdef>struct udev *<parameter>udev</parameter></paramdef>
06255d6f76f3f630a9634d745a48910b1ea3e4d3David Herrmann <paramdef>const char *<parameter>subsystem</parameter></paramdef>
06255d6f76f3f630a9634d745a48910b1ea3e4d3David Herrmann <paramdef>const char *<parameter>sysname</parameter></paramdef>
06255d6f76f3f630a9634d745a48910b1ea3e4d3David Herrmann </funcprototype>
06255d6f76f3f630a9634d745a48910b1ea3e4d3David Herrmann <funcprototype>
06255d6f76f3f630a9634d745a48910b1ea3e4d3David Herrmann <funcdef>struct udev_device *<function>udev_device_new_from_device_id</function></funcdef>
06255d6f76f3f630a9634d745a48910b1ea3e4d3David Herrmann <paramdef>struct udev *<parameter>udev</parameter></paramdef>
06255d6f76f3f630a9634d745a48910b1ea3e4d3David Herrmann <paramdef>const char *<parameter>id</parameter></paramdef>
06255d6f76f3f630a9634d745a48910b1ea3e4d3David Herrmann </funcprototype>
06255d6f76f3f630a9634d745a48910b1ea3e4d3David Herrmann <funcprototype>
06255d6f76f3f630a9634d745a48910b1ea3e4d3David Herrmann <funcdef>struct udev_device *<function>udev_device_new_from_environment</function></funcdef>
06255d6f76f3f630a9634d745a48910b1ea3e4d3David Herrmann <paramdef>struct udev *<parameter>udev</parameter></paramdef>
06255d6f76f3f630a9634d745a48910b1ea3e4d3David Herrmann </funcprototype>
06255d6f76f3f630a9634d745a48910b1ea3e4d3David Herrmann <funcprototype>
06255d6f76f3f630a9634d745a48910b1ea3e4d3David Herrmann <funcdef>struct udev_device *<function>udev_device_ref</function></funcdef>
06255d6f76f3f630a9634d745a48910b1ea3e4d3David Herrmann <paramdef>struct udev_device *<parameter>udev_device</parameter></paramdef>
06255d6f76f3f630a9634d745a48910b1ea3e4d3David Herrmann </funcprototype>
06255d6f76f3f630a9634d745a48910b1ea3e4d3David Herrmann <funcprototype>
06255d6f76f3f630a9634d745a48910b1ea3e4d3David Herrmann <funcdef>struct udev_device *<function>udev_device_unref</function></funcdef>
06255d6f76f3f630a9634d745a48910b1ea3e4d3David Herrmann <paramdef>struct udev_device *<parameter>udev_device</parameter></paramdef>
06255d6f76f3f630a9634d745a48910b1ea3e4d3David Herrmann </funcprototype>
06255d6f76f3f630a9634d745a48910b1ea3e4d3David Herrmann </funcsynopsis>
06255d6f76f3f630a9634d745a48910b1ea3e4d3David Herrmann </refsynopsisdiv>
00dbd902e9d55694cfb7c143ab54e8c08484d28eTom Gundersen <para><function>udev_device_new_from_syspath</function>,
00dbd902e9d55694cfb7c143ab54e8c08484d28eTom Gundersen <function>udev_device_new_from_devnum</function>,
00dbd902e9d55694cfb7c143ab54e8c08484d28eTom Gundersen <function>udev_device_new_from_subsystem_sysname</function>,
00dbd902e9d55694cfb7c143ab54e8c08484d28eTom Gundersen <function>udev_device_new_from_device_id</function>, and
00dbd902e9d55694cfb7c143ab54e8c08484d28eTom Gundersen <function>udev_device_new_from_environment</function>
00dbd902e9d55694cfb7c143ab54e8c08484d28eTom Gundersen allocate a new udev device object and returns a pointer to it. This
00dbd902e9d55694cfb7c143ab54e8c08484d28eTom Gundersen object is opaque and must not be accessed by the caller via different
00dbd902e9d55694cfb7c143ab54e8c08484d28eTom Gundersen means than functions provided by libudev. Initially, the reference count
00dbd902e9d55694cfb7c143ab54e8c08484d28eTom Gundersen of the device is 1. You can acquire further references, and drop
00dbd902e9d55694cfb7c143ab54e8c08484d28eTom Gundersen gained references via <function>udev_device_ref()</function> and
00dbd902e9d55694cfb7c143ab54e8c08484d28eTom Gundersen <function>udev_device_unref()</function>. Once the reference count hits 0,
00dbd902e9d55694cfb7c143ab54e8c08484d28eTom Gundersen the device object is destroyed and freed.</para>
00dbd902e9d55694cfb7c143ab54e8c08484d28eTom Gundersen <para><function>udev_device_new_from_syspath</function>,
00dbd902e9d55694cfb7c143ab54e8c08484d28eTom Gundersen <function>udev_device_new_from_devnum</function>,
00dbd902e9d55694cfb7c143ab54e8c08484d28eTom Gundersen <function>udev_device_new_from_subsystem_sysname</function>, and
00dbd902e9d55694cfb7c143ab54e8c08484d28eTom Gundersen <function>udev_device_new_from_device_id</function>
00dbd902e9d55694cfb7c143ab54e8c08484d28eTom Gundersen create the device object based on information found in
b938cb902c3b5bca807a94b277672c64d6767886Jan Engelhardt <filename>/sys</filename>, annotated with properties from the udev-internal
00dbd902e9d55694cfb7c143ab54e8c08484d28eTom Gundersen device database. A syspath is any subdirectory of <filename>/sys</filename>,
00dbd902e9d55694cfb7c143ab54e8c08484d28eTom Gundersen with the restriction that a subdirectory of <filename>/sys/devices</filename>
00dbd902e9d55694cfb7c143ab54e8c08484d28eTom Gundersen (or a symlink to one) represents a real device and as such must contain
00dbd902e9d55694cfb7c143ab54e8c08484d28eTom Gundersen a <filename>uevent</filename> file. <function>udev_device_new_from_devnum</function>
00dbd902e9d55694cfb7c143ab54e8c08484d28eTom Gundersen takes a device type, which can be <constant>b</constant> for block devices or
00dbd902e9d55694cfb7c143ab54e8c08484d28eTom Gundersen <constant>c</constant> for character devices, as well as a devnum (see
524f3e5c9d1eb2fba3d0b65d1790018163ba0b20Zbigniew Jędrzejewski-Szmek <citerefentry project='man-pages'><refentrytitle>makedev</refentrytitle><manvolnum>3</manvolnum></citerefentry>).
00dbd902e9d55694cfb7c143ab54e8c08484d28eTom Gundersen <function>udev_device_new_from_subsystem_sysname</function> looks up devices based
2ef24a16ac054bc06c3a2520e0d8e862eeea65f8Tom Gundersen on the provided subsystem and sysname
2ef24a16ac054bc06c3a2520e0d8e862eeea65f8Tom Gundersen (see <citerefentry><refentrytitle>udev_device_get_subsystem</refentrytitle><manvolnum>3</manvolnum></citerefentry>
2ef24a16ac054bc06c3a2520e0d8e862eeea65f8Tom Gundersen <citerefentry><refentrytitle>udev_device_get_sysname</refentrytitle><manvolnum>3</manvolnum></citerefentry>)
2ef24a16ac054bc06c3a2520e0d8e862eeea65f8Tom Gundersen and <function>udev_device_new_from_device_id</function> looks up devices based on the provided
a8eaaee72a2f06e0fb64fb71de3b71ecba31dafbJan Engelhardt device ID, which is a special string in one of the following four forms:
2ef24a16ac054bc06c3a2520e0d8e862eeea65f8Tom Gundersen <row><entry><varname>+sound:card29</varname></entry>
2ef24a16ac054bc06c3a2520e0d8e862eeea65f8Tom Gundersen <entry>kernel driver core subsystem:device name</entry></row>
00dbd902e9d55694cfb7c143ab54e8c08484d28eTom Gundersen <para><function>udev_device_new_from_environment</function>
00dbd902e9d55694cfb7c143ab54e8c08484d28eTom Gundersen creates a device from the current environment (see
524f3e5c9d1eb2fba3d0b65d1790018163ba0b20Zbigniew Jędrzejewski-Szmek <citerefentry project='man-pages'><refentrytitle>environ</refentrytitle><manvolnum>7</manvolnum></citerefentry>).
00dbd902e9d55694cfb7c143ab54e8c08484d28eTom Gundersen Each key-value pair is interpreted in the same way as if it was
00dbd902e9d55694cfb7c143ab54e8c08484d28eTom Gundersen received in an uevent (see
00dbd902e9d55694cfb7c143ab54e8c08484d28eTom Gundersen <citerefentry><refentrytitle>udev_monitor_receive_device</refentrytitle><manvolnum>3</manvolnum></citerefentry>).
00dbd902e9d55694cfb7c143ab54e8c08484d28eTom Gundersen The keys <constant>DEVPATH</constant>, <constant>SUBSYSTEM</constant>,
00dbd902e9d55694cfb7c143ab54e8c08484d28eTom Gundersen <constant>ACTION</constant>, and <constant>SEQNUM</constant> are mandatory.</para>
06255d6f76f3f630a9634d745a48910b1ea3e4d3David Herrmann <para>On success, <function>udev_device_new_from_syspath()</function>,
06255d6f76f3f630a9634d745a48910b1ea3e4d3David Herrmann <function>udev_device_new_from_devnum()</function>,
06255d6f76f3f630a9634d745a48910b1ea3e4d3David Herrmann <function>udev_device_new_from_subsystem_sysname()</function>,
06255d6f76f3f630a9634d745a48910b1ea3e4d3David Herrmann <function>udev_device_new_from_device_id()</function> and
06255d6f76f3f630a9634d745a48910b1ea3e4d3David Herrmann <function>udev_device_new_from_environment()</function> return a
06255d6f76f3f630a9634d745a48910b1ea3e4d3David Herrmann pointer to the allocated udev device. On failure,
f471010353f6ab4a32d33968ee8d677454f4af0cMichal Sekletar and <varname>errno</varname> is set appropriately.
06255d6f76f3f630a9634d745a48910b1ea3e4d3David Herrmann <function>udev_device_ref()</function> returns the argument
06255d6f76f3f630a9634d745a48910b1ea3e4d3David Herrmann that it was passed, unmodified.
06255d6f76f3f630a9634d745a48910b1ea3e4d3David Herrmann <function>udev_device_unref()</function> always returns
06255d6f76f3f630a9634d745a48910b1ea3e4d3David Herrmann <citerefentry><refentrytitle>udev_new</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
06255d6f76f3f630a9634d745a48910b1ea3e4d3David Herrmann <citerefentry><refentrytitle>udev_device_get_syspath</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
06255d6f76f3f630a9634d745a48910b1ea3e4d3David Herrmann <citerefentry><refentrytitle>udev_device_has_tag</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
06255d6f76f3f630a9634d745a48910b1ea3e4d3David Herrmann <citerefentry><refentrytitle>udev_enumerate_new</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
06255d6f76f3f630a9634d745a48910b1ea3e4d3David Herrmann <citerefentry><refentrytitle>udev_monitor_new_from_netlink</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
06255d6f76f3f630a9634d745a48910b1ea3e4d3David Herrmann <citerefentry><refentrytitle>udev_list_entry</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
06255d6f76f3f630a9634d745a48910b1ea3e4d3David Herrmann <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,