devices.rst (12143B)
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.