stty: support [-]drain setting to control waiting for pending Tx

Instead of commit v8.24-132-g5171bef which only provides
control to disable this behavior (with -I), provide
the symmetrical "[-]drain" special setting.

* src/stty.c (main): Parse the [-]drain setting instead of -I,
and treat like a global option.
(usage): Adjust accordingly.
* tests/misc/stty.sh: Test "drain" with and without options.
* NEWS: Mention the new feature.

NEWS

@@ -47,8 +47,8 @@ GNU coreutils NEWS                                    -*- outline -*-
   is reusable by most shells, with non-printable characters escaped
   with the POSIX proposed $'...' syntax.
 
-  stty now supports the -I, --immediate option, to apply settings
-  without waiting for transmission of any pending output.
+  stty now supports the "[-]drain" setting to control whether to wait
+  for transmission of pending output before application of settings.
 
 ** Changes in behavior
 

doc/coreutils.texi

@@ -13808,18 +13808,6 @@ Print all current settings in a form that can be used as an argument to
 another @command{stty} command to restore the current settings.  This option
 may not be used in combination with any line settings.
 
-@item -I
-@itemx --immediate
-@opindex -I
-@opindex --immediate
-@cindex nonblocking @command{stty} setting
-Apply settings without first waiting for pending output to be transmitted.
-In some cases the system may be in a state where serial transmission
-is not possible.
-For example, if the system has received the @samp{DC3} character
-with @code{ixon} (software flow control) enabled, then @command{stty} would
-block without this option.
-
 @end table
 
 Many settings can be turned off by preceding them with a @samp{-}.
@@ -14439,6 +14427,19 @@ Non-POSIX.
 @opindex columns
 Tell the kernel that the terminal has @var{n} columns.  Non-POSIX.
 
+@item drain
+@opindex drain
+@cindex nonblocking @command{stty} setting
+Apply settings after first waiting for pending output to be transmitted.
+This is enabled by default for GNU @command{stty}.
+It is useful to disable this option
+in cases where the system may be in a state where serial transmission
+is not possible.
+For example, if the system has received the @samp{DC3} character
+with @code{ixon} (software flow control) enabled, then @command{stty} would
+block without @code{-drain} being specified.
+May be negated. Non-POSIX.
+
 @item size
 @opindex size
 @vindex LINES

src/stty.c

@@ -464,12 +464,14 @@ static int max_col;
 /* Current position, to know when to wrap. */
 static int current_col;
 
+/* Default "drain" mode for tcsetattr.  */
+static int tcsetattr_options = TCSADRAIN;
+
 static struct option const longopts[] =
 {
   {"all", no_argument, NULL, 'a'},
   {"save", no_argument, NULL, 'g'},
   {"file", required_argument, NULL, 'F'},
-  {"immediate", no_argument, NULL, 'I'},
   {GETOPT_HELP_OPTION_DECL},
   {GETOPT_VERSION_OPTION_DECL},
   {NULL, 0, NULL, 0}
@@ -523,7 +525,7 @@ usage (int status)
   else
     {
       printf (_("\
-Usage: %s [-F DEVICE | --file=DEVICE] [-I] [SETTING]...\n\
+Usage: %s [-F DEVICE | --file=DEVICE] [SETTING]...\n\
   or:  %s [-F DEVICE | --file=DEVICE] [-a|--all]\n\
   or:  %s [-F DEVICE | --file=DEVICE] [-g|--save]\n\
 "),
@@ -538,9 +540,6 @@ Print or change terminal characteristics.\n\
   -a, --all          print all current settings in human-readable form\n\
   -g, --save         print all current settings in a stty-readable form\n\
   -F, --file=DEVICE  open and use the specified DEVICE instead of stdin\n\
-"), stdout);
-      fputs (_("\
-  -I, --immediate    apply setting without waiting for pending transmission\n\
 "), stdout);
       fputs (HELP_OPTION_DESCRIPTION, stdout);
       fputs (VERSION_OPTION_DESCRIPTION, stdout);
@@ -620,6 +619,9 @@ Special settings:\n\
  * columns N     same as cols N\n\
 "), stdout);
 #endif
+      printf (_("\
+ * [-]drain      wait for transmission before applying settings (%s by default)\
+\n"), tcsetattr_options == TCSADRAIN ? _("on") : _("off"));
       fputs (_("\
    ispeed N      set the input speed to N\n\
 "), stdout);
@@ -1084,7 +1086,6 @@ main (int argc, char **argv)
   bool noargs = true;
   char *file_name = NULL;
   const char *device_name;
-  int tcsetattr_options = TCSADRAIN;
 
   initialize_main (&argc, &argv);
   set_program_name (argv[0]);
@@ -1108,7 +1109,7 @@ main (int argc, char **argv)
      stty parses options, be sure it still works with combinations of
      short and long options, --, POSIXLY_CORRECT, etc.  */
 
-  while ((optc = getopt_long (argc - argi, argv + argi, "-agF:I",
+  while ((optc = getopt_long (argc - argi, argv + argi, "-agF:",
                               longopts, NULL))
          != -1)
     {
@@ -1130,16 +1131,16 @@ main (int argc, char **argv)
           file_name = optarg;
           break;
 
-        case 'I':
-          tcsetattr_options = TCSANOW;
-          break;
-
         case_GETOPT_HELP_CHAR;
 
         case_GETOPT_VERSION_CHAR (PROGRAM_NAME, AUTHORS);
 
         default:
-          noargs = false;
+          /* Consider "drain" as an option rather than a setting,
+             to support: alias stty='stty -drain'  etc.  */
+          if (! STREQ (argv[argi + opti], "-drain")
+              && ! STREQ (argv[argi + opti], "drain"))
+            noargs = false;
 
           /* Skip the argument containing this unrecognized option;
              the 2nd pass will analyze it.  */
@@ -1216,6 +1217,11 @@ main (int argc, char **argv)
           ++arg;
           reversed = true;
         }
+      if (STREQ (arg, "drain"))
+        {
+          tcsetattr_options = reversed ? TCSANOW : TCSADRAIN;
+          continue;
+        }
       for (i = 0; mode_info[i].name != NULL; ++i)
         {
           if (STREQ (arg, mode_info[i].name))

tests/misc/stty.sh

@@ -35,8 +35,12 @@ stty $(cat $saved_state) || fail=1
 # This would segfault prior to sh-utils-2.0j.
 stty erase - || fail=1
 
-# Ensure --immediate mode is supported
-stty -I erase - || fail=1
+# Ensure "immediate" and "wait" mode supported, with and without settings
+for mode in '-drain' 'drain'; do
+  for opt in 'echo' ''; do
+    stty "$mode" $opt || fail=1
+  done
+done
 
 # These would improperly ignore invalid options through coreutils 5.2.1.
 returns_ 1 stty -F 2>/dev/null || fail=1