1<?xml version='1.0'?> <!--*-nxml-*-->
2<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
3  "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd" [
4<!ENTITY % entities SYSTEM "custom-entities.ent" >
5%entities;
6]>
7<!-- SPDX-License-Identifier: LGPL-2.1-or-later -->
8
9<refentry id="libudev"
10  xmlns:xi="http://www.w3.org/2001/XInclude">
11
12  <refentryinfo>
13    <title>libudev</title>
14    <productname>systemd</productname>
15  </refentryinfo>
16
17  <refmeta>
18    <refentrytitle>libudev</refentrytitle>
19    <manvolnum>3</manvolnum>
20  </refmeta>
21
22  <refnamediv>
23    <refname>libudev</refname>
24    <refpurpose>API for enumerating and introspecting local devices</refpurpose>
25  </refnamediv>
26
27  <refsynopsisdiv>
28    <funcsynopsis>
29      <funcsynopsisinfo>#include &lt;libudev.h&gt;</funcsynopsisinfo>
30    </funcsynopsis>
31
32    <cmdsynopsis>
33      <command>pkg-config --cflags --libs libudev</command>
34    </cmdsynopsis>
35  </refsynopsisdiv>
36
37  <refsect1>
38    <title>Description</title>
39
40    <para><filename>libudev.h</filename> provides an API to introspect and enumerate devices on the local
41    system. This library is supported, but should not be used in new projects. Please see
42    <citerefentry><refentrytitle>sd-device</refentrytitle><manvolnum>3</manvolnum></citerefentry> for an
43    equivalent replacement with a more modern API.</para>
44
45    <para>All functions require a libudev context to operate. This
46    context can be create via
47    <citerefentry><refentrytitle>udev_new</refentrytitle><manvolnum>3</manvolnum></citerefentry>.
48    It is used to track library state and link objects together. No
49    global state is used by libudev, everything is always linked to
50    a udev context.</para>
51
52    <xi:include href="threads-aware.xml" xpointer="strict"/>
53
54    <para>To introspect a local device on a system, a udev device
55    object can be created via
56    <citerefentry><refentrytitle>udev_device_new_from_syspath</refentrytitle><manvolnum>3</manvolnum></citerefentry>
57    and friends. The device object allows one to query current state,
58    read and write attributes and lookup properties of the device in
59    question.</para>
60
61    <para>To enumerate local devices on the system, an enumeration
62    object can be created via
63    <citerefentry><refentrytitle>udev_enumerate_new</refentrytitle><manvolnum>3</manvolnum></citerefentry>.</para>
64
65    <para>To monitor the local system for hotplugged or unplugged
66    devices, a monitor can be created via
67    <citerefentry><refentrytitle>udev_monitor_new_from_netlink</refentrytitle><manvolnum>3</manvolnum></citerefentry>.</para>
68
69    <para>Whenever libudev returns a list of objects, the
70    <citerefentry><refentrytitle>udev_list_entry</refentrytitle><manvolnum>3</manvolnum></citerefentry>
71    API should be used to iterate, access and modify those lists.</para>
72
73    <para>Furthermore, libudev also exports legacy APIs that should
74    not be used by new software (and as such are not documented as
75    part of this manual). This includes the hardware database known
76    as <constant>udev_hwdb</constant> (please use the new
77    <citerefentry><refentrytitle>sd-hwdb</refentrytitle><manvolnum>3</manvolnum></citerefentry>
78    API instead) and the <constant>udev_queue</constant> object to
79    query the udev daemon (which should not be used by new software
80    at all).</para>
81  </refsect1>
82
83  <refsect1>
84    <title>See Also</title>
85    <para>
86      <citerefentry><refentrytitle>udev_new</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
87      <citerefentry><refentrytitle>udev_device_new_from_syspath</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
88      <citerefentry><refentrytitle>udev_enumerate_new</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
89      <citerefentry><refentrytitle>udev_monitor_new_from_netlink</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
90      <citerefentry><refentrytitle>udev_list_entry</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
91      <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
92      <citerefentry><refentrytitle>sd-device</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
93      <citerefentry><refentrytitle>sd-hwdb</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
94      <citerefentry project='die-net'><refentrytitle>pkg-config</refentrytitle><manvolnum>1</manvolnum></citerefentry>
95    </para>
96  </refsect1>
97
98</refentry>
99