Documentation/admin-guide/devices.rst

   1
   2 Linux allocated devices (4.x+ version)
   3 ======================================
   4
   5 This list is the Linux Device List, the official registry of allocated
   6 device numbers and ``/dev`` directory nodes for the Linux operating
   7 system.
   8
   9 The LaTeX version of this document is no longer maintained, nor is
  10 the document that used to reside at lanana.org.  This version in the
  11 mainline Linux kernel is the master document.  Updates shall be sent
  12 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 http://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 /dev/scd?       sr?             hard            Alternate SCSI CD-ROM name
 101 =============== =============== =============== ===============================
 102
 103 Locally defined links
 104 +++++++++++++++++++++
 105
 106 The following links may be established locally to conform to the
 107 configuration of the system.  This is merely a tabulation of existing
 108 practice, and does not constitute a recommendation.  However, if they
 109 exist, 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
 123 well as dialout, as it tends to cause lock file problems.  If it
 124 exists, ``/dev/modem`` should point to the appropriate primary TTY device
 125 (the use of the alternate callout devices is deprecated).
 126
 127 For 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
 130 SCSI devices (/dev/sg*).
 131
 132 ``/dev/mouse`` may point to a primary serial TTY device, a hardware mouse
 133 device, or a socket for a mouse driver program (e.g. ``/dev/gpmdata``).
 134
 135 Sockets and pipes
 136 +++++++++++++++++
 137
 138 Non-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
 146 Mount points
 147 ++++++++++++
 148
 149 The following names are reserved for mounting special filesystems
 150 under /dev.  These special filesystems provide kernel interfaces that
 151 cannot 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
 158 Terminal devices
 159 ----------------
 160
 161 Terminal, or TTY devices are a special class of character devices.  A
 162 terminal device is any device that could act as a controlling terminal
 163 for a session; this includes virtual consoles, serial ports, and
 164 pseudoterminals (PTYs).
 165
 166 All terminal devices share a common set of capabilities known as line
 167 disciplines; these include the common terminal line discipline as well
 168 as SLIP and PPP modes.
 169
 170 All terminal devices are named similarly; this section explains the
 171 naming and use of the various types of TTYs.  Note that the naming
 172 conventions include several historical warts; some of these are
 173 Linux-specific, some were inherited from other systems, and some
 174 reflect Linux outgrowing a borrowed convention.
 175
 176 A hash mark (``#``) in a device name is used here to indicate a decimal
 177 number without leading zeroes.
 178
 179 Virtual consoles and the console device
 180 +++++++++++++++++++++++++++++++++++++++
 181
 182 Virtual consoles are full-screen terminal displays on the system video
 183 monitor.  Virtual consoles are named ``/dev/tty#``, with numbering
 184 starting 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
 186 card on those architectures for which the frame buffer devices
 187 (``/dev/fb*``) are not applicable. Do not use ``/dev/console``
 188 for this purpose.
 189
 190 The console device, ``/dev/console``, is the device to which system
 191 messages should be sent, and on which logins should be permitted in
 192 single-user mode.  Starting with Linux 2.1.71, ``/dev/console`` is managed
 193 by the kernel; for previous versions it should be a symbolic link to
 194 either ``/dev/tty0``, a specific virtual console such as ``/dev/tty1``, or to
 195 a serial port primary (``tty*``, not ``cu*``) device, depending on the
 196 configuration of the system.
 197
 198 Serial ports
 199 ++++++++++++
 200
 201 Serial ports are RS-232 serial ports and any device which simulates
 202 one, either in hardware (such as internal modems) or in software (such
 203 as the ISDN driver.)  Under Linux, each serial ports has two device
 204 names, the primary or callin device and the alternate or callout one.
 205 Each kind of device is indicated by a different letter.  For any
 206 letter X, the names of the devices are ``/dev/ttyX#`` and ``/dev/cux#``,
 207 respectively; for historical reasons, ``/dev/ttyS#`` and ``/dev/ttyC#``
 208 correspond to ``/dev/cua#`` and ``/dev/cub#``. In the future, it should be
 209 expected that multiple letters will be used; all letters will be upper
 210 case for the "tty" device (e.g. ``/dev/ttyDP#``) and lower case for the
 211 "cu" device (e.g. ``/dev/cudp#``).
 212
 213 The names ``/dev/ttyQ#`` and ``/dev/cuq#`` are reserved for local use.
 214
 215 The alternate devices provide for kernel-based exclusion and somewhat
 216 different defaults than the primary devices.  Their main purpose is to
 217 allow the use of serial ports with programs with no inherent or broken
 218 support for serial ports.  Their use is deprecated, and they may be
 219 removed from a future version of Linux.
 220
 221 Arbitration of serial ports is provided by the use of lock files with
 222 the names ``/var/lock/LCK..ttyX#``. The contents of the lock file should
 223 be the PID of the locking process as an ASCII number.
 224
 225 It is common practice to install links such as /dev/modem
 226 which point to serial ports.  In order to ensure proper locking in the
 227 presence of these links, it is recommended that software chase
 228 symlinks and lock all possible names; additionally, it is recommended
 229 that a lock file be installed with the corresponding alternate
 230 device.  In order to avoid deadlocks, it is recommended that the locks
 231 are 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
 237 In the case of nested symbolic links, the lock files should be
 238 installed in the order the symlinks are resolved.
 239
 240 Under no circumstances should an application hold a lock while waiting
 241 for another to be released.  In addition, applications which attempt
 242 to create lock files for the corresponding alternate device names
 243 should take into account the possibility of being used on a non-serial
 244 port TTY, for which no alternate device would exist.
 245
 246 Pseudoterminals (PTYs)
 247 ++++++++++++++++++++++
 248
 249 Pseudoterminals, or PTYs, are used to create login sessions or provide
 250 other capabilities requiring a TTY line discipline (including SLIP or
 251 PPP capability) to arbitrary data-generation processes.  Each PTY has
 252 a 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
 254 allowing each master side to be opened only once.
 255
 256 Once the master side has been opened, the corresponding slave device
 257 can be used in the same manner as any TTY device.  The master and
 258 slave devices are connected by the kernel, generating the equivalent
 259 of a bidirectional pipe with TTY capabilities.
 260
 261 Recent versions of the Linux kernels and GNU libc contain support for
 262 the System V/Unix98 naming scheme for PTYs, which assigns a common
 263 device, ``/dev/ptmx``, to all the masters (opening it will automatically
 264 give you a previously unassigned PTY) and a subdirectory, ``/dev/pts``,
 265 for the slaves; the slaves are named with decimal integers (``/dev/pts/#``
 266 in our notation).  This removes the problem of exhausting the
 267 namespace and enables the kernel to automatically create the device
 268 nodes for the slaves on demand using the "devpts" filesystem.