From dada@sbox.tugraz.at  Thu Aug 26 11:18:39 2004
Return-Path: <dada@sbox.tugraz.at>
Received: from mx1.FreeBSD.org (mx1.freebsd.org [216.136.204.125])
	by hub.freebsd.org (Postfix) with ESMTP id 2506216A4CE
	for <freebsd-gnats-submit@freebsd.org>; Thu, 26 Aug 2004 11:18:39 +0000 (GMT)
Received: from mailrelay02.tugraz.at (mailrelay.tu-graz.ac.at [129.27.3.7])
	by mx1.FreeBSD.org (Postfix) with ESMTP id 2C81943D67
	for <freebsd-gnats-submit@freebsd.org>; Thu, 26 Aug 2004 11:18:38 +0000 (GMT)
	(envelope-from dada@sbox.tugraz.at)
Received: from webmail.tugraz.at (webmail02.tu-graz.ac.at [129.27.3.144])
	by mailrelay02.tugraz.at (8.13.1/8.13.1) with ESMTP id i7QBIQ56007475
	for <freebsd-gnats-submit@freebsd.org>; Thu, 26 Aug 2004 13:18:26 +0200 (CEST)
Received: from ARP408.kfunigraz.ac.at (ARP408.kfunigraz.ac.at
	[143.50.129.133]) by webmail.tugraz.at (Horde) with HTTP for <dada@sbox>;
	Thu, 26 Aug 2004 13:18:27 +0200
Message-Id: <20040826131827.k8s0cwko4c0wwkgw@webmail.tugraz.at>
Date: Thu, 26 Aug 2004 13:18:27 +0200
From: dada@sbox.tugraz.at
To: FreeBSD problem reports <freebsd-gnats-submit@freebsd.org>
Subject: [patch] sh(1): incomplete documentation of 'trap' builtin

>Number:         70985
>Category:       docs
>Synopsis:       [patch] sh(1): incomplete documentation of 'trap' builtin
>Confidential:   no
>Severity:       non-critical
>Priority:       low
>Responsible:    stefanf
>State:          closed
>Quarter:        
>Keywords:       
>Date-Required:  
>Class:          doc-bug
>Submitter-Id:   current-users
>Arrival-Date:   Thu Aug 26 11:20:25 GMT 2004
>Closed-Date:    Mon Dec 26 18:21:12 GMT 2005
>Last-Modified:  Mon Dec 26 18:21:12 GMT 2005
>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@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:
Responsible-Changed-From-To: freebsd-doc->freebsd-standards 
Responsible-Changed-By: simon 
Responsible-Changed-When: Thu Aug 26 12:50:29 GMT 2004 
Responsible-Changed-Why:  
Over to the standards people so they can decide if we want to document 
that our shell is not fully standard complaint (according the to the 
PR - I haven't checked further) or if our sh should rather be changed. 
If the standards people think it should be documented, as described in 
the PR, feel free to throw this PR back to freebsd-doc. 

http://www.freebsd.org/cgi/query-pr.cgi?pr=70985 
Responsible-Changed-From-To: freebsd-standards->stefanf 
Responsible-Changed-By: stefanf 
Responsible-Changed-When: Thu Dec 8 21:19:47 GMT 2005 
Responsible-Changed-Why:  
Over to me. 

http://www.freebsd.org/cgi/query-pr.cgi?pr=70985 
State-Changed-From-To: open->patched 
State-Changed-By: stefanf 
State-Changed-When: Thu Dec 8 21:20:07 GMT 2005 
State-Changed-Why:  
Committed to current.  Thanks! 

http://www.freebsd.org/cgi/query-pr.cgi?pr=70985 
State-Changed-From-To: patched->closed 
State-Changed-By: stefanf 
State-Changed-When: Mon Dec 26 18:21:06 UTC 2005 
State-Changed-Why:  
Also fixed in RELENG_{5,6}. 

http://www.freebsd.org/cgi/query-pr.cgi?pr=70985 
>Unformatted:
