[PATCH v2 1/4] man/man3*: document the glibc 2.42+ baud_t termios interface

["H. Peter Anvin" <hpa@zytor.com>]

glibc 2.42+ has a new set of interfaces to get and set arbitrary baud
rates. Add them to the man pages.

This removes from termios(3) some details about the baud rate
constants: they are now an open set in glibc, simply defined to be
equivalent to their numeric value (e.g. B300 == 300). Thus, stating
that certain architectures only support certain values is no longer
correct.

This also removes references from termios(3) about the interior of the
ioctl interfaces: the statement about TCSETS2, for example, was always
incorrect (TCSETS2 doesn't exist on all Linux architectures.) That
kind of information belongs in ioctl_tty(2), anyway, especially since
including <linux/termios.h> -> <asm/termbits.h> is not compatible with
including <termios.h>.

Signed-off-by: H. Peter Anvin (Intel) <hpa@zytor.com>
---
 man/man3/termios.3        | 318 ++++++++++++++++++--------------------
 man/man3type/baud_t.3type |   1 +
 man/man3type/cc_t.3type   |  42 ++++-
 3 files changed, 193 insertions(+), 168 deletions(-)
 create mode 100644 man/man3type/baud_t.3type

diff --git a/man/man3/termios.3 b/man/man3/termios.3
index 0942cca8084e..cd3f9ce4d7c0 100644
--- a/man/man3/termios.3
+++ b/man/man3/termios.3
@@ -7,7 +7,8 @@
 .TH termios 3 (date) "Linux man-pages (unreleased)"
 .SH NAME
 termios, tcgetattr, tcsetattr, tcsendbreak, tcdrain, tcflush, tcflow,
-cfmakeraw, cfgetospeed, cfgetispeed, cfsetispeed, cfsetospeed, cfsetspeed \-
+cfmakeraw, cfgetispeed, cfgetospeed, cfsetispeed, cfsetospeed,
+cfsetspeed, cfgetobaud, cfgetibaud, cfsetibaud, cfsetobaud, cfsetbaud \-
 get and set terminal attributes, line control, get and set baud rate
 .SH LIBRARY
 Standard C library
@@ -34,6 +35,13 @@ Standard C library
 .BI "int cfsetispeed(struct termios *" termios_p ", speed_t " speed );
 .BI "int cfsetospeed(struct termios *" termios_p ", speed_t " speed );
 .BI "int cfsetspeed(struct termios *" termios_p ", speed_t " speed );
+.P
+.BI "baud_t cfgetibaud(const struct termios *" termios_p );
+.BI "baud_t cfgetobaud(const struct termios *" termios_p );
+.P
+.BI "int cfsetibaud(struct termios *" termios_p ", baud_t " baud );
+.BI "int cfsetobaud(struct termios *" termios_p ", baud_t " baud );
+.BI "int cfsetbaud(struct termios *" termios_p ", baud_t " baud );
 .fi
 .P
 .RS -4
@@ -49,6 +57,16 @@ Feature Test Macro Requirements for glibc (see
     glibc 2.19 and earlier:
         _BSD_SOURCE
 .fi
+.P
+.BR cfgetibaud (),
+.BR cfgetobaud (),
+.BR cfsetibaud (),
+.BR cfsetobaud (),
+.BR cfsetbaud ():
+.nf
+    Since glibc 2.42:
+        _GNU_SOURCE
+.fi
 .SH DESCRIPTION
 The termios functions describe a general terminal interface that is
 provided to control asynchronous communications ports.
@@ -305,30 +323,33 @@ flag constants:
 .B _BSD_SOURCE
 or
 .BR _SVID_SOURCE ]
-.TP
-.B CBAUDEX
-(not in POSIX) Extra baud speed mask (1 bit), included in
-.BR CBAUD .
-[requires
-.B _BSD_SOURCE
-or
-.BR _SVID_SOURCE ]
 .IP
-(POSIX says that the baud speed is stored in the
-.I termios
-structure without specifying where precisely, and provides
-.BR cfgetispeed ()
+This bitmask should only be used when invoking the kernel
+.BR ioctl ()
+interface directly.
+.P
+Instead, the
+.BR cfgetospeed (),
+.BR cfgetobaud (),
+.BR cfsetospeed ()
 and
-.BR cfsetispeed ()
-for getting at it.
+.BR cfsetobaud ()
+functions should be used in application code.
+.P
 Some systems use bits selected by
 .B CBAUD
 in
 .IR c_cflag ,
-other systems use separate fields, for example,
-.I sg_ispeed
-and
-.IR sg_ospeed .)
+other systems use separate fields, Linux uses
+.IR both .
+.TP
+.B CBAUDEX
+(not in POSIX) Extra baud speed mask (1 bit), included in
+.BR CBAUD .
+[requires
+.B _BSD_SOURCE
+or
+.BR _SVID_SOURCE ]
 .TP
 .B CSIZE
 Character size mask.
@@ -379,13 +400,17 @@ bits.
 .B _BSD_SOURCE
 or
 .BR _SVID_SOURCE ]
