Debian Codegraph @

upstream/debian-unstable/man3/sd_device_get_syspath.3

raw
1 '\" t
2 .TH "SD_DEVICE_GET_SYSPATH" "3" "" "systemd 261~rc3" "sd_device_get_syspath"
3 .\" -----------------------------------------------------------------
4 .\" * Define some portability stuff
5 .\" -----------------------------------------------------------------
6 .\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
7 .\" http://bugs.debian.org/507673
8 .\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html
9 .\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
10 .ie \n(.g .ds Aq \(aq
11 .el .ds Aq '
12 .\" -----------------------------------------------------------------
13 .\" * set default formatting
14 .\" -----------------------------------------------------------------
15 .\" disable hyphenation
16 .nh
17 .\" disable justification (adjust text to left margin only)
18 .ad l
19 .\" -----------------------------------------------------------------
20 .\" * MAIN CONTENT STARTS HERE *
21 .\" -----------------------------------------------------------------
22 .SH "NAME"
23 sd_device_get_syspath, sd_device_get_devpath, sd_device_get_sysname, sd_device_get_sysnum, sd_device_get_subsystem, sd_device_get_driver_subsystem, sd_device_get_devtype, sd_device_get_devname, sd_device_get_devnum, sd_device_get_ifindex, sd_device_get_driver, sd_device_get_diskseq, sd_device_get_device_id \- Returns various fields of device objects
24 .SH "SYNOPSIS"
25 .sp
26 .ft B
27 .nf
28 #include <systemd/sd\-device\&.h>
29 .fi
30 .ft
31 .HP \w'int\ sd_device_get_syspath('u
32 .BI "int sd_device_get_syspath(sd_device\ *" "device" ", const\ char\ **" "ret" ");"
33 .HP \w'int\ sd_device_get_devpath('u
34 .BI "int sd_device_get_devpath(sd_device\ *" "device" ", const\ char\ **" "ret" ");"
35 .HP \w'int\ sd_device_get_sysname('u
36 .BI "int sd_device_get_sysname(sd_device\ *" "device" ", const\ char\ **" "ret" ");"
37 .HP \w'int\ sd_device_get_sysnum('u
38 .BI "int sd_device_get_sysnum(sd_device\ *" "device" ", const\ char\ **" "ret" ");"
39 .HP \w'int\ sd_device_get_subsystem('u
40 .BI "int sd_device_get_subsystem(sd_device\ *" "device" ", const\ char\ **" "ret" ");"
41 .HP \w'int\ sd_device_get_driver_subsystem('u
42 .BI "int sd_device_get_driver_subsystem(sd_device\ *" "device" ", const\ char\ **" "ret" ");"
43 .HP \w'int\ sd_device_get_devtype('u
44 .BI "int sd_device_get_devtype(sd_device\ *" "device" ", const\ char\ **" "ret" ");"
45 .HP \w'int\ sd_device_get_devname('u
46 .BI "int sd_device_get_devname(sd_device\ *" "device" ", const\ char\ **" "ret" ");"
47 .HP \w'int\ sd_device_get_devnum('u
48 .BI "int sd_device_get_devnum(sd_device\ *" "device" ", dev_t\ *" "ret" ");"
49 .HP \w'int\ sd_device_get_ifindex('u
50 .BI "int sd_device_get_ifindex(sd_device\ *" "device" ", int\ *" "ret" ");"
51 .HP \w'int\ sd_device_get_driver('u
52 .BI "int sd_device_get_driver(sd_device\ *" "device" ", const\ char\ **" "ret" ");"
53 .HP \w'int\ sd_device_get_diskseq('u
54 .BI "int sd_device_get_diskseq(sd_device\ *" "device" ", uint64_t\ *" "ret" ");"
55 .HP \w'int\ sd_device_get_device_id('u
56 .BI "int sd_device_get_device_id(sd_device\ *" "device" ", const\ char\ **" "ret" ");"
57 .SH "DESCRIPTION"
58 .PP
59 \fBsd_device_get_syspath()\fR
60 returns the sysfs path of the specified device record, including the
61 /sys
62 prefix\&. Example:
63 /sys/devices/virtual/tty/tty7
64 .PP
65 \fBsd_device_get_devpath()\fR
66 returns the sysfs path of the specified device record, excluding the
67 /sys
68 prefix\&. Example:
69 /devices/virtual/tty/tty7
70 .PP
71 \fBsd_device_get_sysname()\fR
72 returns the sysfs name of the specified device record, i\&.e\&. the last component of the sysfs path\&. Example:
73 "tty7"
74 for the device
75 /sys/devices/virtual/tty/tty7
76 .PP
77 \fBsd_device_get_sysnum()\fR
78 returns the sysfs device number of the specified device record, i\&.e\&. the numeric suffix of the last component of the sysfs path\&. Example:
79 "7"
80 for the device
81 /sys/devices/virtual/tty/tty7
82 .PP
83 \fBsd_device_get_subsystem()\fR
84 returns the kernel subsystem of the specified device record\&. This is a short string fitting into a filename, and thus does not contain a slash and cannot be empty\&. Example:
85 "tty",
86 "block"
87 or
88 "net"\&.
89 .PP
90 \fBsd_device_get_driver_subsystem()\fR
91 returns the connected bus type of the devices loaded by the specified driver device record\&. For example, when
92 "iwlwifi"
93 driver device is specified, which is used by the wireless network interfaces connected to PCI bus, this function returns
94 "pci"\&. This function only succeeds when
95 \fBsd_device_get_subsystem()\fR
96 returns
97 "drivers"\&. Example:
98 "pci",
99 "i2c", or
100 "hid"\&.
101 .PP
102 \fBsd_device_get_devtype()\fR
103 returns the device type of the specified device record, if the subsystem manages multiple types of devices\&. Example: for devices of the
104 "block"
105 subsystem this can be
106 "disk"
107 or
108 "partition"
109 .PP
110 \fBsd_device_get_devname()\fR
111 returns the device node path of the specified device record if the device has a device node\&. Example: for
112 /sys/devices/virtual/tty/tty7
113 the string
114 /dev/tty7
115 is typically returned\&.
116 .PP
117 \fBsd_device_get_devnum()\fR
118 returns the device node major/minor (i\&.e\&.
119 \fBdev_t\fR) of the specified device record if the device has a device node (i\&.e\&. the one returned by
120 \fBsd_device_get_devname()\fR)\&. For devices belonging to the
121 "block"
122 subsystem this refers to a block device node, in all other cases to a character device node\&. Example: for the
123 /sys/devices/virtual/tty/tty7
124 device this typically returns the device number with major/minor
125 "4:7"\&.
126 .PP
127 \fBsd_device_get_ifindex()\fR
128 returns the network interface index of the specified device record, if the device encapsulates a network interface device, i\&.e\&. belongs to the
129 "net"
130 subsystem\&. Example: the
131 "lo"
132 interface typically has interface index 1\&.
133 .PP
134 \fBsd_device_get_driver()\fR
135 returns the kernel driver name attached to the device\&. Note that the driver field is set on the devices consumed by the driver, not on the device created by it\&. Example: a PCI device
136 /sys/bus/pci/devices/0000:00:1f\&.6
137 might be attached to a driver
138 "e1000e"\&.
139 .PP
140 \fBsd_device_get_diskseq()\fR
141 returns the kernel disk sequence number of the block device\&. This number monotonically increases whenever a backing medium of a block device changes without the device name changing, and is relevant for block devices encapsulating devices with changing media (e\&.g\&. floppy or CD\-ROM), or loopback block devices\&. Only defined for block devices, i\&.e\&. those of subsystem
142 "block"\&.
143 .PP
144 \fBsd_device_get_device_id()\fR
145 returns the short string that identifies the device record\&. When the device ID obtained by the function for a specified device record is passed to
146 \fBsd_device_new_from_device_id()\fR, a new instance of the same device record will be gained\&. When a block or character device is specified, which has corresponding device node, this returns
147 "b"
148 or
149 "c", respectively, followed by the device node major and minor numbers separated with a colon\&. Example:
150 "b259:1"
151 or
152 "c10:121"\&. When a network interface device is specified, this returns
153 "n"
154 followed by the interface index, which can be obtained by
155 \fBsd_device_get_ifindex()\fR\&. Example:
156 "n1"\&. When a device in the
157 "driver"
158 subsystem is specified, this returns
159 "+drivers:"
160 followed by its driver subsystem and sysfs name separated with a colon\&. Example:
161 "+drivers:pci:iwlwifi"
162 for a driver device record whose driver subsystem is
163 "pci"
164 and sysfs name is
165 "iwlwifi", When another type of device is specified, this function returns
166 "+"
167 followed by its subsystem and sysfs name separated with a colon\&. Example:
168 "+acpi:ACPI0003:00",
169 "+input:input16", or
170 "+pci:0000:00:1f\&.6"\&.
171 .SH "RETURN VALUE"
172 .PP
173 On success, these calls return 0 or a positive integer\&. On failure, they return a negative errno\-style error code\&.
174 .SS "Errors"
175 .PP
176 Returned errors may indicate the following problems:
177 .PP
178 \fB\-EINVAL\fR
179 .RS 4
180 A specified parameter is invalid\&.
181 .sp
182 Added in version 251\&.
183 .RE
184 .PP
185 \fB\-ENOENT\fR
186 .RS 4
187 The requested field is not present in the device record\&.
188 .sp
189 Added in version 251\&.
190 .RE
191 .SH "NOTES"
192 .PP
193 Functions described here are available as a shared library, which can be compiled against and linked to with the
194 \fBlibsystemd\fR\ \&\fBpkg-config\fR(1)
195 file\&.
196 .PP
197 The code described here uses
198 \fBgetenv\fR(3), which is declared to be not multi\-thread\-safe\&. This means that the code calling the functions described here must not call
199 \fBsetenv\fR(3)
200 from a parallel thread\&. It is recommended to only do calls to
201 \fBsetenv()\fR
202 from an early phase of the program when no other threads have been started\&.
203 .SH "HISTORY"
204 .PP
205 \fBsd_device_get_syspath()\fR,
206 \fBsd_device_get_devpath()\fR,
207 \fBsd_device_get_sysname()\fR,
208 \fBsd_device_get_sysnum()\fR,
209 \fBsd_device_get_subsystem()\fR,
210 \fBsd_device_get_devtype()\fR,
211 \fBsd_device_get_devname()\fR,
212 \fBsd_device_get_devnum()\fR,
213 \fBsd_device_get_ifindex()\fR,
214 \fBsd_device_get_driver()\fR, and
215 \fBsd_device_get_diskseq()\fR
216 were added in version 251\&.
217 .PP
218 \fBsd_device_get_driver_subsystem()\fR
219 and
220 \fBsd_device_get_device_id()\fR
221 were added in version 257\&.
222 .SH "SEE ALSO"
223 .PP
224 \fBsystemd\fR(1), \fBsd-device\fR(3)