From patchwork Mon Jul 14 21:33:46 2025 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: "H. Peter Anvin" X-Patchwork-Id: 116302 Return-Path: X-Original-To: patchwork@sourceware.org Delivered-To: patchwork@sourceware.org Received: from server2.sourceware.org (localhost [IPv6:::1]) by sourceware.org (Postfix) with ESMTP id E55043858C42 for ; Mon, 14 Jul 2025 21:39:13 +0000 (GMT) DKIM-Filter: OpenDKIM Filter v2.11.0 sourceware.org E55043858C42 Authentication-Results: sourceware.org; dkim=pass (2048-bit key, unprotected) header.d=zytor.com header.i=@zytor.com header.a=rsa-sha256 header.s=2025062101 header.b=KthUrH0H X-Original-To: libc-alpha@sourceware.org Delivered-To: libc-alpha@sourceware.org Received: from mail.zytor.com (terminus.zytor.com [IPv6:2607:7c80:54:3::136]) by sourceware.org (Postfix) with ESMTPS id 8B4C83858D37 for ; Mon, 14 Jul 2025 21:33:58 +0000 (GMT) DMARC-Filter: OpenDMARC Filter v1.4.2 sourceware.org 8B4C83858D37 Authentication-Results: sourceware.org; dmarc=pass (p=none dis=none) header.from=zytor.com Authentication-Results: sourceware.org; spf=pass smtp.mailfrom=zytor.com ARC-Filter: OpenARC Filter v1.0.0 sourceware.org 8B4C83858D37 Authentication-Results: server2.sourceware.org; arc=none smtp.remote-ip=2607:7c80:54:3::136 ARC-Seal: i=1; a=rsa-sha256; d=sourceware.org; s=key; t=1752528838; cv=none; b=a7J76NCTHfJWyqvx/q1v/osNSpFqykEDtzbDtaqMUf52pIMpcTSQbflKCo0kCLYwLh/5wZ8BY/+IOVWfli+Zk0TuM8cnXPpS2n2QiSytKcgTZoPAGkPpZpOzD9MhrcAHgA3kqkWIrBVf52a4QW9m+Z/6GguH7s+BmuNdMmAq0w0= ARC-Message-Signature: i=1; a=rsa-sha256; d=sourceware.org; s=key; t=1752528838; c=relaxed/simple; bh=AHuq4fhqOAILWHdxP6auo6/2rE4yHaLE03t5MVciegk=; h=DKIM-Signature:From:To:Subject:Date:Message-ID:MIME-Version; b=k5A3HElIQ7798fVFhWqTLAdM+rTpWpIzHvcuGqEK8PjSniF6eODFashmxOTGSXR4ciOhcrmNeci2q7YzEQGqttAhlx13psaN4wak1n1424dJdE/ebrZwFXr7AIXU6vn0onvXtXvOZq/uEk4f3HSKLTNy8yoQ4EVVTZUKvPXErEA= ARC-Authentication-Results: i=1; server2.sourceware.org DKIM-Filter: OpenDKIM Filter v2.11.0 sourceware.org 8B4C83858D37 Received: from mail.zytor.com ([IPv6:2601:646:8081:9482:195b:5624:ff69:d0a6]) (authenticated bits=0) by mail.zytor.com (8.18.1/8.17.1) with ESMTPSA id 56ELXtib609674 (version=TLSv1.3 cipher=TLS_AES_256_GCM_SHA384 bits=256 verify=NO); Mon, 14 Jul 2025 14:33:56 -0700 DKIM-Filter: OpenDKIM Filter v2.11.0 mail.zytor.com 56ELXtib609674 DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=zytor.com; s=2025062101; t=1752528836; bh=TDPujQfDstMHs3VBZgsJsyrViO85qs6MK0oKefhfvTo=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From; b=KthUrH0HbClNIvQp/B1v8W6U8ITAuml7jVeiGohDN0h1CWNxJlmeuYhAz0CS3FtKU OnhLjKnRcF/J5WRiCsk6M2VIAlWx4YqdQAU3qPgP25eDEEUvVfBs2Fy5C+pLaaSb7K 1rp+73bY9e85DIfJM+HS7TThu4akh3zMXPrBwsFL4gy2BfUwq5e4VleLfu2t1Vc4yl 8EExOlJEYzIw/whvCzokOsAAXvYRcD1SASelMRy5/FaXUiKZNDroLBbJ16YaNfOot6 Q3zdPfuDS+S+ex+culPvbe3apzjVBrZ+sm6D2YntG81YrRiONIBZi6+aKe8eXOaU1y +gos6MQ+gb8vw== From: "H. Peter Anvin" To: GNU C Library Cc: Collin Funk , Adhemerval Zanella , "H. Peter Anvin" Subject: [PATCH v1 1/3] termios: manual: add @dfn{} to the definitions of DTE and DCE Date: Mon, 14 Jul 2025 14:33:46 -0700 Message-ID: <20250714213348.1079081-2-hpa@zytor.com> X-Mailer: git-send-email 2.50.1 In-Reply-To: <20250714213348.1079081-1-hpa@zytor.com> References: <20250714213348.1079081-1-hpa@zytor.com> MIME-Version: 1.0 X-Spam-Status: No, score=-11.6 required=5.0 tests=BAYES_00, DKIM_SIGNED, DKIM_VALID, DKIM_VALID_AU, DKIM_VALID_EF, GIT_PATCH_0, SPF_HELO_PASS, SPF_PASS, TXREP autolearn=ham autolearn_force=no version=3.4.6 X-Spam-Checker-Version: SpamAssassin 3.4.6 (2021-04-09) on server2.sourceware.org X-BeenThere: libc-alpha@sourceware.org X-Mailman-Version: 2.1.30 Precedence: list List-Id: Libc-alpha mailing list List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: libc-alpha-bounces~patchwork=sourceware.org@sourceware.org The RS232 terms DTE and DCE should have their definitions flagged as such. Signed-off-by: H. Peter Anvin (Intel) --- manual/terminal.texi | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/manual/terminal.texi b/manual/terminal.texi index 805b408fb2cb..aa158537f67a 100644 --- a/manual/terminal.texi +++ b/manual/terminal.texi @@ -50,9 +50,9 @@ speed is device specific. The rest of this section is described in terms of a physical RS232 interface. -The RS232 specification assumes the host (Data Terminal Equipment, DTE) -connects to a modem (Data Communications Equipment, DCE), regardless of -if a physical modem is present or not. +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. 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 From patchwork Mon Jul 14 21:33:47 2025 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: "H. Peter Anvin" X-Patchwork-Id: 116300 Return-Path: X-Original-To: patchwork@sourceware.org Delivered-To: patchwork@sourceware.org Received: from server2.sourceware.org (localhost [IPv6:::1]) by sourceware.org (Postfix) with ESMTP id EF53C3858C48 for ; Mon, 14 Jul 2025 21:35:06 +0000 (GMT) DKIM-Filter: OpenDKIM Filter v2.11.0 sourceware.org EF53C3858C48 Authentication-Results: sourceware.org; dkim=pass (2048-bit key, unprotected) header.d=zytor.com header.i=@zytor.com header.a=rsa-sha256 header.s=2025062101 header.b=lRmuAIGl X-Original-To: libc-alpha@sourceware.org Delivered-To: libc-alpha@sourceware.org Received: from mail.zytor.com (terminus.zytor.com [IPv6:2607:7c80:54:3::136]) by sourceware.org (Postfix) with ESMTPS id 014963858C42 for ; Mon, 14 Jul 2025 21:33:58 +0000 (GMT) DMARC-Filter: OpenDMARC Filter v1.4.2 sourceware.org 014963858C42 Authentication-Results: sourceware.org; dmarc=pass (p=none dis=none) header.from=zytor.com Authentication-Results: sourceware.org; spf=pass smtp.mailfrom=zytor.com ARC-Filter: OpenARC Filter v1.0.0 sourceware.org 014963858C42 Authentication-Results: server2.sourceware.org; arc=none smtp.remote-ip=2607:7c80:54:3::136 ARC-Seal: i=1; a=rsa-sha256; d=sourceware.org; s=key; t=1752528839; cv=none; b=a9GZKwHt6VIgIa/J9OGN7ZJrXGVzEWAWfCKWH4cMuSHyge5QdM5jdiAn5KmrPM6VbJJq6CgLBJFhXfyr8QZ2VDUbEd4WnSBPR9+qheKVT8+C5pau/JgVfHcuDVvkCbQDnndzbrQJCUlPTC9giAJFc6WcWer6qN412vbItYdO2EI= ARC-Message-Signature: i=1; a=rsa-sha256; d=sourceware.org; s=key; t=1752528839; c=relaxed/simple; bh=ssNoiuLob3PRet6bLb63qsQpGAYaCuep0L1Uybo6DFk=; h=DKIM-Signature:From:To:Subject:Date:Message-ID:MIME-Version; b=VWU9AvhSVA/oEfUJ/kXGaH9QyJy3W1I9d9N75UmkMXrnQuFUmaucQ0vW+vNf0+Q8CYff67CMyjpK9E0pU6HAwdb9Q4bWge7pOaFHPWe+1oq5vYk/l9B2KX5+gixHlI3whKPdobCNM66GwoMbQTDw2Smv/RGYT+69VRim6us12Go= ARC-Authentication-Results: i=1; server2.sourceware.org DKIM-Filter: OpenDKIM Filter v2.11.0 sourceware.org 014963858C42 Received: from mail.zytor.com ([IPv6:2601:646:8081:9482:195b:5624:ff69:d0a6]) (authenticated bits=0) by mail.zytor.com (8.18.1/8.17.1) with ESMTPSA id 56ELXtic609674 (version=TLSv1.3 cipher=TLS_AES_256_GCM_SHA384 bits=256 verify=NO); Mon, 14 Jul 2025 14:33:56 -0700 DKIM-Filter: OpenDKIM Filter v2.11.0 mail.zytor.com 56ELXtic609674 DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=zytor.com; s=2025062101; t=1752528836; bh=I+7OmMS3fqI/cjwTeaNNG02JU42KlInCXF/KI6g2xrA=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From; b=lRmuAIGl/bhwUK8YPF+TzX9FZa8O8Npd0MGKKjPNbqrCvi+lgpvb1S+Fzo7iFDl2i oSA9OR/v0BdcKa538KJf8cdpYeog82qceeQeb59ZqJvW2zYks3pzsBcOUrBWhwfvgc rVGjj3KxdNOT6YNX61qTQ5l1KsG22YKVhHxr0n9mWG86x008xRblBsbHdWL48l8DoJ FGs7UGKjrukyHXOgnk8jssyYcawZsIfGLIYUTuIy8t/k+XqFNpaQjNL1SXp6hOZGKG H8PqxsVooN95jYNiBJBcVTFdD5Wao5+IuBB2LIq/Q4+R85SOJMFCv0lxxej+8e64hi xgaCxneEjgDNg== From: "H. Peter Anvin" To: GNU C Library Cc: Collin Funk , Adhemerval Zanella , "H. Peter Anvin" Subject: [PATCH v1 2/3] termios: manual: capitalize and explain BREAK Date: Mon, 14 Jul 2025 14:33:47 -0700 Message-ID: <20250714213348.1079081-3-hpa@zytor.com> X-Mailer: git-send-email 2.50.1 In-Reply-To: <20250714213348.1079081-1-hpa@zytor.com> References: <20250714213348.1079081-1-hpa@zytor.com> MIME-Version: 1.0 X-Spam-Status: No, score=-11.6 required=5.0 tests=BAYES_00, DKIM_SIGNED, DKIM_VALID, DKIM_VALID_AU, DKIM_VALID_EF, GIT_PATCH_0, SPF_HELO_PASS, SPF_PASS, TXREP autolearn=ham autolearn_force=no version=3.4.6 X-Spam-Checker-Version: SpamAssassin 3.4.6 (2021-04-09) on server2.sourceware.org X-BeenThere: libc-alpha@sourceware.org X-Mailman-Version: 2.1.30 Precedence: list List-Id: Libc-alpha mailing list List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: libc-alpha-bounces~patchwork=sourceware.org@sourceware.org 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) --- 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 From patchwork Mon Jul 14 21:33:48 2025 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: "H. Peter Anvin" X-Patchwork-Id: 116301 Return-Path: X-Original-To: patchwork@sourceware.org Delivered-To: patchwork@sourceware.org Received: from server2.sourceware.org (localhost [IPv6:::1]) by sourceware.org (Postfix) with ESMTP id EB63E3858D32 for ; Mon, 14 Jul 2025 21:35:38 +0000 (GMT) DKIM-Filter: OpenDKIM Filter v2.11.0 sourceware.org EB63E3858D32 Authentication-Results: sourceware.org; dkim=pass (2048-bit key, unprotected) header.d=zytor.com header.i=@zytor.com header.a=rsa-sha256 header.s=2025062101 header.b=GC1r5qtG X-Original-To: libc-alpha@sourceware.org Delivered-To: libc-alpha@sourceware.org Received: from mail.zytor.com (terminus.zytor.com [IPv6:2607:7c80:54:3::136]) by sourceware.org (Postfix) with ESMTPS id C5F803858C48 for ; Mon, 14 Jul 2025 21:33:59 +0000 (GMT) DMARC-Filter: OpenDMARC Filter v1.4.2 sourceware.org C5F803858C48 Authentication-Results: sourceware.org; dmarc=pass (p=none dis=none) header.from=zytor.com Authentication-Results: sourceware.org; spf=pass smtp.mailfrom=zytor.com ARC-Filter: OpenARC Filter v1.0.0 sourceware.org C5F803858C48 Authentication-Results: server2.sourceware.org; arc=none smtp.remote-ip=2607:7c80:54:3::136 ARC-Seal: i=1; a=rsa-sha256; d=sourceware.org; s=key; t=1752528839; cv=none; b=HWw2triHhthNUwVloFpcI2f/cT3bZeMTvoGM9O6DUWYXQwlvVwQskSqziYOHpK1SANk1yxhZOXi+T2HYcYDjPK1jPrTI2J33b20grbggefH5/DeDXxQeMQ1o5/9ot0voNoZfEwheJB1M5arAOwo0SOFrWxnv5/j152icumfEwFA= ARC-Message-Signature: i=1; a=rsa-sha256; d=sourceware.org; s=key; t=1752528839; c=relaxed/simple; bh=K3ez0BntbBheh6aE5L5Opb/OaHmqYs7liZ2MgZbrm/U=; h=DKIM-Signature:From:To:Subject:Date:Message-ID:MIME-Version; b=AiLPuoEfjUtZdFCoHrs3DYA9uAFPv88p6WJ8TKZ7QyUnzlBUUifx3C2LWQPM85j4ATaWfQTm2ndJSDdFtOAyQtiBGHX33AVMMywRLtUF0jlgf7YadN2asVBwyXzuGw1dY0RvTgm4cDZgvWG30MR93ahEQL3H3h9efgXJCza8oF8= ARC-Authentication-Results: i=1; server2.sourceware.org DKIM-Filter: OpenDKIM Filter v2.11.0 sourceware.org C5F803858C48 Received: from mail.zytor.com ([IPv6:2601:646:8081:9482:195b:5624:ff69:d0a6]) (authenticated bits=0) by mail.zytor.com (8.18.1/8.17.1) with ESMTPSA id 56ELXtid609674 (version=TLSv1.3 cipher=TLS_AES_256_GCM_SHA384 bits=256 verify=NO); Mon, 14 Jul 2025 14:33:57 -0700 DKIM-Filter: OpenDKIM Filter v2.11.0 mail.zytor.com 56ELXtid609674 DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=zytor.com; s=2025062101; t=1752528837; bh=A7nEc67RvCNVA38JJldldcx1TjUzj15VDvXZHUl9VJw=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From; b=GC1r5qtGTR4sEWwFVHK3h6ubYPSxsBy9C5x8DjKBnZ7WugwR2LzjdCd0EsNAxN30f wUDq0Z4skv1CBfdqzBcl/v8oTGnQnRc8GovboOIXYJJFa0tnfGmLVKbA6KAWhEALAv l+K2LSuzSsr7CuvTGgy7IsIBXmxw57XR3UgJNdkyRs//nbJ0FNtFPciKXIPsG1l38y SIrwbiwUWdrakB+NikePXk37O6atkdVxZRAjRihFHTNCVrxigD8cFbPDAxqh4lZaky nKzNKULV2jeMDYU+Ga7j+ffXCLN4gYRF2NJwUOW76IhtftdsB+XHRXK72lSCtXhcYN i3C1GppckByvg== From: "H. Peter Anvin" To: GNU C Library Cc: Collin Funk , Adhemerval Zanella , "H. Peter Anvin" Subject: [PATCH v1 3/3] termios: manual: disambiguate hardware and software flow control Date: Mon, 14 Jul 2025 14:33:48 -0700 Message-ID: <20250714213348.1079081-4-hpa@zytor.com> X-Mailer: git-send-email 2.50.1 In-Reply-To: <20250714213348.1079081-1-hpa@zytor.com> References: <20250714213348.1079081-1-hpa@zytor.com> MIME-Version: 1.0 X-Spam-Status: No, score=-11.7 required=5.0 tests=BAYES_00, DKIM_SIGNED, DKIM_VALID, DKIM_VALID_AU, DKIM_VALID_EF, GIT_PATCH_0, PROLO_LEO1, SPF_HELO_PASS, SPF_PASS, TXREP autolearn=ham autolearn_force=no version=3.4.6 X-Spam-Checker-Version: SpamAssassin 3.4.6 (2021-04-09) on server2.sourceware.org X-BeenThere: libc-alpha@sourceware.org X-Mailman-Version: 2.1.30 Precedence: list List-Id: Libc-alpha mailing list List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: libc-alpha-bounces~patchwork=sourceware.org@sourceware.org Hardware and software flow control are completely independent, but the manual used the term "flow control" ambiguously. Consistently specify hardware or software flow control. Add some additional index entries as well, as these concepts are partially described across different sections. Signed-off-by: H. Peter Anvin (Intel) --- manual/terminal.texi | 89 ++++++++++++++++++++++++++++++-------------- 1 file changed, 61 insertions(+), 28 deletions(-) diff --git a/manual/terminal.texi b/manual/terminal.texi index 2f7633c0b824..2e0871360859 100644 --- a/manual/terminal.texi +++ b/manual/terminal.texi @@ -50,6 +50,10 @@ speed is device specific. The rest of this section is described in terms of a physical RS232 interface. +@cindex Data Terminal Equipment (DTE) +@cindex DTE +@cindex Data Communications Equipment (DCE) +@cindex DCE 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. @@ -69,6 +73,9 @@ full RS232 and V.24 specifications provide a large number of signals, but the ones that are typically implemented in contemporary hardware and are relevant to the terminal device interface are: +@cindex terminal control and status signals +@cindex control signals, terminal +@cindex status signals, terminal @table @asis @item DTR - Data Terminal Ready (control) @@ -78,13 +85,17 @@ communications session. If deasserted (false), this is a required to, trigger a modem disconnect in response. @cindex modem disconnect request +@cindex hardware terminal flow control +@cindex terminal flow control, hardware +@cindex flow control, terminal +@cindex RTS/CTS flow control @item RTS - Request To Send (control) This signal is also referred to as Ready To Receive (RTR). If asserted, the DTE is ready to accept data. If deasserted, the DCE is requested to hold data temporarily without disconnecting. This is known -as hardware or RTS/CTS @dfn{flow control} and can be handled +as @dfn{RTS/CTS} or @dfn{hardware flow control} and can be handled automatically if the appropriate terminal mode flags are set. @item DSR - Data Set Ready (status) @@ -234,10 +245,10 @@ when you type a very long line. @xref{Canonical or Not}. @cindex terminal output queue The @dfn{terminal output queue} is like the input queue, but for output; it contains characters that have been written by processes, but not yet -transmitted to the terminal. If output flow control is enabled by -setting the @code{IXON} input mode bit (@pxref{Input Modes}), the +transmitted to the terminal. If output software flow control is enabled +by setting the @code{IXON} input mode bit (@pxref{Input Modes}), the terminal driver obeys START and STOP characters sent by the terminal to -stop and restart transmission of output. +stop and restart transmission of output. @xref{Start/Stop Characters}. @dfn{Clearing} the terminal input queue means discarding any characters that have been received but not yet read. Similarly, clearing the @@ -545,9 +556,10 @@ set_istrip (int desc, int value) @node Input Modes @subsection Input Modes -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. +This section describes the terminal attribute flags that control fairly +low-level aspects of input processing: handling of parity errors, BREAK +signals, hardware and software 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 @@ -839,19 +851,21 @@ systems and @gnuhurdsystems{}. @deftypevr Macro tcflag_t CCTS_OFLOW @standards{BSD, termios.h} -If this bit is set, enable flow control of output based on the CTS wire -(RS232 protocol). +If this bit is set, enable hardware flow control of output based +on the CTS status signal. @end deftypevr @deftypevr Macro tcflag_t CRTS_IFLOW @standards{BSD, termios.h} -If this bit is set, enable flow control of input based on the RTS wire -(RS232 protocol). +If this bit is set, enable hardware flow control of input based on the +RTS control signal. @end deftypevr @deftypevr Macro tcflag_t MDMBUF @standards{BSD, termios.h} -If this bit is set, enable carrier-based flow control of output. +If this bit is set, enable hardware flow control of output based on the +Data Carrier Detect (DCD) status signal instead of the CTS status +signal. @end deftypevr @deftypevr Macro tcflag_t CIGNORE @@ -1046,9 +1060,8 @@ bit remains set until reprinting is finished. @xref{Editing Characters}. @node Line Speed @subsection Line Speed -@cindex line speed -@cindex baud rate -@cindex terminal line speed +@cindex line speed, terminal +@cindex baud rate, terminal @cindex terminal line speed The terminal line speed tells the computer how fast to read and write @@ -1689,12 +1702,29 @@ Typically, the DSUSP character is @kbd{C-y}. @end deftypevr @node Start/Stop Characters -@subsubsection Special Characters for Flow Control +@cindex software flow control, terminal +@cindex terminal flow control, software +@cindex flow control, terminal +@cindex XON/XOFF flow control +@subsubsection Special Characters for Software Flow Control These special characters may be active in either canonical or noncanonical input mode, but their use is controlled by the flags @code{IXON} and @code{IXOFF} (@pxref{Input Modes}). +This is referred to as @dfn{XON/XOFF} or @dfn{software flow control}, +and is independent of hardware (RTS/CTS) flow control; it is possible to +use either one, both at the same time, or neither. + +Whereas hardware flow control is fully transparent, software flow +control requires that the START and STOP characters are dedicated to +this function and cannot be used for other purposes. This may interfere +with applications that use these characters, or require full binary +transparency. + +The terms @dfn{XON} and @dfn{XOFF} are often used to describe the +@emph{default} values of the START and STOP characters. + @deftypevr Macro int VSTART @standards{POSIX.1, termios.h} @cindex START character @@ -1710,9 +1740,9 @@ output; the resuming character is not discarded unless it is the START character. If @code{IXOFF} is set, the system may also transmit START characters to the terminal. -The usual value for the START character is @kbd{C-q}. You may not be -able to change this value---the hardware may insist on using @kbd{C-q} -regardless of what you specify. +The usual value for the START character is @kbd{C-q} (@code{0x11}). +You may not be able to change this value---the hardware may insist on +using @kbd{C-q} regardless of what you specify. @end deftypevr @deftypevr Macro int VSTOP @@ -1728,9 +1758,9 @@ output to be suspended; the STOP character itself is discarded. If @code{IXOFF} is set, the system may also transmit STOP characters to the terminal, to prevent the input queue from overflowing. -The usual value for the STOP character is @kbd{C-s}. You may not be -able to change this value---the hardware may insist on using @kbd{C-s} -regardless of what you specify. +The usual value for the STOP character is @kbd{C-s} (@code{0x13}). +You may not be able to change this value---the hardware may insist on +using @kbd{C-s} regardless of what you specify. @end deftypevr @node Other Special @@ -2101,8 +2131,10 @@ output would be confusing. Unfortunately, the name @code{tcflush} comes from POSIX and we cannot change it. @end deftypefun +@cindex software flow control, terminal +@cindex terminal flow control, software @cindex flow control, terminal -@cindex terminal flow control +@cindex XON/XOFF flow control @deftypefun int tcflow (int @var{filedes}, int @var{action}) @standards{POSIX.1, termios.h} @safety{@prelim{}@mtunsafe{@mtasurace{:tcattr(filedes)/bsd}}@asunsafe{}@acsafe{}} @@ -2111,17 +2143,18 @@ from POSIX and we cannot change it. @c the c_cc character corresponding to the action; there's a window for @c another thread to change the xon/xoff characters. The @code{tcflow} function is used to perform operations relating to -XON/XOFF flow control on the terminal file specified by @var{filedes}. +software flow control on the terminal file specified by +@var{filedes}. The @var{action} argument specifies what operation to perform, and can be one of the following values: @vtable @code @item TCOOFF -Suspend transmission of output. +Suspend transmission of output, as if a STOP character had been received. @item TCOON -Restart transmission of output. +Restart transmission of output, as if a START character had been received. @item TCIOFF Transmit a STOP character. @@ -2130,8 +2163,8 @@ Transmit a STOP character. Transmit a START character. @end vtable -For more information about the STOP and START characters, see @ref{Special -Characters}. +For more information about the STOP and START characters, see +@ref{Start/Stop Characters}. 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