[groff] 11/20: [groff]: Revise exit status computation.

[G. Branden Robinson]

gbranden pushed a commit to branch master
in repository groff.

commit a27a37d331d407d1bff52780b2228cefba22873b
Author: G. Branden Robinson <g.branden.robinson@gmail.com>
AuthorDate: Fri Oct 18 18:49:39 2024 -0500

    [groff]: Revise exit status computation.
    
    * src/roff/groff/groff.cpp (main): Avoid collision between groff's "own"
      exit status bits and those allocated to reporting pipeline status.
      Left-shift return value of `run_command()` by two binary places.
    
    * src/roff/groff/groff.1.man (Exit status): Document this.
    
    * src/roff/groff/tests/ab-request-works.sh: Update test expectations.
    
    * NEWS: Add item.
---
 ChangeLog                                | 15 +++++++++++++++
 NEWS                                     |  9 +++++++++
 src/roff/groff/groff.1.man               | 29 ++++++++++++++++++-----------
 src/roff/groff/groff.cpp                 |  5 ++++-
 src/roff/groff/tests/ab-request-works.sh |  5 +++--
 5 files changed, 49 insertions(+), 14 deletions(-)

diff --git a/ChangeLog b/ChangeLog
index 47127a07e..371fc5f1b 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,3 +1,18 @@
+2024-10-18  G. Branden Robinson <g.branden.robinson@gmail.com>
+
+       [groff]: Revise exit status computation.
+
+       * src/roff/groff/groff.cpp (main): Avoid collision between
+       groff's "own" exit status bits and those allocated to reporting
+       pipeline status.  Left-shift return value of `run_command()` by
+       two binary places.
+       * src/roff/groff/groff.1.man (Exit status): Document this.
+
+       * src/roff/groff/tests/ab-request-works.sh: Update test
+       expectations.
+
+       * NEWS: Add item.
+
 2024-10-18  G. Branden Robinson <g.branden.robinson@gmail.com>
 
        * src/devices/grodvi/dvi.cpp (main):
diff --git a/NEWS b/NEWS
index 7b42c12a8..52c259b5a 100644
--- a/NEWS
+++ b/NEWS
@@ -160,6 +160,15 @@ eqn
 
 *  The new "reset" primitive restores a named parameter to its default.
 
+groff
+-----
+
+*  The groff command now encodes the fate of failing processes in the
+   pipeline it constructs and runs so that this information cannot be
+   confused with groff's own error conditions (such as a usage error,
+   which now produces an exit status of 2).  See the section "Exit
+   status" of groff(1) for details.
+
 nroff
 -----
 
diff --git a/src/roff/groff/groff.1.man b/src/roff/groff/groff.1.man
index b64b69c9d..d00b20df3 100644
--- a/src/roff/groff/groff.1.man
+++ b/src/roff/groff/groff.1.man
@@ -1696,12 +1696,18 @@ the databases.
 .\" ====================================================================
 .
 .I groff
-exits with a failure status if there was a problem parsing its arguments
-and a successful status if either of the options
+exits successfully (with
+.RB status\~ 0 )
+if either of the options
 .B \-h
 or
 .B \-\-help
-was specified.
+is specified,
+.RB status\~ 2
+if the program cannot interpret its command-line arguments,
+and
+.RB status\~ 1
+if it encounters an error during operation.
 .
 Otherwise,
 .I groff
@@ -1713,23 +1719,24 @@ does likewise.
 If not,
 .IR groff 's
 exit status encodes a summary of problems encountered,
-setting bit\~0 if a command exited with a failure status,
-bit\~1 if a command was terminated with a signal,
-and bit\~2 if a command could not be executed.
+setting bit\~2 if a command exited with a failure status,
+bit\~3 if a command was terminated with a signal,
+and bit\~4 if a command could not be executed.
 .
 (Thus,
-if all three misfortunes befell one's pipeline,
+if all three misfortunes befall one's pipeline,
 .I groff
-would exit with status 2\[ha]0 + 2\[ha]1 + 2\[ha]2 = 1+2+4 = 7.)
+exits with status 2\[ha]2 + 2\[ha]3 + 2\[ha]4 = 4+8+16 = 28.)
 .
 To troubleshoot pipeline problems,
-you may wish to re-run the
+re-run the
 .I groff
 command with the
 .B \-V
 option and break the reported pipeline down into separate stages,
-inspecting the exit status of and diagnostic messages emitted by each
-command.
+inspecting the exit status of,
+and diagnostic messages emitted by,
+each command.
 .
 .
 .\" ====================================================================
diff --git a/src/roff/groff/groff.cpp b/src/roff/groff/groff.cpp
index cd4ca58ea..80a2cd06c 100644
--- a/src/roff/groff/groff.cpp
+++ b/src/roff/groff/groff.cpp
@@ -534,7 +534,10 @@ int main(int argc, char **argv)
     print_commands(Vflag == 1 ? stdout : stderr);
   if (Vflag == 1)
     xexit(EXIT_SUCCESS);
-  xexit(run_commands(want_version_info));
+  // We need the lower two bits of the exit status for ourselves.
+  int status = run_commands(want_version_info) << 2;
+  assert(status < 65 || 0 == "run_commands() returned too many bits");
+  xexit(status);
 }
 
 const char *xbasename(const char *s)
diff --git a/src/roff/groff/tests/ab-request-works.sh 
b/src/roff/groff/tests/ab-request-works.sh
index 9008e55bf..68fb9e446 100755
--- a/src/roff/groff/tests/ab-request-works.sh
+++ b/src/roff/groff/tests/ab-request-works.sh
@@ -1,6 +1,6 @@
 #!/bin/sh
 #
-# Copyright (C) 2021-2022 Free Software Foundation, Inc.
+# Copyright (C) 2021-2024 Free Software Foundation, Inc.
 #
 # This file is part of groff.
 #
@@ -32,7 +32,8 @@ for d in ascii dvi html latin1 lbp lj4 pdf ps utf8
 do
   echo "verifying exit status of .ab request using $d device" >&2
   printf '.ab\n' | "$groff" -Z -T$d
-  test $? -eq 1 || exit 1
+  # 4 = (1 << 2)
+  test $? -eq 4 || exit 1
 done
 
 echo "verifying empty output of .ab request with no arguments" >&2