-(Not implemented in glibc, supported on Linux via
-.BR TCGET *
+This bitmask should only be used when invoking the kernel
+.BR ioctl ()
+interface directly (see
+.BR ioctl_tty (2)).
+Instead, the
+.BR cfgetispeed (),
+.BR cfgetibaud (),
+.BR cfsetispeed ()
 and
-.BR TCSET *
-ioctls;
-see
-.BR ioctl_tty (2))
+.BR cfsetibaud ()
+functions should be used in application code.
 .TP
 .B CMSPAR
 (not in POSIX)
@@ -1068,114 +1093,22 @@ until
 .BR tcsetattr ()
 is successfully called.
 .P
-Setting the speed to
-.B B0
+Setting the output speed to zero
 instructs the modem to "hang up".
-The actual bit rate corresponding to
-.B B38400
-may be altered with
-.BR setserial (8).
 .P
-The input and output baud rates are stored in the
-.I termios
-structure.
-.P
-.BR cfgetospeed ()
-returns the output baud rate stored in the
-.I termios
-structure
-pointed to by
-.IR termios_p .
-.P
-.BR cfsetospeed ()
-sets the output baud rate stored in the
-.I termios
-structure
-pointed to by
-.I termios_p
-to
-.IR speed ,
-which must be one of these constants:
-.RS
-.TP
-.B B0
-.TQ
-.B B50
-.TQ
-.B B75
-.TQ
-.B B110
-.TQ
-.B B134
-.TQ
-.B B150
-.TQ
-.B B200
-.TQ
-.B B300
-.TQ
-.B B600
-.TQ
-.B B1200
-.TQ
-.B B1800
-.TQ
-.B B2400
-.TQ
-.B B4800
-.TQ
-.B B9600
-.TQ
-.B B19200
-.TQ
-.B B38400
-.TQ
-.B B57600
-.TQ
-.B B115200
-.TQ
-.B B230400
-.TQ
-.B B460800
-.TQ
-.B B500000
-.TQ
-.B B576000
-.TQ
-.B B921600
-.TQ
-.B B1000000
-.TQ
-.B B1152000
-.TQ
-.B B1500000
-.TQ
-.B B2000000
-.RE
-.P
-These constants are additionally supported on the SPARC architecture:
-.RS
-.TP
-.B B76800
-.TQ
-.B B153600
-.TQ
-.B B307200
-.TQ
-.B B614400
-.RE
-.P
-These constants are additionally supported on non-SPARC architectures:
-.RS
-.TP
-.B B2500000
-.TQ
-.B B3000000
-.TQ
-.B B3500000
-.TQ
-.B B4000000
-.RE
+When using the
+.I baud_t
+.IR * baud()
+functions, the baud rate is specified directly as a numeric value.
+.P
+When using the
+.I speed_t
+.IR * speed()
+functions, the line rate needs to be specified as one of a set of an
+enumerated macros defined in
+.I <termios.h>
+of the form
+.BI B nnn.
 .P
 Due to differences between architectures,
 portable applications should check
@@ -1183,67 +1116,94 @@ if a particular
 .BI B nnn
 constant is defined prior to using it.
 .P
+The actual bit rate corresponding to
+.B B38400
+may be altered with
+.BR setserial (8).
+.P
+The input and output baud rates are stored in the
+.I termios
+structure.
+.P
+.BR cfgetospeed ()
+and
+.BR cfgetobaud ()
+return the output baud rate stored in the
+.I termios
+structure
+pointed to by
+.IR termios_p .
+.P
+.BR cfsetospeed ()
+and
+.BR cfsetobaud ()
+set the output baud rate stored in the
+.I termios
+structure pointed to by
+.IR termios_p .
+.P
 The zero baud rate,
-.BR B0 ,
+.B B0
+for
+.BR cfsetospeed (),
 is used to terminate the connection.
-If
-.B B0
-is specified,
+.P
+If a baud rate of zero is specified,
 the modem control lines shall no longer be asserted.
 Normally,
 this will disconnect the line.
-.B CBAUDEX
-is a mask
-for the speeds beyond those defined in POSIX.1
-(57600 and above).
-Thus,
-.BR B57600 " & " CBAUDEX
-is nonzero.
-.P
-Setting the baud rate to a value other than those defined by
-.BI B nnn
-constants is possible via the
-.B TCSETS2
-ioctl;
-see
-.BR ioctl_tty (2).
 .P
 .BR cfgetispeed ()
-returns the input baud rate stored in the
+and
+.BR cfgetobaud ()
+return the input baud rate stored in the
 .I termios
 structure.
 .P
 .BR cfsetispeed ()
+and
+.BR cfsetibaud ()
 sets the input baud rate stored in the
 .I termios
-structure to
-.IR speed ,
-which must be specified as one of the
-.BI B nnn
-constants listed above for
-.BR cfsetospeed ().
+structure.
+.P
 If the input baud rate is set to the literal constant
 .B 0
 (not the symbolic constant
-.BR B0 ),
-the input baud rate will be
-equal to the output baud rate.
+.B B0
+even when using
+.BR cfsetispeed ())
+the input baud rate
+will be equal to the output baud rate.
 .P
 .BR cfsetspeed ()
 is a 4.4BSD extension.
 It takes the same arguments as
 .BR cfsetispeed (),
 and sets both input and output speed.
