git: edd982b95372 - main - Cross-reference all of uart(4), tty(4) and termios(4)

The branch main has been updated by phk:

URL: https://cgit.FreeBSD.org/src/commit/?id=edd982b95372bee56de4bfe3a61873a8fed254ae

commit edd982b95372bee56de4bfe3a61873a8fed254ae
Author:     Poul-Henning Kamp <phk@FreeBSD.org>
AuthorDate: 2025-12-14 22:09:48 +0000
Commit:     Poul-Henning Kamp <phk@FreeBSD.org>
CommitDate: 2025-12-14 22:09:48 +0000

    Cross-reference all of uart(4), tty(4) and termios(4)
    
    Add a BUGS subsection about why, in the vain hope that somebody
    improves the situation.
---
 share/man/man4/Makefile  |  1 +
 share/man/man4/termios.4 | 11 +++++++++++
 share/man/man4/tty.4     | 16 +++++++++++++---
 share/man/man4/uart.4    | 12 ++++++++++++
 4 files changed, 37 insertions(+), 3 deletions(-)

diff --git a/share/man/man4/Makefile b/share/man/man4/Makefile
index 4084fa55dc69..8cf4a06ea9bb 100644
--- a/share/man/man4/Makefile
+++ b/share/man/man4/Makefile
@@ -809,6 +809,7 @@ MLINKS+=tap.4 if_tap.4 \
 	tap.4 if_vmnet.4
 MLINKS+=tdfx.4 tdfx_linux.4
 MLINKS+=ti.4 if_ti.4
+MLINKS+=tty.4 cua.4
 MLINKS+=tun.4 if_tun.4
 MLINKS+=ure.4 if_ure.4
 MLINKS+=vge.4 if_vge.4
diff --git a/share/man/man4/termios.4 b/share/man/man4/termios.4
index 08b0b81126c3..3d99130c8d33 100644
--- a/share/man/man4/termios.4
+++ b/share/man/man4/termios.4
@@ -1594,4 +1594,15 @@ the values in the header
 .Xr tcsetattr 3 ,
 .Xr tcsetsid 3 ,
 .Xr tty 4 ,
+.Xr uart 4 ,
 .Xr stack 9
+.Sh BUGS
+Before the Internet, serial ports were primarily used for inbound
+connections from terminals, either directly or through modems, these
+days serial ports are primarily used for outbound connections to
+devices, an evolution which unfortunately has spread the relevant
+documentation over three different manual pages:
+.Xr termios 4 ,
+.Xr uart 4 and
+.Xr tty 4 .
+
diff --git a/share/man/man4/tty.4 b/share/man/man4/tty.4
index caa31835a331..ec93ff440855 100644
--- a/share/man/man4/tty.4
+++ b/share/man/man4/tty.4
@@ -37,9 +37,9 @@
 This section describes the interface to the terminal drivers
 in the system.
 .Ss Terminal Special Files
-Each hardware terminal port on the system usually has a terminal special device
-file associated with it in the directory ``/dev/'' (for
-example, ``/dev/tty03'').
+Each hardware terminal port on the system has several terminal special device
+files associated with it in the directory ``/dev/'' (for
+example, ``/dev/tty03'' and ``/dev/cua03'').
 When a user logs into
 the system on one of these hardware terminal ports, the system has already
 opened the associated device and prepared the line for normal interactive
@@ -375,6 +375,7 @@ variables.
 .Xr pts 4 ,
 .Xr pty 4 ,
 .Xr termios 4 ,
+.Xr uart 4 ,
 .Xr getty 8
 .Sh HISTORY
 A console typewriter device
@@ -383,3 +384,12 @@ and asynchronous communication interfaces
 .Pa /dev/tty[0-5]
 first appeared in
 .At v1 .
+.Sh BUGS
+Before the Internet, serial ports were primarily used for inbound
+connections from terminals, either directly or through modems, these
+days serial ports are primarily used for outbound connections to
+devices, an evolution which unfortunately has spread the relevant
+documentation over three different manual pages:
+.Xr termios 4 ,
+.Xr uart 4 and
+.Xr tty 4 .
diff --git a/share/man/man4/uart.4 b/share/man/man4/uart.4
index 98b61886371d..f0b6b23b53d2 100644
--- a/share/man/man4/uart.4
+++ b/share/man/man4/uart.4
@@ -377,6 +377,8 @@ COM2 instead of COM1 and set the baud rate to 115200.
 .Xr cu 1 ,
 .Xr puc 4 ,
 .Xr scc 4 ,
+.Xr termios 4 ,
+.Xr tty 4 ,
 .Xr ttys 5
 .\"
 .Sh HISTORY
@@ -389,3 +391,13 @@ The
 .Nm
 device driver and this manual page were written by
 .An Marcel Moolenaar Aq Mt marcel@xcllnt.net .
+.Sh BUGS
+Before the Internet, serial ports were primarily used for inbound
+connections from terminals, either directly or through modems, these
+days serial ports are primarily used for outbound connections to
+devices, an evolution which unfortunately has spread the relevant
+documentation over three different manual pages:
+.Xr termios 4 ,
+.Xr uart 4 and
+.Xr tty 4 .
+