0001 .. _admin_devices:
0002
0003 Linux allocated devices (4.x+ version)
0004 ======================================
0005
0006 This list is the Linux Device List, the official registry of allocated
0007 device numbers and ``/dev`` directory nodes for the Linux operating
0008 system.
0009
0010 The version of this document at lanana.org is no longer maintained. This
0011 version in the mainline Linux kernel is the master document. Updates
0012 shall be sent as patches to the kernel maintainers (see the
0013 :ref:`Documentation/process/submitting-patches.rst <submittingpatches>` document).
0014 Specifically explore the sections titled "CHAR and MISC DRIVERS", and
0015 "BLOCK LAYER" in the MAINTAINERS file to find the right maintainers
0016 to involve for character and block devices.
0017
0018 This document is included by reference into the Filesystem Hierarchy
0019 Standard (FHS). The FHS is available from https://www.pathname.com/fhs/.
0020
0021 Allocations marked (68k/Amiga) apply to Linux/68k on the Amiga
0022 platform only. Allocations marked (68k/Atari) apply to Linux/68k on
0023 the Atari platform only.
0024
0025 This document is in the public domain. The authors requests, however,
0026 that semantically altered versions are not distributed without
0027 permission of the authors, assuming the authors can be contacted without
0028 an unreasonable effort.
0029
0030
0031 .. attention::
0032
0033 DEVICE DRIVERS AUTHORS PLEASE READ THIS
0034
0035 Linux now has extensive support for dynamic allocation of device numbering
0036 and can use ``sysfs`` and ``udev`` (``systemd``) to handle the naming needs.
0037 There are still some exceptions in the serial and boot device area. Before
0038 asking for a device number make sure you actually need one.
0039
0040 To have a major number allocated, or a minor number in situations
0041 where that applies (e.g. busmice), please submit a patch and send to
0042 the authors as indicated above.
0043
0044 Keep the description of the device *in the same format
0045 as this list*. The reason for this is that it is the only way we have
0046 found to ensure we have all the requisite information to publish your
0047 device and avoid conflicts.
0048
0049 Finally, sometimes we have to play "namespace police." Please don't be
0050 offended. We often get submissions for ``/dev`` names that would be bound
0051 to cause conflicts down the road. We are trying to avoid getting in a
0052 situation where we would have to suffer an incompatible forward
0053 change. Therefore, please consult with us **before** you make your
0054 device names and numbers in any way public, at least to the point
0055 where it would be at all difficult to get them changed.
0056
0057 Your cooperation is appreciated.
0058
0059 .. include:: devices.txt
0060 :literal:
0061
0062 Additional ``/dev/`` directory entries
0063 --------------------------------------
0064
0065 This section details additional entries that should or may exist in
0066 the /dev directory. It is preferred that symbolic links use the same
0067 form (absolute or relative) as is indicated here. Links are
0068 classified as "hard" or "symbolic" depending on the preferred type of
0069 link; if possible, the indicated type of link should be used.
0070
0071 Compulsory links
0072 ++++++++++++++++
0073
0074 These links should exist on all systems:
0075
0076 =============== =============== =============== ===============================
0077 /dev/fd /proc/self/fd symbolic File descriptors
0078 /dev/stdin fd/0 symbolic stdin file descriptor
0079 /dev/stdout fd/1 symbolic stdout file descriptor
0080 /dev/stderr fd/2 symbolic stderr file descriptor
0081 /dev/nfsd socksys symbolic Required by iBCS-2
0082 /dev/X0R null symbolic Required by iBCS-2
0083 =============== =============== =============== ===============================
0084
0085 Note: ``/dev/X0R`` is <letter X>-<digit 0>-<letter R>.
0086
0087 Recommended links
0088 +++++++++++++++++
0089
0090 It is recommended that these links exist on all systems:
0091
0092
0093 =============== =============== =============== ===============================
0094 /dev/core /proc/kcore symbolic Backward compatibility
0095 /dev/ramdisk ram0 symbolic Backward compatibility
0096 /dev/ftape qft0 symbolic Backward compatibility
0097 /dev/bttv0 video0 symbolic Backward compatibility
0098 /dev/radio radio0 symbolic Backward compatibility
0099 /dev/i2o* /dev/i2o/* symbolic Backward compatibility
0100 /dev/scd? sr? hard Alternate SCSI CD-ROM name
0101 =============== =============== =============== ===============================
0102
0103 Locally defined links
0104 +++++++++++++++++++++
0105
0106 The following links may be established locally to conform to the
0107 configuration of the system. This is merely a tabulation of existing
0108 practice, and does not constitute a recommendation. However, if they
0109 exist, they should have the following uses.
0110
0111 =============== =============== =============== ===============================
0112 /dev/mouse mouse port symbolic Current mouse device
0113 /dev/tape tape device symbolic Current tape device
0114 /dev/cdrom CD-ROM device symbolic Current CD-ROM device
0115 /dev/cdwriter CD-writer symbolic Current CD-writer device
0116 /dev/scanner scanner symbolic Current scanner device
0117 /dev/modem modem port symbolic Current dialout device
0118 /dev/root root device symbolic Current root filesystem
0119 /dev/swap swap device symbolic Current swap device
0120 =============== =============== =============== ===============================
0121
0122 ``/dev/modem`` should not be used for a modem which supports dialin as
0123 well as dialout, as it tends to cause lock file problems. If it
0124 exists, ``/dev/modem`` should point to the appropriate primary TTY device
0125 (the use of the alternate callout devices is deprecated).
0126
0127 For SCSI devices, ``/dev/tape`` and ``/dev/cdrom`` should point to the
0128 *cooked* devices (``/dev/st*`` and ``/dev/sr*``, respectively), whereas
0129 ``/dev/cdwriter`` and /dev/scanner should point to the appropriate generic
0130 SCSI devices (/dev/sg*).
0131
0132 ``/dev/mouse`` may point to a primary serial TTY device, a hardware mouse
0133 device, or a socket for a mouse driver program (e.g. ``/dev/gpmdata``).
0134
0135 Sockets and pipes
0136 +++++++++++++++++
0137
0138 Non-transient sockets and named pipes may exist in /dev. Common entries are:
0139
0140 =============== =============== ===============================================
0141 /dev/printer socket lpd local socket
0142 /dev/log socket syslog local socket
0143 /dev/gpmdata socket gpm mouse multiplexer
0144 =============== =============== ===============================================
0145
0146 Mount points
0147 ++++++++++++
0148
0149 The following names are reserved for mounting special filesystems
0150 under /dev. These special filesystems provide kernel interfaces that
0151 cannot be provided with standard device nodes.
0152
0153 =============== =============== ===============================================
0154 /dev/pts devpts PTY slave filesystem
0155 /dev/shm tmpfs POSIX shared memory maintenance access
0156 =============== =============== ===============================================
0157
0158 Terminal devices
0159 ----------------
0160
0161 Terminal, or TTY devices are a special class of character devices. A
0162 terminal device is any device that could act as a controlling terminal
0163 for a session; this includes virtual consoles, serial ports, and
0164 pseudoterminals (PTYs).
0165
0166 All terminal devices share a common set of capabilities known as line
0167 disciplines; these include the common terminal line discipline as well
0168 as SLIP and PPP modes.
0169
0170 All terminal devices are named similarly; this section explains the
0171 naming and use of the various types of TTYs. Note that the naming
0172 conventions include several historical warts; some of these are
0173 Linux-specific, some were inherited from other systems, and some
0174 reflect Linux outgrowing a borrowed convention.
0175
0176 A hash mark (``#``) in a device name is used here to indicate a decimal
0177 number without leading zeroes.
0178
0179 Virtual consoles and the console device
0180 +++++++++++++++++++++++++++++++++++++++
0181
0182 Virtual consoles are full-screen terminal displays on the system video
0183 monitor. Virtual consoles are named ``/dev/tty#``, with numbering
0184 starting at ``/dev/tty1``; ``/dev/tty0`` is the current virtual console.
0185 ``/dev/tty0`` is the device that should be used to access the system video
0186 card on those architectures for which the frame buffer devices
0187 (``/dev/fb*``) are not applicable. Do not use ``/dev/console``
0188 for this purpose.
0189
0190 The console device, ``/dev/console``, is the device to which system
0191 messages should be sent, and on which logins should be permitted in
0192 single-user mode. Starting with Linux 2.1.71, ``/dev/console`` is managed
0193 by the kernel; for previous versions it should be a symbolic link to
0194 either ``/dev/tty0``, a specific virtual console such as ``/dev/tty1``, or to
0195 a serial port primary (``tty*``, not ``cu*``) device, depending on the
0196 configuration of the system.
0197
0198 Serial ports
0199 ++++++++++++
0200
0201 Serial ports are RS-232 serial ports and any device which simulates
0202 one, either in hardware (such as internal modems) or in software (such
0203 as the ISDN driver.) Under Linux, each serial ports has two device
0204 names, the primary or callin device and the alternate or callout one.
0205 Each kind of device is indicated by a different letter. For any
0206 letter X, the names of the devices are ``/dev/ttyX#`` and ``/dev/cux#``,
0207 respectively; for historical reasons, ``/dev/ttyS#`` and ``/dev/ttyC#``
0208 correspond to ``/dev/cua#`` and ``/dev/cub#``. In the future, it should be
0209 expected that multiple letters will be used; all letters will be upper
0210 case for the "tty" device (e.g. ``/dev/ttyDP#``) and lower case for the
0211 "cu" device (e.g. ``/dev/cudp#``).
0212
0213 The names ``/dev/ttyQ#`` and ``/dev/cuq#`` are reserved for local use.
0214
0215 The alternate devices provide for kernel-based exclusion and somewhat
0216 different defaults than the primary devices. Their main purpose is to
0217 allow the use of serial ports with programs with no inherent or broken
0218 support for serial ports. Their use is deprecated, and they may be
0219 removed from a future version of Linux.
0220
0221 Arbitration of serial ports is provided by the use of lock files with
0222 the names ``/var/lock/LCK..ttyX#``. The contents of the lock file should
0223 be the PID of the locking process as an ASCII number.
0224
0225 It is common practice to install links such as /dev/modem
0226 which point to serial ports. In order to ensure proper locking in the
0227 presence of these links, it is recommended that software chase
0228 symlinks and lock all possible names; additionally, it is recommended
0229 that a lock file be installed with the corresponding alternate
0230 device. In order to avoid deadlocks, it is recommended that the locks
0231 are acquired in the following order, and released in the reverse:
0232
0233 1. The symbolic link name, if any (``/var/lock/LCK..modem``)
0234 2. The "tty" name (``/var/lock/LCK..ttyS2``)
0235 3. The alternate device name (``/var/lock/LCK..cua2``)
0236
0237 In the case of nested symbolic links, the lock files should be
0238 installed in the order the symlinks are resolved.
0239
0240 Under no circumstances should an application hold a lock while waiting
0241 for another to be released. In addition, applications which attempt
0242 to create lock files for the corresponding alternate device names
0243 should take into account the possibility of being used on a non-serial
0244 port TTY, for which no alternate device would exist.
0245
0246 Pseudoterminals (PTYs)
0247 ++++++++++++++++++++++
0248
0249 Pseudoterminals, or PTYs, are used to create login sessions or provide
0250 other capabilities requiring a TTY line discipline (including SLIP or
0251 PPP capability) to arbitrary data-generation processes. Each PTY has
0252 a master side, named ``/dev/pty[p-za-e][0-9a-f]``, and a slave side, named
0253 ``/dev/tty[p-za-e][0-9a-f]``. The kernel arbitrates the use of PTYs by
0254 allowing each master side to be opened only once.
0255
0256 Once the master side has been opened, the corresponding slave device
0257 can be used in the same manner as any TTY device. The master and
0258 slave devices are connected by the kernel, generating the equivalent
0259 of a bidirectional pipe with TTY capabilities.
0260
0261 Recent versions of the Linux kernels and GNU libc contain support for
0262 the System V/Unix98 naming scheme for PTYs, which assigns a common
0263 device, ``/dev/ptmx``, to all the masters (opening it will automatically
0264 give you a previously unassigned PTY) and a subdirectory, ``/dev/pts``,
0265 for the slaves; the slaves are named with decimal integers (``/dev/pts/#``
0266 in our notation). This removes the problem of exhausting the
0267 namespace and enables the kernel to automatically create the device
0268 nodes for the slaves on demand using the "devpts" filesystem.