+.P
+.BR cfsetbaud ()
+is the equivalent function using the explicitly numeric
+.I baud_t
+interface.
 .SH RETURN VALUE
 .BR cfgetispeed ()
-returns the input baud rate stored in the
+and
+.BR cfgetobaud ()
+return the input baud rate stored in the
 .I termios
-structure.
+structure as a
+.I speed_t
+enumeration value or a numeric value, respectively.
 .P
 .BR cfgetospeed ()
-returns the output baud rate stored in the
+and
+.BR cfgetobaud ()
+return the output baud rate stored in the
 .I termios
-structure.
+structure as a
+.I speed_t
+enumeration value or a numeric value, respectively.
 .P
 All other functions return:
 .TP
@@ -1289,7 +1249,12 @@ T{
 .BR cfgetospeed (),
 .BR cfsetispeed (),
 .BR cfsetospeed (),
-.BR cfsetspeed ()
+.BR cfsetspeed (),
+.BR cfgetibaud (),
+.BR cfgetobaud (),
+.BR cfsetibaud (),
+.BR cfsetobaud (),
+.BR cfsetbaud ()
 T}	Thread safety	MT-Safe
 .TE
 .\" FIXME: The markings are different from that in the glibc manual.
@@ -1328,6 +1293,17 @@ POSIX.1-2008.
 .TQ
 .BR cfsetspeed ()
 BSD.
+.TP
+.BR cfgetibaud ()
+.TQ
+.BR cfgetobaud ()
+.TQ
+.BR cfsetibaud ()
+.TQ
+.BR cfsetobaud ()
+.TQ
+.BR cfsetbaud ()
+GNU.
 .SH HISTORY
 .TP
 .BR tcgetattr ()
@@ -1355,6 +1331,17 @@ POSIX.1-2001.
 .TQ
 .BR cfsetspeed ()
 BSD.
+.TP
+.BR cfgetibaud ()
+.TQ
+.BR cfgetobaud ()
+.TQ
+.BR cfsetibaud ()
+.TQ
+.BR cfsetobaud ()
+.TQ
+.BR cfsetbaud ()
+glibc 2.42.
 .SH NOTES
 UNIX\ V7 and several later systems have a list of baud rates
 where after the values
@@ -1414,6 +1401,7 @@ mask).
 .BR tty (1),
 .BR ioctl_console (2),
 .BR ioctl_tty (2),
+.BR baud_t (3type),
 .BR cc_t (3type),
 .BR speed_t (3type),
 .BR tcflag_t (3type),
diff --git a/man/man3type/baud_t.3type b/man/man3type/baud_t.3type
new file mode 100644
index 000000000000..26cfd017180e
--- /dev/null
+++ b/man/man3type/baud_t.3type
@@ -0,0 +1 @@
+.so man3type/cc_t.3type
diff --git a/man/man3type/cc_t.3type b/man/man3type/cc_t.3type
index 31c2dbcf8dbe..fa16e4cc3915 100644
--- a/man/man3type/cc_t.3type
+++ b/man/man3type/cc_t.3type
@@ -5,7 +5,8 @@
 .\"
 .TH cc_t 3type (date) "Linux man-pages (unreleased)"
 .SH NAME
-cc_t, speed_t, tcflag_t \- terminal special characters, baud rates, modes
+cc_t, baud_t, speed_t, tcflag_t \- terminal special characters, baud
+rates, modes
 .SH LIBRARY
 Standard C library
 .RI ( libc )
@@ -13,6 +14,7 @@ Standard C library
 .nf
 .B #include <termios.h>
 .P
+.BR typedef " /* ... */ " baud_t;
 .BR typedef " /* ... */ " cc_t;
 .BR typedef " /* ... */ " speed_t;
 .BR typedef " /* ... */ " tcflag_t;
@@ -21,14 +23,48 @@ Standard C library
 .I cc_t
 is used for terminal special characters,
 .I speed_t
-for baud rates, and
+for baud rates using
+.BI B nnn
+enumerated constants defined in
+.IR <termios.h> ,
+.I baud_t
+for baud rates explicitly defined as numbers, and
 .I tcflag_t
 for modes.
 .P
-All are unsigned integer types.
+.IR cc_t ,
+.IR speed_t ,
+and
+.I tcflag_t
+are all unsigned integer types.
+.P
+.I baud_t
+is a numeric type.
+.P
+It is currently the same as
+.IR speed_t ,
+but it is not guaranteed to remain so in the future.
 .SH STANDARDS
+.TP
+.I cc_t
+.TQ
+.I speed_t
+.TQ
+.I tcflag_t
 POSIX.1-2024.
+.TP
+.I baud_t
+GNU.
 .SH HISTORY
+.TP
+.I cc_t
+.TQ
+.I speed_t
+.TQ
+.I tcflag_t
 POSIX.1-1988.
+.TP
+.I baud_t
+glibc 2.42.
 .SH SEE ALSO
 .BR termios (3)
-- 
2.54.0