1.. _admin_devices:
2
3Linux allocated devices (4.x+ version)
4======================================
5
6This list is the Linux Device List, the official registry of allocated
7device numbers and ``/dev`` directory nodes for the Linux operating
8system.
9
10The LaTeX version of this document is no longer maintained, nor is
11the document that used to reside at lanana.org.  This version in the
12mainline Linux kernel is the master document.  Updates shall be sent
13as patches to the kernel maintainers (see the
14:ref:`Documentation/process/submitting-patches.rst <submittingpatches>` document).
15Specifically explore the sections titled "CHAR and MISC DRIVERS", and
16"BLOCK LAYER" in the MAINTAINERS file to find the right maintainers
17to involve for character and block devices.
18
19This document is included by reference into the Filesystem Hierarchy
20Standard (FHS).	 The FHS is available from https://www.pathname.com/fhs/.
21
22Allocations marked (68k/Amiga) apply to Linux/68k on the Amiga
23platform only.	Allocations marked (68k/Atari) apply to Linux/68k on
24the Atari platform only.
25
26This document is in the public domain.	The authors requests, however,
27that semantically altered versions are not distributed without
28permission of the authors, assuming the authors can be contacted without
29an unreasonable effort.
30
31
32.. attention::
33
34  DEVICE DRIVERS AUTHORS PLEASE READ THIS
35
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.
40
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.
44
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.
49
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.
57
58  Your cooperation is appreciated.
59
60.. include:: devices.txt
61   :literal:
62
63Additional ``/dev/`` directory entries
64--------------------------------------
65
66This section details additional entries that should or may exist in
67the /dev directory.  It is preferred that symbolic links use the same
68form (absolute or relative) as is indicated here.  Links are
69classified as "hard" or "symbolic" depending on the preferred type of
70link; if possible, the indicated type of link should be used.
71
72Compulsory links
73++++++++++++++++
74
75These links should exist on all systems:
76
77=============== =============== =============== ===============================
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
84=============== =============== =============== ===============================
85
86Note: ``/dev/X0R`` is <letter X>-<digit 0>-<letter R>.
87
88Recommended links
89+++++++++++++++++
90
91It is recommended that these links exist on all systems:
92
93
94=============== =============== =============== ===============================
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
102=============== =============== =============== ===============================
103
104Locally defined links
105+++++++++++++++++++++
106
107The following links may be established locally to conform to the
108configuration of the system.  This is merely a tabulation of existing
109practice, and does not constitute a recommendation.  However, if they
110exist, they should have the following uses.
111
112=============== =============== =============== ===============================
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
121=============== =============== =============== ===============================
122
123``/dev/modem`` should not be used for a modem which supports dialin as
124well as dialout, as it tends to cause lock file problems.  If it
125exists, ``/dev/modem`` should point to the appropriate primary TTY device
126(the use of the alternate callout devices is deprecated).
127
128For 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
131SCSI devices (/dev/sg*).
132
133``/dev/mouse`` may point to a primary serial TTY device, a hardware mouse
134device, or a socket for a mouse driver program (e.g. ``/dev/gpmdata``).
135
136Sockets and pipes
137+++++++++++++++++
138
139Non-transient sockets and named pipes may exist in /dev.  Common entries are:
140
141=============== =============== ===============================================
142/dev/printer	socket		lpd local socket
143/dev/log	socket		syslog local socket
144/dev/gpmdata	socket		gpm mouse multiplexer
145=============== =============== ===============================================
146
147Mount points
148++++++++++++
149
150The following names are reserved for mounting special filesystems
151under /dev.  These special filesystems provide kernel interfaces that
152cannot be provided with standard device nodes.
153
154=============== =============== ===============================================
155/dev/pts	devpts		PTY slave filesystem
156/dev/shm	tmpfs		POSIX shared memory maintenance access
157=============== =============== ===============================================
158
159Terminal devices
160----------------
161
162Terminal, or TTY devices are a special class of character devices.  A
163terminal device is any device that could act as a controlling terminal
164for a session; this includes virtual consoles, serial ports, and
165pseudoterminals (PTYs).
166
167All terminal devices share a common set of capabilities known as line
168disciplines; these include the common terminal line discipline as well
169as SLIP and PPP modes.
170
171All terminal devices are named similarly; this section explains the
172naming and use of the various types of TTYs.  Note that the naming
173conventions include several historical warts; some of these are
174Linux-specific, some were inherited from other systems, and some
175reflect Linux outgrowing a borrowed convention.
176
177A hash mark (``#``) in a device name is used here to indicate a decimal
178number without leading zeroes.
179
180Virtual consoles and the console device
181+++++++++++++++++++++++++++++++++++++++
182
183Virtual consoles are full-screen terminal displays on the system video
184monitor.  Virtual consoles are named ``/dev/tty#``, with numbering
185starting 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
187card on those architectures for which the frame buffer devices
188(``/dev/fb*``) are not applicable. Do not use ``/dev/console``
189for this purpose.
190
191The console device, ``/dev/console``, is the device to which system
192messages should be sent, and on which logins should be permitted in
193single-user mode.  Starting with Linux 2.1.71, ``/dev/console`` is managed
194by the kernel; for previous versions it should be a symbolic link to
195either ``/dev/tty0``, a specific virtual console such as ``/dev/tty1``, or to
196a serial port primary (``tty*``, not ``cu*``) device, depending on the
197configuration of the system.
198
199Serial ports
200++++++++++++
201
202Serial ports are RS-232 serial ports and any device which simulates
203one, either in hardware (such as internal modems) or in software (such
204as the ISDN driver.)  Under Linux, each serial ports has two device
205names, the primary or callin device and the alternate or callout one.
206Each kind of device is indicated by a different letter.	 For any
207letter X, the names of the devices are ``/dev/ttyX#`` and ``/dev/cux#``,
208respectively; for historical reasons, ``/dev/ttyS#`` and ``/dev/ttyC#``
209correspond to ``/dev/cua#`` and ``/dev/cub#``. In the future, it should be
210expected that multiple letters will be used; all letters will be upper
211case for the "tty" device (e.g. ``/dev/ttyDP#``) and lower case for the
212"cu" device (e.g. ``/dev/cudp#``).
213
214The names ``/dev/ttyQ#`` and ``/dev/cuq#`` are reserved for local use.
215
216The alternate devices provide for kernel-based exclusion and somewhat
217different defaults than the primary devices.  Their main purpose is to
218allow the use of serial ports with programs with no inherent or broken
219support for serial ports.  Their use is deprecated, and they may be
220removed from a future version of Linux.
221
222Arbitration of serial ports is provided by the use of lock files with
223the names ``/var/lock/LCK..ttyX#``. The contents of the lock file should
224be the PID of the locking process as an ASCII number.
225
226It is common practice to install links such as /dev/modem
227which point to serial ports.  In order to ensure proper locking in the
228presence of these links, it is recommended that software chase
229symlinks and lock all possible names; additionally, it is recommended
230that a lock file be installed with the corresponding alternate
231device.	 In order to avoid deadlocks, it is recommended that the locks
232are acquired in the following order, and released in the reverse:
233
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``)
237
238In the case of nested symbolic links, the lock files should be
239installed in the order the symlinks are resolved.
240
241Under no circumstances should an application hold a lock while waiting
242for another to be released.  In addition, applications which attempt
243to create lock files for the corresponding alternate device names
244should take into account the possibility of being used on a non-serial
245port TTY, for which no alternate device would exist.
246
247Pseudoterminals (PTYs)
248++++++++++++++++++++++
249
250Pseudoterminals, or PTYs, are used to create login sessions or provide
251other capabilities requiring a TTY line discipline (including SLIP or
252PPP capability) to arbitrary data-generation processes.	 Each PTY has
253a 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
255allowing each master side to be opened only once.
256
257Once the master side has been opened, the corresponding slave device
258can be used in the same manner as any TTY device.  The master and
259slave devices are connected by the kernel, generating the equivalent
260of a bidirectional pipe with TTY capabilities.
261
262Recent versions of the Linux kernels and GNU libc contain support for
263the System V/Unix98 naming scheme for PTYs, which assigns a common
264device, ``/dev/ptmx``, to all the masters (opening it will automatically
265give you a previously unassigned PTY) and a subdirectory, ``/dev/pts``,
266for the slaves; the slaves are named with decimal integers (``/dev/pts/#``
267in our notation).  This removes the problem of exhausting the
268namespace and enables the kernel to automatically create the device
269nodes for the slaves on demand using the "devpts" filesystem.
270