From fenner@parc.xerox.com  Thu Mar 20 15:00:25 1997
Received: from alpha.xerox.com (alpha.Xerox.COM [13.1.64.93])
          by freefall.freebsd.org (8.8.5/8.8.5) with SMTP id PAA04218
          for <FreeBSD-gnats-submit@freebsd.org>; Thu, 20 Mar 1997 15:00:22 -0800 (PST)
Received: from fenestro.parc.xerox.com ([13.0.208.199]) by alpha.xerox.com with SMTP id <15717(3)>; Thu, 20 Mar 1997 14:59:47 PST
Received: (from fenner@localhost)
          by fenestro.parc.xerox.com (8.8.4/8.8.4)
	  id OAA01991; Thu, 20 Mar 1997 14:59:48 -0800 (PST)
Message-Id: <199703202259.OAA01991@fenestro.parc.xerox.com>
Date: Thu, 20 Mar 1997 14:59:48 PST
From: Bill Fenner <fenner@parc.xerox.com>
Reply-To: fenner@parc.xerox.com
To: FreeBSD-gnats-submit@freebsd.org
Subject: Ambiguous wording in sigaction.2
X-Send-Pr-Version: 3.2

>Number:         3047
>Category:       docs
>Synopsis:       Ambiguous wording in sigaction.2
>Confidential:   no
>Severity:       non-critical
>Priority:       low
>Responsible:    freebsd-bugs
>State:          closed
>Quarter:
>Keywords:
>Date-Required:
>Class:          sw-bug
>Submitter-Id:   current-users
>Arrival-Date:   Thu Mar 20 15:10:01 PST 1997
>Closed-Date:    Mon Mar 24 19:42:36 PST 1997
>Last-Modified:  Tue Mar 25 15:30:01 PST 1997
>Originator:     Bill Fenner
>Release:        FreeBSD 2.2-BETA_A i386
>Organization:
Xerox
>Environment:

	
FreeBSD -current and 2.2

>Description:

	
The sigaction(2) man page has the following wording:

NOTE
     The mask specified in act is not allowed to block SIGKILL or SIGSTOP.
     This is done silently by the system.

The word "This" is ambiguous.  My first reading was "blocking SIGKILL [and]
SIGSTOP is done silently by the system".

>How-To-Repeat:

	

>Fix:
	
	
Change the last sentence to something like "This restriction is
silently enforced."  or  "Attempts to block SIGKILL or SIGSTOP will be
silently ignored."

>Release-Note:
>Audit-Trail:
State-Changed-From-To: open->closed 
State-Changed-By: mpp 
State-Changed-When: Mon Mar 24 19:42:36 PST 1997 
State-Changed-Why:  
Fixed in rev 1.12 of libc/sys/sigaction.2. 

From: Bill Fenner <fenner@parc.xerox.com>
To: Mike Pritchard <mpp@freefall.freebsd.org>
Cc: CVS-committers@freefall.freebsd.org, cvs-all@freefall.freebsd.org,
        cvs-lib@freefall.freebsd.org, freebsd-gnats-submit@freebsd.org,
        fenner@parc.xerox.com
Subject: Re: docs/3047 & cvs commit: src/lib/libc/sys sigaction.2 
Date: Tue, 25 Mar 1997 09:45:58 PST

 > Change the description of how attempts to block SIGKILL and SIGSTOP
 > are handled.  The system call will actually fail in this case - the
 > system doesn't silently ignore the request.  Closes PR# 3047
 
 Um, if this is what you took from my wording then I did an even poorer
 job than the man page did.
 
 All I meant was that the antecedent of "This" in the second sentence
 of
 
 NOTE
      The mask specified in act is not allowed to block SIGKILL or SIGSTOP.
      This is done silently by the system.
 
 is potentially unclear.  The first time I read this man page I thought
 the antecedent was "block SIGKILL [and] SIGSTOP", e.g. "the system
 silently blocks SIGKILL [and] SIGSTOP".  The real meaning (and an
 alternative reading of the same sentence) is "the system silently
 ignores attempts to block SIGKILL or SIGSTOP"; I just wanted to make
 that sentence less ambiguous.
 
 Attempting to block SIGKILL and SIGSTOP is not an error and is silently
 ignored by the system.  Everything else that the system call is
 attempting to do succeeds.  (At least, this is what POSIX says, and
 this is what 2.2 does).
 
 (While writing my test program to make absolutely sure, I noticed that the
 first line should probably read "The mask specified in the sa_mask field"
 or something similar, too...)
 
   Bill

