mirror of
https://github.com/systemd/systemd
synced 2024-09-16 06:43:18 +00:00
8c51e1520b
See #26688: getenv() is not thread-safe, and could a possible source of problems when a multi-threaded program calls setenv()/putenv()/unsetenv() in parallel. It is not possible to avoid getenv() calls in general, since $PATH, $LANG, $SHELL, $USER, $HOME, $TZ may need to be accessed at any time. Add a warning to our docs so that people are aware of the issue. Closes #26688. (Real fixes will need to be in glibc and gnome-shell or other programs.) The text is added to threads-aware.xml to be included in various places. By including it in libsystemd-pkgconfig.xml, it is automatically added to all sd-* pages. The text is also included explicitly in pages for a few other functions which are call getenv().
100 lines
4.4 KiB
XML
100 lines
4.4 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.2/docbookx.dtd" [
|
|
<!ENTITY % entities SYSTEM "custom-entities.ent" >
|
|
%entities;
|
|
]>
|
|
<!-- SPDX-License-Identifier: LGPL-2.1-or-later -->
|
|
|
|
<refentry id="libudev"
|
|
xmlns:xi="http://www.w3.org/2001/XInclude">
|
|
|
|
<refentryinfo>
|
|
<title>libudev</title>
|
|
<productname>systemd</productname>
|
|
</refentryinfo>
|
|
|
|
<refmeta>
|
|
<refentrytitle>libudev</refentrytitle>
|
|
<manvolnum>3</manvolnum>
|
|
</refmeta>
|
|
|
|
<refnamediv>
|
|
<refname>libudev</refname>
|
|
<refpurpose>API for enumerating and introspecting local devices</refpurpose>
|
|
</refnamediv>
|
|
|
|
<refsynopsisdiv>
|
|
<funcsynopsis>
|
|
<funcsynopsisinfo>#include <libudev.h></funcsynopsisinfo>
|
|
</funcsynopsis>
|
|
|
|
<cmdsynopsis>
|
|
<command>pkg-config --cflags --libs libudev</command>
|
|
</cmdsynopsis>
|
|
</refsynopsisdiv>
|
|
|
|
<refsect1>
|
|
<title>Description</title>
|
|
|
|
<para><filename>libudev.h</filename> provides an API to introspect and enumerate devices on the local
|
|
system. This library is supported, but should not be used in new projects. Please see
|
|
<citerefentry><refentrytitle>sd-device</refentrytitle><manvolnum>3</manvolnum></citerefentry> for an
|
|
equivalent replacement with a more modern API.</para>
|
|
|
|
<para>All functions require a libudev context to operate. This
|
|
context can be created via
|
|
<citerefentry><refentrytitle>udev_new</refentrytitle><manvolnum>3</manvolnum></citerefentry>.
|
|
It is used to track library state and link objects together. No
|
|
global state is used by libudev, everything is always linked to
|
|
a udev context.</para>
|
|
|
|
<xi:include href="threads-aware.xml" xpointer="strict"/>
|
|
<xi:include href="threads-aware.xml" xpointer="getenv"/>
|
|
|
|
<para>To introspect a local device on a system, a udev device
|
|
object can be created via
|
|
<citerefentry><refentrytitle>udev_device_new_from_syspath</refentrytitle><manvolnum>3</manvolnum></citerefentry>
|
|
and friends. The device object allows one to query current state,
|
|
read and write attributes and lookup properties of the device in
|
|
question.</para>
|
|
|
|
<para>To enumerate local devices on the system, an enumeration
|
|
object can be created via
|
|
<citerefentry><refentrytitle>udev_enumerate_new</refentrytitle><manvolnum>3</manvolnum></citerefentry>.</para>
|
|
|
|
<para>To monitor the local system for hotplugged or unplugged
|
|
devices, a monitor can be created via
|
|
<citerefentry><refentrytitle>udev_monitor_new_from_netlink</refentrytitle><manvolnum>3</manvolnum></citerefentry>.</para>
|
|
|
|
<para>Whenever libudev returns a list of objects, the
|
|
<citerefentry><refentrytitle>udev_list_entry</refentrytitle><manvolnum>3</manvolnum></citerefentry>
|
|
API should be used to iterate, access and modify those lists.</para>
|
|
|
|
<para>Furthermore, libudev also exports legacy APIs that should
|
|
not be used by new software (and as such are not documented as
|
|
part of this manual). This includes the hardware database known
|
|
as <constant>udev_hwdb</constant> (please use the new
|
|
<citerefentry><refentrytitle>sd-hwdb</refentrytitle><manvolnum>3</manvolnum></citerefentry>
|
|
API instead) and the <constant>udev_queue</constant> object to
|
|
query the udev daemon (which should not be used by new software
|
|
at all).</para>
|
|
</refsect1>
|
|
|
|
<refsect1>
|
|
<title>See Also</title>
|
|
<para>
|
|
<citerefentry><refentrytitle>udev_new</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
|
|
<citerefentry><refentrytitle>udev_device_new_from_syspath</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>,
|
|
<citerefentry><refentrytitle>sd-device</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
|
|
<citerefentry><refentrytitle>sd-hwdb</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
|
|
<citerefentry project='die-net'><refentrytitle>pkg-config</refentrytitle><manvolnum>1</manvolnum></citerefentry>
|
|
</para>
|
|
</refsect1>
|
|
|
|
</refentry>
|