[PATCH 1/1] 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 as numbers rather than strange enumeration constants. Add them
to the man pages.

This also removes the specific list of Bxxx constants, as they no
longer match the list of constants supported by glibc, which is now an
open set anyway.

[ I was the developer of that interface. ]

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

diff --git a/man/man3/termios.3 b/man/man3/termios.3
index 0942cca8084e..7aa29b39ea73 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,6 +323,25 @@ flag constants:
 .B _BSD_SOURCE
 or
 .BR _SVID_SOURCE ]
+.IP
+This bitmask should only be used when invoking the kernel
+.BR ioctl ()
+interface directly.
+.P
+The
+.BR cfgetospeed (),
+.BR cfgetobaud (),
+.BR cfsetospeed ()
+and
+.BR cfsetobaud ()
+functions should instead.
+.P
+Some systems use bits selected by
+.B CBAUD
+in
+.IR c_cflag ,
+other systems use separate fields, Linux uses
+.IR both .
 .TP
 .B CBAUDEX
 (not in POSIX) Extra baud speed mask (1 bit), included in
@@ -313,22 +350,6 @@ or
 .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 ()
-and
-.BR cfsetispeed ()
-for getting at it.
-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 .)
 .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)).
+The
+.BR cfgetispeed (),
+.BR cfgetibaud (),
+.BR cfsetispeed ()
 and
-.BR TCSET *
-ioctls;
-see
-.BR ioctl_tty (2))
+.BR cfsetibaud ()
+functions should instead.
 .TP
 .B CMSPAR
 (not in POSIX)
@@ -1068,182 +1093,122 @@ until
 .BR tcsetattr ()
 is successfully called.
 .P
-Setting the speed to
-.B B0
-instructs the modem to "hang up".
+Setting the output speed to zero instructs the modem to "hang up".
+.P
+If a certain device does not support different input and output
+speeds, the output speed takes precedence if the user tries to set
+them to different values.
+.P
+When using the
+.I baud_t
+.BR -baud ()
+functions, the baud rate is specified directly as a numeric value.
+.P
+When using the
+.I speed_t
+.BR -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
+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).
+.BR setserial (8);
+doing so is however discouraged as it may break other applications
+later trying to use the same serial port.
 .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
+and
+.BR cfgetobaud ()
+return 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
+and
+.BR cfsetobaud ()
+set 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
-.P
-Due to differences between architectures,
-portable applications should check
-if a particular
-.BI B nnn
-constant is defined prior to using it.
+structure pointed to by
+.IR termios_p .
 .P
 The zero baud rate,
-.BR B0 ,
-is used to terminate the connection.
-If
 .B B0
-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.
+for
+.BR cfsetospeed (),
+is used to terminate the connection.
 .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).
+If a baud rate of zero is specified,
+the modem control lines shall no longer be asserted.
+Normally, this will disconnect the line.
 .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
+POSIX.1-2024 considers this functionality deprecated.
 .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 +1254,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 +1298,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 +1336,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 +1406,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