Commit | Line | Data |
---|---|---|
f77af637 | 1 | .. _admin_devices: |
1da177e4 | 2 | |
d9f92f9f MCC |
3 | Linux allocated devices (4.x+ version) |
4 | ====================================== | |
1da177e4 LT |
5 | |
6 | This list is the Linux Device List, the official registry of allocated | |
d9f92f9f | 7 | device numbers and ``/dev`` directory nodes for the Linux operating |
1da177e4 LT |
8 | system. |
9 | ||
ebdf4040 LW |
10 | The LaTeX version of this document is no longer maintained, nor is |
11 | the document that used to reside at lanana.org. This version in the | |
12 | mainline Linux kernel is the master document. Updates shall be sent | |
d9f92f9f | 13 | as patches to the kernel maintainers (see the |
8c27ceff | 14 | :ref:`Documentation/process/submitting-patches.rst <submittingpatches>` document). |
ebdf4040 LW |
15 | Specifically explore the sections titled "CHAR and MISC DRIVERS", and |
16 | "BLOCK LAYER" in the MAINTAINERS file to find the right maintainers | |
17 | to involve for character and block devices. | |
1da177e4 LT |
18 | |
19 | This document is included by reference into the Filesystem Hierarchy | |
93431e06 | 20 | Standard (FHS). The FHS is available from https://www.pathname.com/fhs/. |
1da177e4 LT |
21 | |
22 | Allocations marked (68k/Amiga) apply to Linux/68k on the Amiga | |
23 | platform only. Allocations marked (68k/Atari) apply to Linux/68k on | |
24 | the Atari platform only. | |
25 | ||
ebdf4040 | 26 | This document is in the public domain. The authors requests, however, |
1da177e4 | 27 | that semantically altered versions are not distributed without |
ebdf4040 | 28 | permission of the authors, assuming the authors can be contacted without |
1da177e4 LT |
29 | an unreasonable effort. |
30 | ||
1da177e4 | 31 | |
d9f92f9f | 32 | .. attention:: |
1da177e4 | 33 | |
d9f92f9f | 34 | DEVICE DRIVERS AUTHORS PLEASE READ THIS |
1da177e4 | 35 | |
d9f92f9f MCC |
36 | Linux now has extensive support for dynamic allocation of device numbering |
37 | and can use ``sysfs`` and ``udev`` (``systemd``) to handle the naming needs. | |
38 | There are still some exceptions in the serial and boot device area. Before | |
39 | asking for a device number make sure you actually need one. | |
1da177e4 | 40 | |
d9f92f9f MCC |
41 | To have a major number allocated, or a minor number in situations |
42 | where that applies (e.g. busmice), please submit a patch and send to | |
43 | the authors as indicated above. | |
04c860c1 | 44 | |
d9f92f9f MCC |
45 | Keep the description of the device *in the same format |
46 | as this list*. The reason for this is that it is the only way we have | |
47 | found to ensure we have all the requisite information to publish your | |
48 | device and avoid conflicts. | |
1da177e4 | 49 | |
d9f92f9f MCC |
50 | Finally, sometimes we have to play "namespace police." Please don't be |
51 | offended. We often get submissions for ``/dev`` names that would be bound | |
52 | to cause conflicts down the road. We are trying to avoid getting in a | |
53 | situation where we would have to suffer an incompatible forward | |
54 | change. Therefore, please consult with us **before** you make your | |
55 | device names and numbers in any way public, at least to the point | |
56 | where it would be at all difficult to get them changed. | |
1da177e4 | 57 | |
d9f92f9f | 58 | Your cooperation is appreciated. |
1da177e4 | 59 | |
07c7e30c JN |
60 | .. include:: devices.txt |
61 | :literal: | |
d9f92f9f MCC |
62 | |
63 | Additional ``/dev/`` directory entries | |
64 | -------------------------------------- | |
1da177e4 LT |
65 | |
66 | This section details additional entries that should or may exist in | |
67 | the /dev directory. It is preferred that symbolic links use the same | |
68 | form (absolute or relative) as is indicated here. Links are | |
69 | classified as "hard" or "symbolic" depending on the preferred type of | |
70 | link; if possible, the indicated type of link should be used. | |
71 | ||
d9f92f9f MCC |
72 | Compulsory links |
73 | ++++++++++++++++ | |
1da177e4 LT |
74 | |
75 | These links should exist on all systems: | |
76 | ||
d9f92f9f | 77 | =============== =============== =============== =============================== |
1da177e4 LT |
78 | /dev/fd /proc/self/fd symbolic File descriptors |
79 | /dev/stdin fd/0 symbolic stdin file descriptor | |
80 | /dev/stdout fd/1 symbolic stdout file descriptor | |
81 | /dev/stderr fd/2 symbolic stderr file descriptor | |
82 | /dev/nfsd socksys symbolic Required by iBCS-2 | |
83 | /dev/X0R null symbolic Required by iBCS-2 | |
d9f92f9f | 84 | =============== =============== =============== =============================== |
1da177e4 | 85 | |
d9f92f9f | 86 | Note: ``/dev/X0R`` is <letter X>-<digit 0>-<letter R>. |
1da177e4 | 87 | |
d9f92f9f MCC |
88 | Recommended links |
89 | +++++++++++++++++ | |
1da177e4 LT |
90 | |
91 | It is recommended that these links exist on all systems: | |
92 | ||
d9f92f9f MCC |
93 | |
94 | =============== =============== =============== =============================== | |
1da177e4 LT |
95 | /dev/core /proc/kcore symbolic Backward compatibility |
96 | /dev/ramdisk ram0 symbolic Backward compatibility | |
97 | /dev/ftape qft0 symbolic Backward compatibility | |
98 | /dev/bttv0 video0 symbolic Backward compatibility | |
99 | /dev/radio radio0 symbolic Backward compatibility | |
100 | /dev/i2o* /dev/i2o/* symbolic Backward compatibility | |
101 | /dev/scd? sr? hard Alternate SCSI CD-ROM name | |
d9f92f9f | 102 | =============== =============== =============== =============================== |
1da177e4 | 103 | |
d9f92f9f MCC |
104 | Locally defined links |
105 | +++++++++++++++++++++ | |
1da177e4 LT |
106 | |
107 | The following links may be established locally to conform to the | |
108 | configuration of the system. This is merely a tabulation of existing | |
109 | practice, and does not constitute a recommendation. However, if they | |
110 | exist, they should have the following uses. | |
111 | ||
d9f92f9f | 112 | =============== =============== =============== =============================== |
1da177e4 LT |
113 | /dev/mouse mouse port symbolic Current mouse device |
114 | /dev/tape tape device symbolic Current tape device | |
115 | /dev/cdrom CD-ROM device symbolic Current CD-ROM device | |
116 | /dev/cdwriter CD-writer symbolic Current CD-writer device | |
117 | /dev/scanner scanner symbolic Current scanner device | |
118 | /dev/modem modem port symbolic Current dialout device | |
119 | /dev/root root device symbolic Current root filesystem | |
120 | /dev/swap swap device symbolic Current swap device | |
d9f92f9f | 121 | =============== =============== =============== =============================== |
1da177e4 | 122 | |
d9f92f9f | 123 | ``/dev/modem`` should not be used for a modem which supports dialin as |
1da177e4 | 124 | well as dialout, as it tends to cause lock file problems. If it |
d9f92f9f | 125 | exists, ``/dev/modem`` should point to the appropriate primary TTY device |
1da177e4 LT |
126 | (the use of the alternate callout devices is deprecated). |
127 | ||
d9f92f9f MCC |
128 | For SCSI devices, ``/dev/tape`` and ``/dev/cdrom`` should point to the |
129 | *cooked* devices (``/dev/st*`` and ``/dev/sr*``, respectively), whereas | |
130 | ``/dev/cdwriter`` and /dev/scanner should point to the appropriate generic | |
1da177e4 LT |
131 | SCSI devices (/dev/sg*). |
132 | ||
d9f92f9f MCC |
133 | ``/dev/mouse`` may point to a primary serial TTY device, a hardware mouse |
134 | device, or a socket for a mouse driver program (e.g. ``/dev/gpmdata``). | |
1da177e4 | 135 | |
d9f92f9f MCC |
136 | Sockets and pipes |
137 | +++++++++++++++++ | |
1da177e4 LT |
138 | |
139 | Non-transient sockets and named pipes may exist in /dev. Common entries are: | |
140 | ||
d9f92f9f | 141 | =============== =============== =============================================== |
1da177e4 LT |
142 | /dev/printer socket lpd local socket |
143 | /dev/log socket syslog local socket | |
144 | /dev/gpmdata socket gpm mouse multiplexer | |
d9f92f9f | 145 | =============== =============== =============================================== |
1da177e4 | 146 | |
d9f92f9f MCC |
147 | Mount points |
148 | ++++++++++++ | |
1da177e4 LT |
149 | |
150 | The following names are reserved for mounting special filesystems | |
151 | under /dev. These special filesystems provide kernel interfaces that | |
152 | cannot be provided with standard device nodes. | |
153 | ||
d9f92f9f | 154 | =============== =============== =============================================== |
1da177e4 LT |
155 | /dev/pts devpts PTY slave filesystem |
156 | /dev/shm tmpfs POSIX shared memory maintenance access | |
d9f92f9f | 157 | =============== =============== =============================================== |
1da177e4 | 158 | |
d9f92f9f MCC |
159 | Terminal devices |
160 | ---------------- | |
1da177e4 LT |
161 | |
162 | Terminal, or TTY devices are a special class of character devices. A | |
163 | terminal device is any device that could act as a controlling terminal | |
164 | for a session; this includes virtual consoles, serial ports, and | |
165 | pseudoterminals (PTYs). | |
166 | ||
167 | All terminal devices share a common set of capabilities known as line | |
fff9289b | 168 | disciplines; these include the common terminal line discipline as well |
1da177e4 LT |
169 | as SLIP and PPP modes. |
170 | ||
171 | All terminal devices are named similarly; this section explains the | |
172 | naming and use of the various types of TTYs. Note that the naming | |
173 | conventions include several historical warts; some of these are | |
174 | Linux-specific, some were inherited from other systems, and some | |
175 | reflect Linux outgrowing a borrowed convention. | |
176 | ||
d9f92f9f | 177 | A hash mark (``#``) in a device name is used here to indicate a decimal |
1da177e4 LT |
178 | number without leading zeroes. |
179 | ||
d9f92f9f MCC |
180 | Virtual consoles and the console device |
181 | +++++++++++++++++++++++++++++++++++++++ | |
1da177e4 LT |
182 | |
183 | Virtual consoles are full-screen terminal displays on the system video | |
d9f92f9f MCC |
184 | monitor. Virtual consoles are named ``/dev/tty#``, with numbering |
185 | starting at ``/dev/tty1``; ``/dev/tty0`` is the current virtual console. | |
186 | ``/dev/tty0`` is the device that should be used to access the system video | |
1da177e4 | 187 | card on those architectures for which the frame buffer devices |
d9f92f9f | 188 | (``/dev/fb*``) are not applicable. Do not use ``/dev/console`` |
1da177e4 LT |
189 | for this purpose. |
190 | ||
d9f92f9f | 191 | The console device, ``/dev/console``, is the device to which system |
1da177e4 | 192 | messages should be sent, and on which logins should be permitted in |
d9f92f9f | 193 | single-user mode. Starting with Linux 2.1.71, ``/dev/console`` is managed |
1da177e4 | 194 | by the kernel; for previous versions it should be a symbolic link to |
d9f92f9f MCC |
195 | either ``/dev/tty0``, a specific virtual console such as ``/dev/tty1``, or to |
196 | a serial port primary (``tty*``, not ``cu*``) device, depending on the | |
1da177e4 LT |
197 | configuration of the system. |
198 | ||
d9f92f9f MCC |
199 | Serial ports |
200 | ++++++++++++ | |
1da177e4 LT |
201 | |
202 | Serial ports are RS-232 serial ports and any device which simulates | |
203 | one, either in hardware (such as internal modems) or in software (such | |
204 | as the ISDN driver.) Under Linux, each serial ports has two device | |
205 | names, the primary or callin device and the alternate or callout one. | |
206 | Each kind of device is indicated by a different letter. For any | |
d9f92f9f MCC |
207 | letter X, the names of the devices are ``/dev/ttyX#`` and ``/dev/cux#``, |
208 | respectively; for historical reasons, ``/dev/ttyS#`` and ``/dev/ttyC#`` | |
209 | correspond to ``/dev/cua#`` and ``/dev/cub#``. In the future, it should be | |
1da177e4 | 210 | expected that multiple letters will be used; all letters will be upper |
d9f92f9f MCC |
211 | case for the "tty" device (e.g. ``/dev/ttyDP#``) and lower case for the |
212 | "cu" device (e.g. ``/dev/cudp#``). | |
1da177e4 | 213 | |
d9f92f9f | 214 | The names ``/dev/ttyQ#`` and ``/dev/cuq#`` are reserved for local use. |
1da177e4 LT |
215 | |
216 | The alternate devices provide for kernel-based exclusion and somewhat | |
217 | different defaults than the primary devices. Their main purpose is to | |
218 | allow the use of serial ports with programs with no inherent or broken | |
219 | support for serial ports. Their use is deprecated, and they may be | |
220 | removed from a future version of Linux. | |
221 | ||
222 | Arbitration of serial ports is provided by the use of lock files with | |
d9f92f9f | 223 | the names ``/var/lock/LCK..ttyX#``. The contents of the lock file should |
1da177e4 LT |
224 | be the PID of the locking process as an ASCII number. |
225 | ||
226 | It is common practice to install links such as /dev/modem | |
227 | which point to serial ports. In order to ensure proper locking in the | |
228 | presence of these links, it is recommended that software chase | |
229 | symlinks and lock all possible names; additionally, it is recommended | |
230 | that a lock file be installed with the corresponding alternate | |
231 | device. In order to avoid deadlocks, it is recommended that the locks | |
232 | are acquired in the following order, and released in the reverse: | |
233 | ||
d9f92f9f MCC |
234 | 1. The symbolic link name, if any (``/var/lock/LCK..modem``) |
235 | 2. The "tty" name (``/var/lock/LCK..ttyS2``) | |
236 | 3. The alternate device name (``/var/lock/LCK..cua2``) | |
1da177e4 LT |
237 | |
238 | In the case of nested symbolic links, the lock files should be | |
239 | installed in the order the symlinks are resolved. | |
240 | ||
241 | Under no circumstances should an application hold a lock while waiting | |
242 | for another to be released. In addition, applications which attempt | |
243 | to create lock files for the corresponding alternate device names | |
244 | should take into account the possibility of being used on a non-serial | |
245 | port TTY, for which no alternate device would exist. | |
246 | ||
d9f92f9f MCC |
247 | Pseudoterminals (PTYs) |
248 | ++++++++++++++++++++++ | |
1da177e4 LT |
249 | |
250 | Pseudoterminals, or PTYs, are used to create login sessions or provide | |
fff9289b | 251 | other capabilities requiring a TTY line discipline (including SLIP or |
1da177e4 | 252 | PPP capability) to arbitrary data-generation processes. Each PTY has |
d9f92f9f MCC |
253 | a master side, named ``/dev/pty[p-za-e][0-9a-f]``, and a slave side, named |
254 | ``/dev/tty[p-za-e][0-9a-f]``. The kernel arbitrates the use of PTYs by | |
1da177e4 LT |
255 | allowing each master side to be opened only once. |
256 | ||
257 | Once the master side has been opened, the corresponding slave device | |
258 | can be used in the same manner as any TTY device. The master and | |
259 | slave devices are connected by the kernel, generating the equivalent | |
260 | of a bidirectional pipe with TTY capabilities. | |
261 | ||
262 | Recent versions of the Linux kernels and GNU libc contain support for | |
263 | the System V/Unix98 naming scheme for PTYs, which assigns a common | |
d9f92f9f MCC |
264 | device, ``/dev/ptmx``, to all the masters (opening it will automatically |
265 | give you a previously unassigned PTY) and a subdirectory, ``/dev/pts``, | |
266 | for the slaves; the slaves are named with decimal integers (``/dev/pts/#`` | |
1da177e4 LT |
267 | in our notation). This removes the problem of exhausting the |
268 | namespace and enables the kernel to automatically create the device | |
269 | nodes for the slaves on demand using the "devpts" filesystem. |