From b1f6059232ecf7f5083e12047c74f17a28cb93f7 Mon Sep 17 00:00:00 2001
From: Jilles Tjoelker <jilles@FreeBSD.org>
Date: Fri, 14 Nov 2014 17:11:28 +0000
Subject: [PATCH] sh(1): Add/improve information about exit status of commands.

---
 bin/sh/sh.1 | 34 ++++++++++++++++++++++++----------
 1 file changed, 24 insertions(+), 10 deletions(-)

diff --git a/bin/sh/sh.1 b/bin/sh/sh.1
index c770aca07d59..fa6872017ca3 100644
--- a/bin/sh/sh.1
+++ b/bin/sh/sh.1
@@ -32,7 +32,7 @@
 .\"	from: @(#)sh.1	8.6 (Berkeley) 5/4/95
 .\" $FreeBSD$
 .\"
-.Dd November 7, 2014
+.Dd November 14, 2014
 .Dt SH 1
 .Os
 .Sh NAME
@@ -795,10 +795,13 @@ should indicate the various exit codes and what they mean.
 Additionally, the built-in commands return exit codes, as does
 an executed shell function.
 .Pp
-If a command is terminated by a signal, its exit status is 128 plus
-the signal number.
-Signal numbers are defined in the header file
-.In sys/signal.h .
+If a command is terminated by a signal, its exit status is greater than 128.
+The signal name can be found by passing the exit status to
+.Li kill -l .
+.Pp
+If there is no command word,
+the exit status is the exit status of the last command substitution executed,
+or zero if the command does not contain any command substitutions.
 .Ss Complex Commands
 Complex commands are combinations of simple commands
 with control operators or keywords, together creating a larger complex
@@ -818,7 +821,8 @@ function definition
 .El
 .Pp
 Unless otherwise stated, the exit status of a command is
-that of the last simple command executed by the command.
+that of the last simple command executed by the command,
+or zero if no simple command was executed.
 .Ss Pipelines
 A pipeline is a sequence of one or more commands separated
 by the control operator
@@ -902,6 +906,8 @@ The format for running a command in background is:
 If the shell is not interactive, the standard input of an
 asynchronous command is set to
 .Pa /dev/null .
+.Pp
+The exit status is zero.
 .Ss Lists (Generally Speaking)
 A list is a sequence of zero or more commands separated by
 newlines, semicolons, or ampersands,
@@ -940,6 +946,13 @@ command is:
 .Ic fi
 .Ed
 .Pp
+The exit status is that of selected
+.Ic then
+or
+.Ic else
+list,
+or zero if no list was selected.
+.Pp
 The syntax of the
 .Ic while
 command is:
@@ -960,6 +973,9 @@ in place of
 which causes it to
 repeat until the exit status of the first list is zero.
 .Pp
+The exit status is that of the last execution of the second list,
+or zero if it was never executed.
+.Pp
 The syntax of the
 .Ic for
 command is:
@@ -1040,10 +1056,6 @@ continuing until a list terminated with
 or the end of the
 .Ic case
 command.
-The exit code of the
-.Ic case
-command is the exit code of the last command executed in the list or
-zero if no patterns were matched.
 .Ss Grouping Commands Together
 Commands may be grouped by writing either
 .Pp
@@ -1131,6 +1143,8 @@ and the syntax is:
 The
 .Ic local
 command is implemented as a built-in command.
+The exit status is zero
+unless the command is not in a function or a variable name is invalid.
 .Pp
 When a variable is made local, it inherits the initial
 value and exported and readonly flags from the variable