]>
Commit | Line | Data |
---|---|---|
b51f4eaf LP |
1 | <?xml version='1.0'?> <!--*-nxml-*--> |
2 | <!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" | |
eea10b26 | 3 | "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd"> |
b51f4eaf LP |
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_devtype</refname> | |
26 | <refname>sd_device_get_devname</refname> | |
27 | <refname>sd_device_get_devnum</refname> | |
28 | <refname>sd_device_get_ifindex</refname> | |
29 | <refname>sd_device_get_driver</refname> | |
30 | <refname>sd_device_get_diskseq</refname> | |
31 | ||
32 | <refpurpose>Returns various fields of device objects</refpurpose> | |
33 | </refnamediv> | |
34 | ||
35 | <refsynopsisdiv> | |
36 | <funcsynopsis> | |
37 | <funcsynopsisinfo>#include <systemd/sd-device.h></funcsynopsisinfo> | |
38 | ||
39 | <funcprototype> | |
40 | <funcdef>int <function>sd_device_get_syspath</function></funcdef> | |
41 | <paramdef>sd_device *<parameter>device</parameter></paramdef> | |
42 | <paramdef>const char **<parameter>ret</parameter></paramdef> | |
43 | </funcprototype> | |
44 | ||
45 | <funcprototype> | |
46 | <funcdef>int <function>sd_device_get_devpath</function></funcdef> | |
47 | <paramdef>sd_device *<parameter>device</parameter></paramdef> | |
48 | <paramdef>const char **<parameter>ret</parameter></paramdef> | |
49 | </funcprototype> | |
50 | ||
51 | <funcprototype> | |
52 | <funcdef>int <function>sd_device_get_sysname</function></funcdef> | |
53 | <paramdef>sd_device *<parameter>device</parameter></paramdef> | |
54 | <paramdef>const char **<parameter>ret</parameter></paramdef> | |
55 | </funcprototype> | |
56 | ||
57 | <funcprototype> | |
58 | <funcdef>int <function>sd_device_get_sysnum</function></funcdef> | |
59 | <paramdef>sd_device *<parameter>device</parameter></paramdef> | |
60 | <paramdef>const char **<parameter>ret</parameter></paramdef> | |
61 | </funcprototype> | |
62 | ||
63 | <funcprototype> | |
64 | <funcdef>int <function>sd_device_get_subsystem</function></funcdef> | |
65 | <paramdef>sd_device *<parameter>device</parameter></paramdef> | |
66 | <paramdef>const char **<parameter>ret</parameter></paramdef> | |
67 | </funcprototype> | |
68 | ||
69 | <funcprototype> | |
70 | <funcdef>int <function>sd_device_get_devtype</function></funcdef> | |
71 | <paramdef>sd_device *<parameter>device</parameter></paramdef> | |
72 | <paramdef>const char **<parameter>ret</parameter></paramdef> | |
73 | </funcprototype> | |
74 | ||
75 | <funcprototype> | |
76 | <funcdef>int <function>sd_device_get_devname</function></funcdef> | |
77 | <paramdef>sd_device *<parameter>device</parameter></paramdef> | |
78 | <paramdef>const char **<parameter>ret</parameter></paramdef> | |
79 | </funcprototype> | |
80 | ||
81 | <funcprototype> | |
82 | <funcdef>int <function>sd_device_get_devnum</function></funcdef> | |
83 | <paramdef>sd_device *<parameter>device</parameter></paramdef> | |
84 | <paramdef>dev_t *<parameter>ret</parameter></paramdef> | |
85 | </funcprototype> | |
86 | ||
87 | <funcprototype> | |
88 | <funcdef>int <function>sd_device_get_ifindex</function></funcdef> | |
89 | <paramdef>sd_device *<parameter>device</parameter></paramdef> | |
90 | <paramdef>int *<parameter>ret</parameter></paramdef> | |
91 | </funcprototype> | |
92 | ||
93 | <funcprototype> | |
94 | <funcdef>int <function>sd_device_get_driver</function></funcdef> | |
95 | <paramdef>sd_device *<parameter>device</parameter></paramdef> | |
96 | <paramdef>const char **<parameter>ret</parameter></paramdef> | |
97 | </funcprototype> | |
98 | ||
99 | <funcprototype> | |
100 | <funcdef>int <function>sd_device_get_diskseq</function></funcdef> | |
101 | <paramdef>sd_device *<parameter>device</parameter></paramdef> | |
102 | <paramdef>uint64_t *<parameter>ret</parameter></paramdef> | |
103 | </funcprototype> | |
104 | ||
105 | </funcsynopsis> | |
106 | </refsynopsisdiv> | |
107 | ||
108 | <refsect1> | |
109 | <title>Description</title> | |
110 | ||
111 | <para><function>sd_device_get_syspath()</function> returns the sysfs path of the specified device record, | |
112 | including the <filename>/sys</filename> prefix. Example: <filename>/sys/devices/virtual/tty/tty7</filename></para> | |
113 | ||
114 | <para><function>sd_device_get_devpath()</function> returns the sysfs path of the specified device record, | |
115 | excluding the <filename>/sys</filename> prefix. Example: <filename>/devices/virtual/tty/tty7</filename></para> | |
116 | ||
117 | <para><function>sd_device_get_sysname()</function> returns the sysfs name of the specified device record, | |
118 | i.e. the last component of the sysfs path. Example: <literal>tty7</literal> for the device | |
119 | <filename>/sys/devices/virtual/tty/tty7</filename></para> | |
120 | ||
121 | <para><function>sd_device_get_sysnum()</function> returns the sysfs device number of the specified device | |
122 | record, i.e. the numeric suffix of the last component of the sysfs path. Example: <literal>7</literal> | |
123 | for the device <filename>/sys/devices/virtual/tty/tty7</filename></para> | |
124 | ||
125 | <para><function>sd_device_get_subsystem()</function> returns the kernel subsystem of the specified device | |
126 | record. This is a short string fitting into a filename, and thus does not contain a slash and cannot be | |
127 | empty. Example: <literal>tty</literal>, <literal>block</literal> or <literal>net</literal>.</para> | |
128 | ||
129 | <para><function>sd_device_get_devtype()</function> returns the device type of the specified device | |
130 | record, if the subsystem manages multiple types of devices. Example: for devices of the | |
131 | <literal>block</literal> subsystem this can be <literal>disk</literal> or <literal>partition</literal> | |
132 | </para> | |
133 | ||
134 | <para><function>sd_device_get_devname()</function> returns the device node path of the specified device | |
135 | record if the device has a device node. Example: for <filename>/sys/devices/virtual/tty/tty7</filename> | |
136 | the string <filename>/dev/tty7</filename> is typically returned.</para> | |
137 | ||
138 | <para><function>sd_device_get_devnum()</function> returns the device node major/minor | |
139 | (i.e. <type>dev_t</type>) of the specified device record if the device has a device node (i.e. the one | |
140 | returned by <function>sd_device_get_devname()</function>). For devices belonging to the | |
141 | <literal>block</literal> subsystem this refers to a block device node, in all other cases to a character | |
142 | device node. Example: for the <filename>/sys/devices/virtual/tty/tty7</filename> device this typically | |
143 | returns the device number with major/minor <literal>4:7</literal>.</para> | |
144 | ||
145 | <para><function>sd_device_get_ifindex()</function> returns the network interface index of the specified | |
146 | device record, if the device encapsulates a network interface device, i.e. belongs to the | |
147 | <literal>net</literal> subsystem. Example: the <literal>lo</literal> interface typically has interface | |
148 | index 1.</para> | |
149 | ||
150 | <para><function>sd_device_get_driver()</function> returns the kernel driver name attached to the | |
151 | device. Note that the driver field is set on the devices consumed by the driver, not on the device | |
152 | created by it. Example: a PCI device <filename>/sys/bus/pci/devices/0000:00:1f.6</filename> might be | |
153 | attached to a driver <literal>e1000e</literal>.</para> | |
154 | ||
155 | <para><function>sd_device_get_diskseq()</function> returns the kernel disk sequence number of the block | |
156 | device. This number monotonically increases whenever a backing medium of a block device changes without | |
157 | the device name changing, and is relevant for block devices encapsulating devices with changing media | |
158 | (e.g. floppy or CD-ROM), or loopback block devices. Only defined for block devices, i.e. those of | |
159 | subsystem <literal>block</literal>.</para> | |
160 | </refsect1> | |
161 | ||
162 | <refsect1> | |
163 | <title>Return Value</title> | |
164 | ||
165 | <para>On success, these calls return 0 or a positive integer. On failure, they return a negative | |
166 | errno-style error code.</para> | |
167 | ||
168 | <refsect2> | |
169 | <title>Errors</title> | |
170 | ||
171 | <para>Returned errors may indicate the following problems:</para> | |
172 | ||
173 | <variablelist> | |
174 | <varlistentry> | |
175 | <term><constant>-EINVAL</constant></term> | |
176 | ||
ec07c3c8 AK |
177 | <listitem><para>A specified parameter is invalid.</para> |
178 | ||
179 | <xi:include href="version-info.xml" xpointer="v251"/></listitem> | |
b51f4eaf LP |
180 | </varlistentry> |
181 | ||
182 | <varlistentry> | |
183 | <term><constant>-ENOENT</constant></term> | |
184 | ||
ec07c3c8 AK |
185 | <listitem><para>The requested field is not present in the device record.</para> |
186 | ||
187 | <xi:include href="version-info.xml" xpointer="v251"/></listitem> | |
b51f4eaf LP |
188 | </varlistentry> |
189 | ||
190 | </variablelist> | |
191 | </refsect2> | |
192 | </refsect1> | |
193 | ||
194 | <xi:include href="libsystemd-pkgconfig.xml" /> | |
195 | ||
69106f47 AK |
196 | <refsect1> |
197 | <title>History</title> | |
00f95506 AK |
198 | <para><function>sd_device_get_syspath()</function>, |
199 | <function>sd_device_get_devpath()</function>, | |
200 | <function>sd_device_get_sysname()</function>, | |
201 | <function>sd_device_get_sysnum()</function>, | |
202 | <function>sd_device_get_subsystem()</function>, | |
203 | <function>sd_device_get_devtype()</function>, | |
204 | <function>sd_device_get_devname()</function>, | |
205 | <function>sd_device_get_devnum()</function>, | |
206 | <function>sd_device_get_ifindex()</function>, | |
207 | <function>sd_device_get_driver()</function>, and | |
208 | <function>sd_device_get_diskseq()</function> were added in version 251.</para> | |
69106f47 AK |
209 | </refsect1> |
210 | ||
b51f4eaf LP |
211 | <refsect1> |
212 | <title>See Also</title> | |
213 | ||
214 | <para> | |
215 | <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry> | |
216 | </para> | |
217 | </refsect1> | |
218 | ||
219 | </refentry> |