From: Mike Pritchard <mpp>
To: fenner@parc.xerox.com (Bill Fenner)
Cc: CVS-committers@freefall.freebsd.org, cvs-all@freefall.freebsd.org,
        cvs-lib@freefall.freebsd.org, freebsd-gnats-submit@freebsd.org,
        fenner@parc.xerox.com
Subject: Re: docs/3047 & cvs commit: src/lib/libc/sys sigaction.2
Date: Tue, 25 Mar 1997 10:15:58 -0800 (PST)

 I see where I got confused.  I looked at the code to sigaction,
 saw that it would return EINVAL if the signal nuber passed in tried
 to block these signals., but the statement in question refers
 to the mask, not the signal number.  I'll go fix this and then go 
 dig out my pointy hat :-).
 
 Bill Fenner wrote:
 > 
 > > Change the description of how attempts to block SIGKILL and SIGSTOP
 > > are handled.  The system call will actually fail in this case - the
 > > system doesn't silently ignore the request.  Closes PR# 3047
 > 
 > Um, if this is what you took from my wording then I did an even poorer
 > job than the man page did.
 > 
 > All I meant was that the antecedent of "This" in the second sentence
 > of
 > 
 > NOTE
 >      The mask specified in act is not allowed to block SIGKILL or SIGSTOP.
 >      This is done silently by the system.
 > 
 > is potentially unclear.  The first time I read this man page I thought
 > the antecedent was "block SIGKILL [and] SIGSTOP", e.g. "the system
 > silently blocks SIGKILL [and] SIGSTOP".  The real meaning (and an
 > alternative reading of the same sentence) is "the system silently
 > ignores attempts to block SIGKILL or SIGSTOP"; I just wanted to make
 > that sentence less ambiguous.
 > 
 > Attempting to block SIGKILL and SIGSTOP is not an error and is silently
 > ignored by the system.  Everything else that the system call is
 > attempting to do succeeds.  (At least, this is what POSIX says, and
 > this is what 2.2 does).
 > 
 > (While writing my test program to make absolutely sure, I noticed that the
 > first line should probably read "The mask specified in the sa_mask field"
 > or something similar, too...)
 > 
 >   Bill
 > 
 
 
 -- 
 Mike Pritchard
 mpp@FreeBSD.org
 "Go that way.  Really fast.  If something gets in your way, turn"

From: Bruce Evans <bde@zeta.org.au>
To: fenner@parc.xerox.com, mpp@freefall.freebsd.org
Cc: cvs-all@freefall.freebsd.org, CVS-committers@freefall.freebsd.org,
        cvs-lib@freefall.freebsd.org, freebsd-gnats-submit@freebsd.org
Subject: Re: docs/3047 & cvs commit: src/lib/libc/sys sigaction.2
Date: Wed, 26 Mar 1997 10:27:23 +1100

 >silently blocks SIGKILL [and] SIGSTOP".  The real meaning (and an
 >alternative reading of the same sentence) is "the system silently
 >ignores attempts to block SIGKILL or SIGSTOP"; I just wanted to make
 >that sentence less ambiguous.
 
 Actually, it means "the system silently ignores attempts to set the
 SIGKILL and SIGSTOP bits in [the kernel's copy of] the signal mask.
 [This is different from setting the bits and ignoring them when a
 SIGKILL or SIGSTOP arrives, since the application can tell the difference
 by reading the kernel's copy of the signal mask.  The copy of the mask
 for the first sigaction call is of course unaffected, since it is const.]
 
 >(While writing my test program to make absolutely sure, I noticed that the
 >first line should probably read "The mask specified in the sa_mask field"
 >or something similar, too...)
 
 Yes.  POSIX says this better.
 
 Bruce
>Unformatted:
