git: a7eac018437e - main - stty(1): provide details about interaction with job control

The branch main has been updated by kib:

URL: https://cgit.FreeBSD.org/src/commit/?id=a7eac018437e592a575f46a59151eedc7a742fa7

commit a7eac018437e592a575f46a59151eedc7a742fa7
Author:     Konstantin Belousov <kib@FreeBSD.org>
AuthorDate: 2022-09-26 21:34:22 +0000
Commit:     Konstantin Belousov <kib@FreeBSD.org>
CommitDate: 2022-10-02 17:29:53 +0000

    stty(1): provide details about interaction with job control
    
    Describe a shell trick to do non-blocking modification of the terminal
    settings, by ignoring job control signals with trap built-in.
    
    PR:     266627
    With input from:        jilles
    Reviewed by:    pauamma
    Sponsored by:   The FreeBSD Foundation
    MFC after:      1 week
    Differential revision:  https://reviews.freebsd.org/D36745
---
 bin/stty/stty.1 | 28 +++++++++++++++++++++++++++-
 1 file changed, 27 insertions(+), 1 deletion(-)

diff --git a/bin/stty/stty.1 b/bin/stty/stty.1
index 67a32c089150..83f5d4da0b82 100644
--- a/bin/stty/stty.1
+++ b/bin/stty/stty.1
@@ -32,7 +32,7 @@
 .\"     @(#)stty.1	8.4 (Berkeley) 4/18/94
 .\" $FreeBSD$
 .\"
-.Dd May 24, 2022
+.Dd September 27, 2022
 .Dt STTY 1
 .Os
 .Sh NAME
@@ -594,6 +594,32 @@ Same as the control character
 Same as the control character
 .Cm reprint .
 .El
+.Sh INTERACTION WITH JOB CONTROL
+Modifications to the terminal settings are treated by job control
+(see
+.Xr termios 4 )
+same as writes.
+When the
+.Nm
+utility is executing in a background process group,
+such attempts result in the kernel sending the
+.Dv SIGTTOU
+signal and stopping the process until its group is returned
+to foreground.
+The non-blocking open of the terminal device with the
+.Fl f
+option to
+.Nm
+does not affect the behavior.
+If it is desirable to modify the settings from the background,
+.Xr sh 1
+users might utilize the following idiom:
+.Bd -literal
+(trap '' TTOU; stty -f /dev/tty sane)
+.Ed
+.Pp
+Note that changing terminal settings for a running foreground
+job that is not prepared for it might cause inconsistencies.
 .Sh EXIT STATUS
 .Ex -std
 .Sh SEE ALSO