[PATCH 1/2] docs: korn shells can have $? > 256 for signal-terminated children

[Stefano Lattarini]

Some Korn shells, when a child process die due to signal number
n, can leave in $? an exit status of 256+n, instead of the "more
standard" 128+n.  See also Austin Group issue 0000051:
  <http://www.austingroupbugs.net/view.php?id=51>

* doc/autoconf.texi (Signal handling): Document the described Korn
Shell behaviour, and some of its possible shortcomings.

Suggestion by Eric Blake.
---
 ChangeLog         |   14 +++++++----
 doc/autoconf.texi |   61 +++++++++++++++++++++++++++++++++++++++++++++++++++++
 2 files changed, 70 insertions(+), 5 deletions(-)

diff --git a/ChangeLog b/ChangeLog
index be019f5..cb6416c 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,9 +1,13 @@
-2011-09-26  Eric Blake  <address@hidden>
-
-       docs: relax documentation license by dropping cover text
-       * doc/autoconf.texi (copying): Drop front- and back-cover texts.
-       * NEWS: Document this.
-       Reported by Brian Gough.
+2011-09-29  Stefano Lattarini  <address@hidden>
+
+       docs: korn shells can have $? > 256 for signal-terminated children
+       Some Korn shells, when a child process die due to signal number
+       n, can leave in $? an exit status of 256+n, instead of the "more
+       standard" 128+n.  See also Austin Group issue 0000051:
+         <http://www.austingroupbugs.net/view.php?id=51>
+       * doc/autoconf.texi (Signal handling): Document the described Korn
+       Shell behaviour, and some of its possible shortcomings.
+       Suggestion by Eric Blake.
 
 2011-09-13  Stefano Lattarini  <address@hidden>
 
diff --git a/doc/autoconf.texi b/doc/autoconf.texi
index 91bb50a..2f74072 100644
--- a/doc/autoconf.texi
+++ b/doc/autoconf.texi
@@ -15610,6 +15610,67 @@ and @code{/usr/xpg4/bin/sh} will proceed to exit with 
status 130 (i.e.,
 128 + 2). In any case, if there is an active trap associated with
 @code{SIGINT}, those shells will correctly execute it.
 
+Some Korn shells, when a child process die due receiving a signal with
+signal number @var{n}, can leave in @samp{$?} an exit status of
address@hidden instead of the ``more standard'' address@hidden  Observe the
+difference between AT&T @code{ksh93} (2011) and @code{bash} 4.1.5 on
+Debian:
+
address@hidden
+$ @kbd{/bin/ksh -c 'sh -c "kill -1 \$\$"; echo $?'}
+/bin/ksh: line 1: 7837: Hangup
+257
+$ @kbd{/bin/bash -c 'sh -c "kill -1 \$\$"; echo $?'}
+/bin/bash: line 1:  7861 Hangup        (sh -c "kill -1 \$\$")
+129
address@hidden example
+
address@hidden
+This @command{ksh} behaviour is allowed by POSIX, if implemented with
+due care; see this @uref{http://www.austingroupbugs.net/view.php?id=51,
+Austin Group discussion} for more background.  However, if it is not
+implemented with proper care, such a behaviour might can cause problems
+some corner cases.  To see why, assume we have a ``wrapper'' script
+like this:
+
address@hidden
+#!/bin/sh
+# Ignore some signals in the shell only, not in its child processes.
+trap : 1 2 13 15
+wrapped_command "$@@"
+ret=$?
+other_command
+exit $ret
address@hidden example
+
address@hidden
+If @command{wrapped_command} is interrupted by a @code{SIGHUP} (which
+has signal number 1), @code{ret} will be set to 257.  Unless the
address@hidden shell builtin is smart enough to understand that such
+a value can only have been originated from a signal, and adjust the
+final wait status of the shell appropriately, the value 257 will just
+get truncated to 1 by the closing @code{exit} call, so that a caller
+of the script will have no way to determine that termination by a
+signal was involved.  Observe the different behaviour of AT&T
address@hidden (2011) and @code{bash} 4.1.5 on Debian:
+
address@hidden
+$ @kbd{cat > foo.sh}
+#!/bin/sh
+sh -c 'kill -1 $$'
+ret=$?
+echo $ret
+exit $ret
+$ @kbd{/bin/ksh foo.sh; echo $?}
+foo.sh: line 2: 12479: Hangup
+257
+1
+$ @kbd{/bin/bash foo.sh; echo $?}
+foo.sh: line 2: 12487 Hangup        (sh -c 'kill -1 $$')
+129
+129
address@hidden example
+
 @node File System Conventions
 @section File System Conventions
 @cindex File system conventions
-- 
1.7.2.3