man/sd_device_get_syspath.xml

   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.5/docbookx.dtd">
   4 <!-- SPDX-License-Identifier: LGPL-2.1-or-later -->
   5
   6 <refentry id="sd_device_get_syspath"
   7           xmlns:xi="http://www.w3.org/2001/XInclude">
   8
   9   <refentryinfo>
  10     <title>sd_device_get_syspath</title>
  11     <productname>systemd</productname>
  12   </refentryinfo>
  13
  14   <refmeta>
  15     <refentrytitle>sd_device_get_syspath</refentrytitle>
  16     <manvolnum>3</manvolnum>
  17   </refmeta>
  18
  19   <refnamediv>
  20     <refname>sd_device_get_syspath</refname>
  21     <refname>sd_device_get_devpath</refname>
  22     <refname>sd_device_get_sysname</refname>
  23     <refname>sd_device_get_sysnum</refname>
  24     <refname>sd_device_get_subsystem</refname>
  25     <refname>sd_device_get_driver_subsystem</refname>
  26     <refname>sd_device_get_devtype</refname>
  27     <refname>sd_device_get_devname</refname>
  28     <refname>sd_device_get_devnum</refname>
  29     <refname>sd_device_get_ifindex</refname>
  30     <refname>sd_device_get_driver</refname>
  31     <refname>sd_device_get_diskseq</refname>
  32     <refname>sd_device_get_device_id</refname>
  33
  34     <refpurpose>Returns various fields of device objects</refpurpose>
  35   </refnamediv>
  36
  37   <refsynopsisdiv>
  38     <funcsynopsis>
  39       <funcsynopsisinfo>#include &lt;systemd/sd-device.h&gt;</funcsynopsisinfo>
  40
  41       <funcprototype>
  42         <funcdef>int <function>sd_device_get_syspath</function></funcdef>
  43         <paramdef>sd_device *<parameter>device</parameter></paramdef>
  44         <paramdef>const char **<parameter>ret</parameter></paramdef>
  45       </funcprototype>
  46
  47       <funcprototype>
  48         <funcdef>int <function>sd_device_get_devpath</function></funcdef>
  49         <paramdef>sd_device *<parameter>device</parameter></paramdef>
  50         <paramdef>const char **<parameter>ret</parameter></paramdef>
  51       </funcprototype>
  52
  53       <funcprototype>
  54         <funcdef>int <function>sd_device_get_sysname</function></funcdef>
  55         <paramdef>sd_device *<parameter>device</parameter></paramdef>
  56         <paramdef>const char **<parameter>ret</parameter></paramdef>
  57       </funcprototype>
  58
  59       <funcprototype>
  60         <funcdef>int <function>sd_device_get_sysnum</function></funcdef>
  61         <paramdef>sd_device *<parameter>device</parameter></paramdef>
  62         <paramdef>const char **<parameter>ret</parameter></paramdef>
  63       </funcprototype>
  64
  65       <funcprototype>
  66         <funcdef>int <function>sd_device_get_subsystem</function></funcdef>
  67         <paramdef>sd_device *<parameter>device</parameter></paramdef>
  68         <paramdef>const char **<parameter>ret</parameter></paramdef>
  69       </funcprototype>
  70
  71       <funcprototype>
  72         <funcdef>int <function>sd_device_get_driver_subsystem</function></funcdef>
  73         <paramdef>sd_device *<parameter>device</parameter></paramdef>
  74         <paramdef>const char **<parameter>ret</parameter></paramdef>
  75       </funcprototype>
  76
  77       <funcprototype>
  78         <funcdef>int <function>sd_device_get_devtype</function></funcdef>
  79         <paramdef>sd_device *<parameter>device</parameter></paramdef>
  80         <paramdef>const char **<parameter>ret</parameter></paramdef>
  81       </funcprototype>
  82
  83       <funcprototype>
  84         <funcdef>int <function>sd_device_get_devname</function></funcdef>
  85         <paramdef>sd_device *<parameter>device</parameter></paramdef>
  86         <paramdef>const char **<parameter>ret</parameter></paramdef>
  87       </funcprototype>
  88
  89       <funcprototype>
  90         <funcdef>int <function>sd_device_get_devnum</function></funcdef>
  91         <paramdef>sd_device *<parameter>device</parameter></paramdef>
  92         <paramdef>dev_t *<parameter>ret</parameter></paramdef>
  93       </funcprototype>
  94
  95       <funcprototype>
  96         <funcdef>int <function>sd_device_get_ifindex</function></funcdef>
  97         <paramdef>sd_device *<parameter>device</parameter></paramdef>
  98         <paramdef>int *<parameter>ret</parameter></paramdef>
  99       </funcprototype>
 100
 101       <funcprototype>
 102         <funcdef>int <function>sd_device_get_driver</function></funcdef>
 103         <paramdef>sd_device *<parameter>device</parameter></paramdef>
 104         <paramdef>const char **<parameter>ret</parameter></paramdef>
 105       </funcprototype>
 106
 107       <funcprototype>
 108         <funcdef>int <function>sd_device_get_diskseq</function></funcdef>
 109         <paramdef>sd_device *<parameter>device</parameter></paramdef>
 110         <paramdef>uint64_t *<parameter>ret</parameter></paramdef>
 111       </funcprototype>
 112
 113       <funcprototype>
 114         <funcdef>int <function>sd_device_get_device_id</function></funcdef>
 115         <paramdef>sd_device *<parameter>device</parameter></paramdef>
 116         <paramdef>const char **<parameter>ret</parameter></paramdef>
 117       </funcprototype>
 118
 119     </funcsynopsis>
 120   </refsynopsisdiv>
 121
 122   <refsect1>
 123     <title>Description</title>
 124
 125     <para><function>sd_device_get_syspath()</function> returns the sysfs path of the specified device record,
 126     including the <filename>/sys</filename> prefix. Example: <filename>/sys/devices/virtual/tty/tty7</filename></para>
 127
 128     <para><function>sd_device_get_devpath()</function> returns the sysfs path of the specified device record,
 129     excluding the <filename>/sys</filename> prefix. Example: <filename>/devices/virtual/tty/tty7</filename></para>
 130
 131     <para><function>sd_device_get_sysname()</function> returns the sysfs name of the specified device record,
 132     i.e. the last component of the sysfs path. Example: <literal>tty7</literal> for the device
 133     <filename>/sys/devices/virtual/tty/tty7</filename></para>
 134
 135     <para><function>sd_device_get_sysnum()</function> returns the sysfs device number of the specified device
 136     record, i.e. the numeric suffix of the last component of the sysfs path. Example: <literal>7</literal>
 137     for the device <filename>/sys/devices/virtual/tty/tty7</filename></para>
 138
 139     <para><function>sd_device_get_subsystem()</function> returns the kernel subsystem of the specified device
 140     record. This is a short string fitting into a filename, and thus does not contain a slash and cannot be
 141     empty. Example: <literal>tty</literal>, <literal>block</literal> or <literal>net</literal>.</para>
 142
 143     <para><function>sd_device_get_driver_subsystem()</function> returns the connected bus type of the devices
 144     loaded by the specified driver device record. For example, when <literal>iwlwifi</literal> driver device
 145     is specified, which is used by the wireless network interfaces connected to PCI bus, this function returns
 146     <literal>pci</literal>. This function only succeeds when <function>sd_device_get_subsystem()</function>
 147     returns <literal>drivers</literal>. Example: <literal>pci</literal>, <literal>i2c</literal>, or
 148     <literal>hid</literal>.</para>
 149
 150     <para><function>sd_device_get_devtype()</function> returns the device type of the specified device
 151     record, if the subsystem manages multiple types of devices. Example: for devices of the
 152     <literal>block</literal> subsystem this can be <literal>disk</literal> or <literal>partition</literal>
 153     </para>
 154
 155     <para><function>sd_device_get_devname()</function> returns the device node path of the specified device
 156     record if the device has a device node. Example: for <filename>/sys/devices/virtual/tty/tty7</filename>
 157     the string <filename>/dev/tty7</filename> is typically returned.</para>
 158
 159     <para><function>sd_device_get_devnum()</function> returns the device node major/minor
 160     (i.e. <type>dev_t</type>) of the specified device record if the device has a device node (i.e. the one
 161     returned by <function>sd_device_get_devname()</function>). For devices belonging to the
 162     <literal>block</literal> subsystem this refers to a block device node, in all other cases to a character
 163     device node. Example: for the <filename>/sys/devices/virtual/tty/tty7</filename> device this typically
 164     returns the device number with major/minor <literal>4:7</literal>.</para>
 165
 166     <para><function>sd_device_get_ifindex()</function> returns the network interface index of the specified
 167     device record, if the device encapsulates a network interface device, i.e. belongs to the
 168     <literal>net</literal> subsystem. Example: the <literal>lo</literal> interface typically has interface
 169     index 1.</para>
 170
 171     <para><function>sd_device_get_driver()</function> returns the kernel driver name attached to the
 172     device. Note that the driver field is set on the devices consumed by the driver, not on the device
 173     created by it. Example: a PCI device <filename>/sys/bus/pci/devices/0000:00:1f.6</filename> might be
 174     attached to a driver <literal>e1000e</literal>.</para>
 175
 176     <para><function>sd_device_get_diskseq()</function> returns the kernel disk sequence number of the block
 177     device. This number monotonically increases whenever a backing medium of a block device changes without
 178     the device name changing, and is relevant for block devices encapsulating devices with changing media
 179     (e.g. floppy or CD-ROM), or loopback block devices. Only defined for block devices, i.e. those of
 180     subsystem <literal>block</literal>.</para>
 181
 182     <para><function>sd_device_get_device_id()</function> returns the short string that identifies the device
 183     record. When the device ID obtained by the function for a specified device record is passed to
 184     <function>sd_device_new_from_device_id()</function>, a new instance of the same device record will be
 185     gained. When a block or character device is specified, which has corresponding device node, this returns
 186     <literal>b</literal> or <literal>c</literal>, respectively, followed by the device node major and minor
 187     numbers separated with a colon. Example: <literal>b259:1</literal> or <literal>c10:121</literal>. When a
 188     network interface device is specified, this returns <literal>n</literal> followed by the interface index,
 189     which can be obtained by <function>sd_device_get_ifindex()</function>. Example: <literal>n1</literal>.
 190     When a device in the <literal>driver</literal> subsystem is specified, this returns
 191     <literal>+drivers:</literal> followed by its driver subsystem and sysfs name separated with a colon.
 192     Example: <literal>+drivers:pci:iwlwifi</literal> for a driver device record whose driver subsystem is
 193     <literal>pci</literal> and sysfs name is <literal>iwlwifi</literal>,
 194     When another type of device is specified, this function returns <literal>+</literal> followed by its
 195     subsystem and sysfs name separated with a colon. Example: <literal>+acpi:ACPI0003:00</literal>,
 196     <literal>+input:input16</literal>, or <literal>+pci:0000:00:1f.6</literal>.</para>
 197   </refsect1>
 198
 199   <refsect1>
 200     <title>Return Value</title>
 201
 202     <para>On success, these calls return 0 or a positive integer. On failure, they return a negative
 203     errno-style error code.</para>
 204
 205     <refsect2>
 206       <title>Errors</title>
 207
 208       <para>Returned errors may indicate the following problems:</para>
 209
 210       <variablelist>
 211         <varlistentry>
 212           <term><constant>-EINVAL</constant></term>
 213
 214           <listitem><para>A specified parameter is invalid.</para>
 215
 216           <xi:include href="version-info.xml" xpointer="v251"/></listitem>
 217         </varlistentry>
 218
 219         <varlistentry>
 220           <term><constant>-ENOENT</constant></term>
 221
 222           <listitem><para>The requested field is not present in the device record.</para>
 223
 224           <xi:include href="version-info.xml" xpointer="v251"/></listitem>
 225         </varlistentry>
 226
 227       </variablelist>
 228     </refsect2>
 229   </refsect1>
 230
 231   <xi:include href="libsystemd-pkgconfig.xml" />
 232
 233   <refsect1>
 234     <title>History</title>
 235     <para><function>sd_device_get_syspath()</function>,
 236     <function>sd_device_get_devpath()</function>,
 237     <function>sd_device_get_sysname()</function>,
 238     <function>sd_device_get_sysnum()</function>,
 239     <function>sd_device_get_subsystem()</function>,
 240     <function>sd_device_get_devtype()</function>,
 241     <function>sd_device_get_devname()</function>,
 242     <function>sd_device_get_devnum()</function>,
 243     <function>sd_device_get_ifindex()</function>,
 244     <function>sd_device_get_driver()</function>, and
 245     <function>sd_device_get_diskseq()</function> were added in version 251.</para>
 246     <para><function>sd_device_get_driver_subsystem()</function> and
 247     <function>sd_device_get_device_id()</function> were added in version 257.</para>
 248   </refsect1>
 249
 250   <refsect1>
 251     <title>See Also</title>
 252
 253     <para><simplelist type="inline">
 254       <member><citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry></member>
 255       <member><citerefentry><refentrytitle>sd-device</refentrytitle><manvolnum>3</manvolnum></citerefentry></member>
 256     </simplelist></para>
 257   </refsect1>
 258
 259 </refentry>