269 lines · plain
1.. _admin_devices:2 3Linux allocated devices (4.x+ version)4======================================5 6This list is the Linux Device List, the official registry of allocated7device numbers and ``/dev`` directory nodes for the Linux operating8system.9 10The version of this document at lanana.org is no longer maintained. This11version in the mainline Linux kernel is the master document. Updates12shall be sent as patches to the kernel maintainers (see the13:ref:`Documentation/process/submitting-patches.rst <submittingpatches>` document).14Specifically explore the sections titled "CHAR and MISC DRIVERS", and15"BLOCK LAYER" in the MAINTAINERS file to find the right maintainers16to involve for character and block devices.17 18This document is included by reference into the Filesystem Hierarchy19Standard (FHS). The FHS is available from https://www.pathname.com/fhs/.20 21Allocations marked (68k/Amiga) apply to Linux/68k on the Amiga22platform only. Allocations marked (68k/Atari) apply to Linux/68k on23the Atari platform only.24 25This document is in the public domain. The authors requests, however,26that semantically altered versions are not distributed without27permission of the authors, assuming the authors can be contacted without28an unreasonable effort.29 30 31.. attention::32 33 DEVICE DRIVERS AUTHORS PLEASE READ THIS34 35 Linux now has extensive support for dynamic allocation of device numbering36 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. Before38 asking for a device number make sure you actually need one.39 40 To have a major number allocated, or a minor number in situations41 where that applies (e.g. busmice), please submit a patch and send to42 the authors as indicated above.43 44 Keep the description of the device *in the same format45 as this list*. The reason for this is that it is the only way we have46 found to ensure we have all the requisite information to publish your47 device and avoid conflicts.48 49 Finally, sometimes we have to play "namespace police." Please don't be50 offended. We often get submissions for ``/dev`` names that would be bound51 to cause conflicts down the road. We are trying to avoid getting in a52 situation where we would have to suffer an incompatible forward53 change. Therefore, please consult with us **before** you make your54 device names and numbers in any way public, at least to the point55 where it would be at all difficult to get them changed.56 57 Your cooperation is appreciated.58 59.. include:: devices.txt60 :literal:61 62Additional ``/dev/`` directory entries63--------------------------------------64 65This section details additional entries that should or may exist in66the /dev directory. It is preferred that symbolic links use the same67form (absolute or relative) as is indicated here. Links are68classified as "hard" or "symbolic" depending on the preferred type of69link; if possible, the indicated type of link should be used.70 71Compulsory links72++++++++++++++++73 74These links should exist on all systems:75 76=============== =============== =============== ===============================77/dev/fd /proc/self/fd symbolic File descriptors78/dev/stdin fd/0 symbolic stdin file descriptor79/dev/stdout fd/1 symbolic stdout file descriptor80/dev/stderr fd/2 symbolic stderr file descriptor81/dev/nfsd socksys symbolic Required by iBCS-282/dev/X0R null symbolic Required by iBCS-283=============== =============== =============== ===============================84 85Note: ``/dev/X0R`` is <letter X>-<digit 0>-<letter R>.86 87Recommended links88+++++++++++++++++89 90It is recommended that these links exist on all systems:91 92 93=============== =============== =============== ===============================94/dev/core /proc/kcore symbolic Backward compatibility95/dev/ramdisk ram0 symbolic Backward compatibility96/dev/ftape qft0 symbolic Backward compatibility97/dev/bttv0 video0 symbolic Backward compatibility98/dev/radio radio0 symbolic Backward compatibility99/dev/i2o* /dev/i2o/* symbolic Backward compatibility100/dev/scd? sr? hard Alternate SCSI CD-ROM name101=============== =============== =============== ===============================102 103Locally defined links104+++++++++++++++++++++105 106The following links may be established locally to conform to the107configuration of the system. This is merely a tabulation of existing108practice, and does not constitute a recommendation. However, if they109exist, they should have the following uses.110 111=============== =============== =============== ===============================112/dev/mouse mouse port symbolic Current mouse device113/dev/tape tape device symbolic Current tape device114/dev/cdrom CD-ROM device symbolic Current CD-ROM device115/dev/cdwriter CD-writer symbolic Current CD-writer device116/dev/scanner scanner symbolic Current scanner device117/dev/modem modem port symbolic Current dialout device118/dev/root root device symbolic Current root filesystem119/dev/swap swap device symbolic Current swap device120=============== =============== =============== ===============================121 122``/dev/modem`` should not be used for a modem which supports dialin as123well as dialout, as it tends to cause lock file problems. If it124exists, ``/dev/modem`` should point to the appropriate primary TTY device125(the use of the alternate callout devices is deprecated).126 127For SCSI devices, ``/dev/tape`` and ``/dev/cdrom`` should point to the128*cooked* devices (``/dev/st*`` and ``/dev/sr*``, respectively), whereas129``/dev/cdwriter`` and /dev/scanner should point to the appropriate generic130SCSI devices (/dev/sg*).131 132``/dev/mouse`` may point to a primary serial TTY device, a hardware mouse133device, or a socket for a mouse driver program (e.g. ``/dev/gpmdata``).134 135Sockets and pipes136+++++++++++++++++137 138Non-transient sockets and named pipes may exist in /dev. Common entries are:139 140=============== =============== ===============================================141/dev/printer socket lpd local socket142/dev/log socket syslog local socket143/dev/gpmdata socket gpm mouse multiplexer144=============== =============== ===============================================145 146Mount points147++++++++++++148 149The following names are reserved for mounting special filesystems150under /dev. These special filesystems provide kernel interfaces that151cannot be provided with standard device nodes.152 153=============== =============== ===============================================154/dev/pts devpts PTY slave filesystem155/dev/shm tmpfs POSIX shared memory maintenance access156=============== =============== ===============================================157 158Terminal devices159----------------160 161Terminal, or TTY devices are a special class of character devices. A162terminal device is any device that could act as a controlling terminal163for a session; this includes virtual consoles, serial ports, and164pseudoterminals (PTYs).165 166All terminal devices share a common set of capabilities known as line167disciplines; these include the common terminal line discipline as well168as SLIP and PPP modes.169 170All terminal devices are named similarly; this section explains the171naming and use of the various types of TTYs. Note that the naming172conventions include several historical warts; some of these are173Linux-specific, some were inherited from other systems, and some174reflect Linux outgrowing a borrowed convention.175 176A hash mark (``#``) in a device name is used here to indicate a decimal177number without leading zeroes.178 179Virtual consoles and the console device180+++++++++++++++++++++++++++++++++++++++181 182Virtual consoles are full-screen terminal displays on the system video183monitor. Virtual consoles are named ``/dev/tty#``, with numbering184starting at ``/dev/tty1``; ``/dev/tty0`` is the current virtual console.185``/dev/tty0`` is the device that should be used to access the system video186card on those architectures for which the frame buffer devices187(``/dev/fb*``) are not applicable. Do not use ``/dev/console``188for this purpose.189 190The console device, ``/dev/console``, is the device to which system191messages should be sent, and on which logins should be permitted in192single-user mode. Starting with Linux 2.1.71, ``/dev/console`` is managed193by the kernel; for previous versions it should be a symbolic link to194either ``/dev/tty0``, a specific virtual console such as ``/dev/tty1``, or to195a serial port primary (``tty*``, not ``cu*``) device, depending on the196configuration of the system.197 198Serial ports199++++++++++++200 201Serial ports are RS-232 serial ports and any device which simulates202one, either in hardware (such as internal modems) or in software (such203as the ISDN driver.) Under Linux, each serial ports has two device204names, the primary or callin device and the alternate or callout one.205Each kind of device is indicated by a different letter. For any206letter X, the names of the devices are ``/dev/ttyX#`` and ``/dev/cux#``,207respectively; for historical reasons, ``/dev/ttyS#`` and ``/dev/ttyC#``208correspond to ``/dev/cua#`` and ``/dev/cub#``. In the future, it should be209expected that multiple letters will be used; all letters will be upper210case for the "tty" device (e.g. ``/dev/ttyDP#``) and lower case for the211"cu" device (e.g. ``/dev/cudp#``).212 213The names ``/dev/ttyQ#`` and ``/dev/cuq#`` are reserved for local use.214 215The alternate devices provide for kernel-based exclusion and somewhat216different defaults than the primary devices. Their main purpose is to217allow the use of serial ports with programs with no inherent or broken218support for serial ports. Their use is deprecated, and they may be219removed from a future version of Linux.220 221Arbitration of serial ports is provided by the use of lock files with222the names ``/var/lock/LCK..ttyX#``. The contents of the lock file should223be the PID of the locking process as an ASCII number.224 225It is common practice to install links such as /dev/modem226which point to serial ports. In order to ensure proper locking in the227presence of these links, it is recommended that software chase228symlinks and lock all possible names; additionally, it is recommended229that a lock file be installed with the corresponding alternate230device. In order to avoid deadlocks, it is recommended that the locks231are 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 237In the case of nested symbolic links, the lock files should be238installed in the order the symlinks are resolved.239 240Under no circumstances should an application hold a lock while waiting241for another to be released. In addition, applications which attempt242to create lock files for the corresponding alternate device names243should take into account the possibility of being used on a non-serial244port TTY, for which no alternate device would exist.245 246Pseudoterminals (PTYs)247++++++++++++++++++++++248 249Pseudoterminals, or PTYs, are used to create login sessions or provide250other capabilities requiring a TTY line discipline (including SLIP or251PPP capability) to arbitrary data-generation processes. Each PTY has252a master side, named ``/dev/pty[p-za-e][0-9a-f]``, and a slave side, named253``/dev/tty[p-za-e][0-9a-f]``. The kernel arbitrates the use of PTYs by254allowing each master side to be opened only once.255 256Once the master side has been opened, the corresponding slave device257can be used in the same manner as any TTY device. The master and258slave devices are connected by the kernel, generating the equivalent259of a bidirectional pipe with TTY capabilities.260 261Recent versions of the Linux kernels and GNU libc contain support for262the System V/Unix98 naming scheme for PTYs, which assigns a common263device, ``/dev/ptmx``, to all the masters (opening it will automatically264give you a previously unassigned PTY) and a subdirectory, ``/dev/pts``,265for the slaves; the slaves are named with decimal integers (``/dev/pts/#``266in our notation). This removes the problem of exhausting the267namespace and enables the kernel to automatically create the device268nodes for the slaves on demand using the "devpts" filesystem.269