docs/70985: [patch] sh(1): incomplete documentation of 'trap' builtin

[dada at sbox.tugraz.at]

>Number:         70985
>Category:       docs
>Synopsis:       [patch] sh(1): incomplete documentation of 'trap' builtin
>Confidential:   no
>Severity:       non-critical
>Priority:       low
>Responsible:    freebsd-doc
>State:          open
>Quarter:        
>Keywords:       
>Date-Required:
>Class:          doc-bug
>Submitter-Id:   current-users
>Arrival-Date:   Thu Aug 26 11:20:25 GMT 2004
>Closed-Date:
>Last-Modified:
>Originator:     Martin Kammerhofer
>Release:        FreeBSD 4.10-RELEASE-p2 i386
>Organization:
Graz Uni
>Environment:
System: FreeBSD Martin.liebt.Susi 4.10-RELEASE-p2 FreeBSD 4.10-RELEASE-p2 #1: Mon Aug 16 14:26:52 CEST 2004 toor at Martin.liebt.Susi:/mnt/redhat/freebsd/usr/src/sys/compile/GEIDORF4 i386
>Description:
The sh(1) manpage describes the trap builtin as follows:

    The action may be null or omitted; the former causes the specified
    signal to be ignored and the latter causes the default action to
    be taken.

Compare this to a quote from SUSv3:

    If action is '-' , the shell shall reset each condition to the
    default value. If action is null ( "" ), the shell shall ignore
    each specified condition if it arises.

There is a slight difference here. Our sh(1) uses a nonexistent action
to signify the default action while the standard calls for a
dash. Omitting the action argument causes incompatibility with other
shells, e.g. ksh93 from the ports collection.

(Our shell does already handle the '-' action correctly. But is
undocumented.)

Invocation as 'trap -l' to list available signal names is not
documented either.
>How-To-Repeat:
man sh
>Fix:
Emphasize the POSIX way of specifying the default signal action.
Document "trap -l".

Index: sh.1
===================================================================
RCS file: /home/ncvs/src/bin/sh/sh.1,v
retrieving revision 1.92
diff -u -t -r1.92 sh.1
--- sh.1	3 Jul 2004 02:03:44 -0000	1.92
+++ sh.1	26 Aug 2004 09:49:04 -0000
@@ -1880,6 +1880,7 @@
 decreasing the value of $# by one.
 If there are zero positional parameters, shifting does not do anything.
 .It Ic trap Oo Ar action Oc Ar signal ...
+.It Ic trap Fl l
 Cause the shell to parse and execute
 .Ar action
 when any specified
@@ -1891,14 +1892,25 @@
 may be used to specify an action that is performed when the shell terminates.
 The
 .Ar action
-may be null or omitted;
+may be null or a dash
+.Pq Ar -
+;
 the former causes the specified signal to be ignored
 and the latter causes the default action to be taken.
+Omitting the
+.Ar action
+is another way to request the default action.
 When the shell forks off a subshell,
 it resets trapped (but not ignored) signals to the default action.
 The
 .Ic trap
 command has no effect on signals that were ignored on entry to the shell.
+.Pp
+Option
+.Fl l
+causes the
+.Ic trap
+command to display a list of valid signal names.
 .It Ic type Op Ar name ...
 Interpret each
 .Ar name

--=_1p8ho7sy71us--

>Release-Note:
>Audit-Trail:
>Unformatted:
 This message is in MIME format.
 
 --=_1p8ho7sy71us
 Content-Type: text/plain; charset=ISO-8859-1
 Content-Disposition: inline
 Content-Transfer-Encoding: 7bit
 
 
 --=_1p8ho7sy71us
 Content-Type: text/plain; charset=UTF-8; name="sh.pr"
 Content-Disposition: inline; filename="sh.pr"
 Content-Transfer-Encoding: 7bit