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