[PATCH v1 2/3] termios: manual: capitalize and explain BREAK

[H. Peter Anvin]

BREAK is typically capitalized in the context of RS232, so be
consistent and capitalize it everywhere (except of course in symbol
names.)

Explain what BREAK actually is, from an abstract point of view: an
additional non-character symbol.

The statement that BREAK has no effect on non-asynchronous connections
is not necessarily true.  For a USB ACM device, for example, it is
transmitted as either one or two command packets.

Explain that despite the name, BREAK doesn't correspond to any
specific action; someone might draw the wrong conclusion from the name
thinking it is expected to have the same effect as VEOF or VINTR.

Document the meaning of the tcsendbrk() call.  It currently seems to
be implemented only on Linux (not even Hurd?) but since it is
converted from a millisecond value to the Linux ioctl decisecond
number, I'm assuming that is intended to be OS-independent.

Signed-off-by: H. Peter Anvin (Intel) <hpa@zytor.com>
---
 manual/terminal.texi | 56 +++++++++++++++++++++++++++++---------------
 1 file changed, 37 insertions(+), 19 deletions(-)

diff --git a/manual/terminal.texi b/manual/terminal.texi
index aa158537f67a..2f7633c0b824 100644
--- a/manual/terminal.texi
+++ b/manual/terminal.texi
@@ -22,7 +22,7 @@ descriptor is and how to open a file descriptor for a terminal device.
 			         details of terminal I/O: echoing,
                                  signals, editing.  Posix.
 * BSD Terminal Modes::          BSD compatible terminal mode setting
-* Line Control::                Sending break sequences, clearing
+* Line Control::                Sending BREAK sequences, clearing
                                  terminal buffers @dots{}
 * Noncanon Example::            How to read single characters without echo.
 * getpass::                     Prompting the user for a passphrase.
@@ -54,6 +54,15 @@ The RS232 specification assumes the host (@dfn{Data Terminal Equipment},
 @dfn{DTE}) connects to a modem (@dfn{Data Communications Equipment},
 @dfn{DCE}), regardless of if a physical modem is present or not.
 
+The serial line carries data symbols (``characters'') 5-8 bits long,
+plus asynchronous framing bits (one start bit, and one or more stop
+bits) and optional parity bits for error detection.  This is controlled
+by setting the appropriate terminal interface flags.  The by far most
+common setting for modern equipment is 8 data bits, no parity bit, and
+one stop bit.  In addition, a special non-character symbol called BREAK
+can be carried by sending an all-zero symbol, too long to be a valid
+zero data symbol.  The meaning of BREAK is application-dependent.
+
 In addition to the serial data, the DTE provides a set of control
 signals to the DCE, and the DCE a set of status signals to the DTE.  The
 full RS232 and V.24 specifications provide a large number of signals,
@@ -538,7 +547,7 @@ set_istrip (int desc, int value)
 
 This section describes the terminal attribute flags that control
 fairly low-level aspects of input processing: handling of parity errors,
-break signals, flow control, and @key{RET} and @key{LFD} characters.
+BREAK signals, flow control, and @key{RET} and @key{LFD} characters.
 
 All of these flags are bits in the @code{c_iflag} member of the
 @code{struct termios} structure.  The member is an integer, and you
@@ -596,21 +605,21 @@ otherwise, all eight bits are available for programs to read.
 
 @deftypevr Macro tcflag_t IGNBRK
 @standards{POSIX.1, termios.h}
-If this bit is set, break conditions are ignored.
+If this bit is set, BREAK conditions are ignored.
 
-@cindex break condition, detecting
-A @dfn{break condition} is defined in the context of asynchronous
+@cindex BREAK condition, detecting
+A @dfn{BREAK condition} is defined in the context of asynchronous
 serial data transmission as a series of zero-value bits longer than a
 single byte.
 @end deftypevr
 
 @deftypevr Macro tcflag_t BRKINT
 @standards{POSIX.1, termios.h}
-If this bit is set and @code{IGNBRK} is not set, a break condition
+If this bit is set and @code{IGNBRK} is not set, a BREAK condition
 clears the terminal input and output queues and raises a @code{SIGINT}
 signal for the foreground process group associated with the terminal.
 
-If neither @code{BRKINT} nor @code{IGNBRK} are set, a break condition is
+If neither @code{BRKINT} nor @code{IGNBRK} are set, a BREAK condition is
 passed to the application as a single @code{'\0'} character if
 @code{PARMRK} is not set, or otherwise as a three-character sequence
 @code{'\377'}, @code{'\0'}, @code{'\0'}.
@@ -1968,23 +1977,28 @@ sent a @code{SIGTTOU} signal.  The exception is if the calling process
 itself is ignoring or blocking @code{SIGTTOU} signals, in which case the
 operation is performed and no signal is sent.  @xref{Job Control}.
 
-@cindex break condition, generating
+@cindex BREAK condition, generating
 @deftypefun int tcsendbreak (int @var{filedes}, int @var{duration})
 @standards{POSIX.1, termios.h}
 @safety{@prelim{}@mtunsafe{@mtasurace{:tcattr(filedes)/bsd}}@asunsafe{}@acunsafe{@acucorrupt{/bsd}}}
 @c On Linux, this calls just one out of two ioctls; on BSD, it's two
 @c ioctls with a select (for the delay only) in between, the first
-@c setting and the latter clearing the break status.  The BSD
-@c implementation may leave the break enabled if cancelled, and threads
-@c and signals may cause the break to be interrupted before requested.
-This function generates a break condition by transmitting a stream of
-zero bits on the terminal associated with the file descriptor
-@var{filedes}.  The duration of the break is controlled by the
-@var{duration} argument.  If zero, the duration is between 0.25 and 0.5
-seconds.  The meaning of a nonzero value depends on the operating system.
-
-This function does nothing if the terminal is not an asynchronous serial
-data port.
+@c setting and the latter clearing the BREAK status.  The BSD
+@c implementation may leave the BREAK enabled if cancelled, and threads
+@c and signals may cause the BREAK to be interrupted before requested.
+This function generates a BREAK condition on the terminal associated
+with the file descriptor @var{filedes}.
+
+For an asynchronous serial port, BREAK is signalled by transmitting an
+overlong stream of zero bits.  The duration of the BREAK is controlled
+by the @var{duration} argument.  If zero, the duration is between 0.25
+and 0.5 seconds.  The meaning of a nonzero value is operating system
+dependent; for @theglibc{} this is the minimum requested delay in
+milliseconds if the operating system supports such a request.
+
+If the terminal is not an asynchronous serial data port the meaning of
+sending BREAK and the duration argument is device and operating system
+dependent, and may have no effect at all.
 
 The return value is normally zero.  In the event of an error, a value
 of @math{-1} is returned.  The following @code{errno} error conditions
@@ -1994,6 +2008,10 @@ are defined for this function:
 @item EBADF
 The @var{filedes} is not a valid file descriptor.
 
+@item EINVAL
+The specified @var{duration} value is not supported for this operating
+system/device combination.
+
 @item ENOTTY
 The @var{filedes} is not associated with a terminal device.
 @end table
-- 
2.50.1