devices.rst 12 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269
  1. .. _admin_devices:
  2. Linux allocated devices (4.x+ version)
  3. ======================================
  4. This list is the Linux Device List, the official registry of allocated
  5. device numbers and ``/dev`` directory nodes for the Linux operating
  6. system.
  7. The LaTeX version of this document is no longer maintained, nor is
  8. the document that used to reside at lanana.org. This version in the
  9. mainline Linux kernel is the master document. Updates shall be sent
  10. as patches to the kernel maintainers (see the
  11. :ref:`Documentation/process/submitting-patches.rst <submittingpatches>` document).
  12. Specifically explore the sections titled "CHAR and MISC DRIVERS", and
  13. "BLOCK LAYER" in the MAINTAINERS file to find the right maintainers
  14. to involve for character and block devices.
  15. This document is included by reference into the Filesystem Hierarchy
  16. Standard (FHS). The FHS is available from https://www.pathname.com/fhs/.
  17. Allocations marked (68k/Amiga) apply to Linux/68k on the Amiga
  18. platform only. Allocations marked (68k/Atari) apply to Linux/68k on
  19. the Atari platform only.
  20. This document is in the public domain. The authors requests, however,
  21. that semantically altered versions are not distributed without
  22. permission of the authors, assuming the authors can be contacted without
  23. an unreasonable effort.
  24. .. attention::
  25. DEVICE DRIVERS AUTHORS PLEASE READ THIS
  26. Linux now has extensive support for dynamic allocation of device numbering
  27. and can use ``sysfs`` and ``udev`` (``systemd``) to handle the naming needs.
  28. There are still some exceptions in the serial and boot device area. Before
  29. asking for a device number make sure you actually need one.
  30. To have a major number allocated, or a minor number in situations
  31. where that applies (e.g. busmice), please submit a patch and send to
  32. the authors as indicated above.
  33. Keep the description of the device *in the same format
  34. as this list*. The reason for this is that it is the only way we have
  35. found to ensure we have all the requisite information to publish your
  36. device and avoid conflicts.
  37. Finally, sometimes we have to play "namespace police." Please don't be
  38. offended. We often get submissions for ``/dev`` names that would be bound
  39. to cause conflicts down the road. We are trying to avoid getting in a
  40. situation where we would have to suffer an incompatible forward
  41. change. Therefore, please consult with us **before** you make your
  42. device names and numbers in any way public, at least to the point
  43. where it would be at all difficult to get them changed.
  44. Your cooperation is appreciated.
  45. .. include:: devices.txt
  46. :literal:
  47. Additional ``/dev/`` directory entries
  48. --------------------------------------
  49. This section details additional entries that should or may exist in
  50. the /dev directory. It is preferred that symbolic links use the same
  51. form (absolute or relative) as is indicated here. Links are
  52. classified as "hard" or "symbolic" depending on the preferred type of
  53. link; if possible, the indicated type of link should be used.
  54. Compulsory links
  55. ++++++++++++++++
  56. These links should exist on all systems:
  57. =============== =============== =============== ===============================
  58. /dev/fd /proc/self/fd symbolic File descriptors
  59. /dev/stdin fd/0 symbolic stdin file descriptor
  60. /dev/stdout fd/1 symbolic stdout file descriptor
  61. /dev/stderr fd/2 symbolic stderr file descriptor
  62. /dev/nfsd socksys symbolic Required by iBCS-2
  63. /dev/X0R null symbolic Required by iBCS-2
  64. =============== =============== =============== ===============================
  65. Note: ``/dev/X0R`` is <letter X>-<digit 0>-<letter R>.
  66. Recommended links
  67. +++++++++++++++++
  68. It is recommended that these links exist on all systems:
  69. =============== =============== =============== ===============================
  70. /dev/core /proc/kcore symbolic Backward compatibility
  71. /dev/ramdisk ram0 symbolic Backward compatibility
  72. /dev/ftape qft0 symbolic Backward compatibility
  73. /dev/bttv0 video0 symbolic Backward compatibility
  74. /dev/radio radio0 symbolic Backward compatibility
  75. /dev/i2o* /dev/i2o/* symbolic Backward compatibility
  76. /dev/scd? sr? hard Alternate SCSI CD-ROM name
  77. =============== =============== =============== ===============================
  78. Locally defined links
  79. +++++++++++++++++++++
  80. The following links may be established locally to conform to the
  81. configuration of the system. This is merely a tabulation of existing
  82. practice, and does not constitute a recommendation. However, if they
  83. exist, they should have the following uses.
  84. =============== =============== =============== ===============================
  85. /dev/mouse mouse port symbolic Current mouse device
  86. /dev/tape tape device symbolic Current tape device
  87. /dev/cdrom CD-ROM device symbolic Current CD-ROM device
  88. /dev/cdwriter CD-writer symbolic Current CD-writer device
  89. /dev/scanner scanner symbolic Current scanner device
  90. /dev/modem modem port symbolic Current dialout device
  91. /dev/root root device symbolic Current root filesystem
  92. /dev/swap swap device symbolic Current swap device
  93. =============== =============== =============== ===============================
  94. ``/dev/modem`` should not be used for a modem which supports dialin as
  95. well as dialout, as it tends to cause lock file problems. If it
  96. exists, ``/dev/modem`` should point to the appropriate primary TTY device
  97. (the use of the alternate callout devices is deprecated).
  98. For SCSI devices, ``/dev/tape`` and ``/dev/cdrom`` should point to the
  99. *cooked* devices (``/dev/st*`` and ``/dev/sr*``, respectively), whereas
  100. ``/dev/cdwriter`` and /dev/scanner should point to the appropriate generic
  101. SCSI devices (/dev/sg*).
  102. ``/dev/mouse`` may point to a primary serial TTY device, a hardware mouse
  103. device, or a socket for a mouse driver program (e.g. ``/dev/gpmdata``).
  104. Sockets and pipes
  105. +++++++++++++++++
  106. Non-transient sockets and named pipes may exist in /dev. Common entries are:
  107. =============== =============== ===============================================
  108. /dev/printer socket lpd local socket
  109. /dev/log socket syslog local socket
  110. /dev/gpmdata socket gpm mouse multiplexer
  111. =============== =============== ===============================================
  112. Mount points
  113. ++++++++++++
  114. The following names are reserved for mounting special filesystems
  115. under /dev. These special filesystems provide kernel interfaces that
  116. cannot be provided with standard device nodes.
  117. =============== =============== ===============================================
  118. /dev/pts devpts PTY slave filesystem
  119. /dev/shm tmpfs POSIX shared memory maintenance access
  120. =============== =============== ===============================================
  121. Terminal devices
  122. ----------------
  123. Terminal, or TTY devices are a special class of character devices. A
  124. terminal device is any device that could act as a controlling terminal
  125. for a session; this includes virtual consoles, serial ports, and
  126. pseudoterminals (PTYs).
  127. All terminal devices share a common set of capabilities known as line
  128. disciplines; these include the common terminal line discipline as well
  129. as SLIP and PPP modes.
  130. All terminal devices are named similarly; this section explains the
  131. naming and use of the various types of TTYs. Note that the naming
  132. conventions include several historical warts; some of these are
  133. Linux-specific, some were inherited from other systems, and some
  134. reflect Linux outgrowing a borrowed convention.
  135. A hash mark (``#``) in a device name is used here to indicate a decimal
  136. number without leading zeroes.
  137. Virtual consoles and the console device
  138. +++++++++++++++++++++++++++++++++++++++
  139. Virtual consoles are full-screen terminal displays on the system video
  140. monitor. Virtual consoles are named ``/dev/tty#``, with numbering
  141. starting at ``/dev/tty1``; ``/dev/tty0`` is the current virtual console.
  142. ``/dev/tty0`` is the device that should be used to access the system video
  143. card on those architectures for which the frame buffer devices
  144. (``/dev/fb*``) are not applicable. Do not use ``/dev/console``
  145. for this purpose.
  146. The console device, ``/dev/console``, is the device to which system
  147. messages should be sent, and on which logins should be permitted in
  148. single-user mode. Starting with Linux 2.1.71, ``/dev/console`` is managed
  149. by the kernel; for previous versions it should be a symbolic link to
  150. either ``/dev/tty0``, a specific virtual console such as ``/dev/tty1``, or to
  151. a serial port primary (``tty*``, not ``cu*``) device, depending on the
  152. configuration of the system.
  153. Serial ports
  154. ++++++++++++
  155. Serial ports are RS-232 serial ports and any device which simulates
  156. one, either in hardware (such as internal modems) or in software (such
  157. as the ISDN driver.) Under Linux, each serial ports has two device
  158. names, the primary or callin device and the alternate or callout one.
  159. Each kind of device is indicated by a different letter. For any
  160. letter X, the names of the devices are ``/dev/ttyX#`` and ``/dev/cux#``,
  161. respectively; for historical reasons, ``/dev/ttyS#`` and ``/dev/ttyC#``
  162. correspond to ``/dev/cua#`` and ``/dev/cub#``. In the future, it should be
  163. expected that multiple letters will be used; all letters will be upper
  164. case for the "tty" device (e.g. ``/dev/ttyDP#``) and lower case for the
  165. "cu" device (e.g. ``/dev/cudp#``).
  166. The names ``/dev/ttyQ#`` and ``/dev/cuq#`` are reserved for local use.
  167. The alternate devices provide for kernel-based exclusion and somewhat
  168. different defaults than the primary devices. Their main purpose is to
  169. allow the use of serial ports with programs with no inherent or broken
  170. support for serial ports. Their use is deprecated, and they may be
  171. removed from a future version of Linux.
  172. Arbitration of serial ports is provided by the use of lock files with
  173. the names ``/var/lock/LCK..ttyX#``. The contents of the lock file should
  174. be the PID of the locking process as an ASCII number.
  175. It is common practice to install links such as /dev/modem
  176. which point to serial ports. In order to ensure proper locking in the
  177. presence of these links, it is recommended that software chase
  178. symlinks and lock all possible names; additionally, it is recommended
  179. that a lock file be installed with the corresponding alternate
  180. device. In order to avoid deadlocks, it is recommended that the locks
  181. are acquired in the following order, and released in the reverse:
  182. 1. The symbolic link name, if any (``/var/lock/LCK..modem``)
  183. 2. The "tty" name (``/var/lock/LCK..ttyS2``)
  184. 3. The alternate device name (``/var/lock/LCK..cua2``)
  185. In the case of nested symbolic links, the lock files should be
  186. installed in the order the symlinks are resolved.
  187. Under no circumstances should an application hold a lock while waiting
  188. for another to be released. In addition, applications which attempt
  189. to create lock files for the corresponding alternate device names
  190. should take into account the possibility of being used on a non-serial
  191. port TTY, for which no alternate device would exist.
  192. Pseudoterminals (PTYs)
  193. ++++++++++++++++++++++
  194. Pseudoterminals, or PTYs, are used to create login sessions or provide
  195. other capabilities requiring a TTY line discipline (including SLIP or
  196. PPP capability) to arbitrary data-generation processes. Each PTY has
  197. a master side, named ``/dev/pty[p-za-e][0-9a-f]``, and a slave side, named
  198. ``/dev/tty[p-za-e][0-9a-f]``. The kernel arbitrates the use of PTYs by
  199. allowing each master side to be opened only once.
  200. Once the master side has been opened, the corresponding slave device
  201. can be used in the same manner as any TTY device. The master and
  202. slave devices are connected by the kernel, generating the equivalent
  203. of a bidirectional pipe with TTY capabilities.
  204. Recent versions of the Linux kernels and GNU libc contain support for
  205. the System V/Unix98 naming scheme for PTYs, which assigns a common
  206. device, ``/dev/ptmx``, to all the masters (opening it will automatically
  207. give you a previously unassigned PTY) and a subdirectory, ``/dev/pts``,
  208. for the slaves; the slaves are named with decimal integers (``/dev/pts/#``
  209. in our notation). This removes the problem of exhausting the
  210. namespace and enables the kernel to automatically create the device
  211. nodes for the slaves on demand using the "devpts" filesystem.