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