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