NetBSD Problem Report #40554

From jammuli@ritari.tontut.fi  Wed Feb  4 15:46:46 2009
Return-Path: <jammuli@ritari.tontut.fi>
Received: from mail.netbsd.org (mail.netbsd.org [204.152.190.11])
	by narn.NetBSD.org (Postfix) with ESMTP id D0E1B63C07D
	for <gnats-bugs@gnats.NetBSD.org>; Wed,  4 Feb 2009 15:46:46 +0000 (UTC)
Message-Id: <20090204143001.F19DC6BD5F@arthur.ritari.tontut.fi>
Date: Wed,  4 Feb 2009 16:30:01 +0200 (EET)
From: Jarmo Jaakkola <jarmo.jaakkola@iki.fi>
Reply-To: Jarmo Jaakkola <jarmo.jaakkola@iki.fi>
To: gnats-bugs@gnats.NetBSD.org
Subject: >& -operator incorrectly documented in sh(1) man page
X-Send-Pr-Version: 3.95

>Number:         40554
>Category:       standards
>Synopsis:       >& -operator incorrectly documented in sh(1) man page
>Confidential:   no
>Severity:       non-critical
>Priority:       medium
>Responsible:    standards-manager
>State:          closed
>Class:          doc-bug
>Submitter-Id:   net
>Arrival-Date:   Wed Feb 04 15:50:00 +0000 2009
>Closed-Date:    Sun Jul 07 20:49:00 +0000 2019
>Last-Modified:  Sun Jul 07 20:49:00 +0000 2019
>Originator:     Jarmo Jaakkola
>Release:        NetBSD 4.0_STABLE
>Organization:
>Environment:
System: NetBSD arthur.ritari.tontut.fi 4.0_STABLE NetBSD 4.0_STABLE (ARTHUR) #9: Fri Jan 11 12:54:24 EET 2008 jammuli@arthur.ritari.tontut.fi:/usr/src/sys/arch/i386/compile/ARTHUR i386
Architecture: i386
Machine: i386
>Description:
This is what the manual page of sh(1) says about the >& -operator:
    [n1]>&n2    Duplicate standard output (or n1) to n2.

This is what The Single UNIX ® Specification, Version 2
(http://www.opengroup.org/onlinepubs/007908799/xcu/chap2.html#tag_001_007_006) has to say about that:
    [n]>&word
    is used to duplicate one output file descriptor from another, or to
    close one. If word evaluates to one or more digits, the file
    descriptor denoted by n, or standard output if n is not specified,
    will be made to be a copy of the file descriptor denoted by word; ...

(As I understand, The Single Unix ® Specification is quite close to
the POSIX 1003.2 specication that sh(1) claims conformance with)

>How-To-Repeat:
>Fix:

Replace "Duplicate standard output (or n1) to n2." with correct wording.

>Release-Note:

>Audit-Trail:
From: "Valeriy E. Ushakov" <uwe@netbsd.org>
To: gnats-bugs@NetBSD.org
Cc: 
Subject: Re: standards/40554
Date: Thu, 5 Feb 2009 14:57:05 +0300

 We cannot just start copy-pasting text from other sources for obvious
 copyright reasons.

 So, what's incorrect about the current wording?

 -uwe

From: Alan Barrett <apb@cequrux.com>
To: gnats-bugs@NetBSD.org
Cc: 
Subject: Re: standards/40554
Date: Thu, 5 Feb 2009 20:51:51 +0200

 On Thu, 05 Feb 2009, Valeriy E. Ushakov wrote:
 >  So, what's incorrect about the current wording?

 Our sh(1) man page implies that the n1 and n2 in [n1]>&n2 must be
 literal numbers.  My tests suggest that n1 must be a literal number, but
 n2 may be the result of variable substitution, or command substitution.

 For example, this works:

 	n2="-"
 	exec 2>&${n2}	# same as exec 2>&-

 and so does this:

 	n2="1"
 	exec 2>&${n2}	# same as exec 2>&1

 but this fails:

 	n1="2"
 	exec ${n1}>&1	# searches for "2" in $PATH, which probably fails

 --apb (Alan Barrett)

From: Robert Elz <kre@munnari.OZ.AU>
To: gnats-bugs@NetBSD.org
Cc: 
Subject: Re: standards/40554 
Date: Fri, 06 Feb 2009 03:40:50 +0700

     Date:        Thu,  5 Feb 2009 19:00:07 +0000 (UTC)
     From:        Alan Barrett <apb@cequrux.com>
     Message-ID:  <20090205190007.A6AC663C07D@narn.NetBSD.org>

   |  On Thu, 05 Feb 2009, Valeriy E. Ushakov wrote:
   |  >  So, what's incorrect about the current wording?
   |  
   |  Our sh(1) man page implies that the n1 and n2 in [n1]>&n2 must be
   |  literal numbers.

 I assumed that he meant that the man page says (simplified)
 "duplicate stdout to n2" which kind of suggests dup2(1,n2)
 whereas what really happens is dup2(n2,1).

 For <& the man page uses "from" - and really (aside from the
 default target fd) <& and >& are the exact same operation.

 I'm not sure I'd treat the "to" as an error though, as it makes the
 wording for >& match the wording for > (just as the wording for <&
 matches the wording for <).

 kre


From: David Laight <david@l8s.co.uk>
To: gnats-bugs@NetBSD.org
Cc: 
Subject: Re: standards/40554
Date: Thu, 5 Feb 2009 21:08:25 +0000

 On Thu, Feb 05, 2009 at 08:45:02PM +0000, Robert Elz wrote:
 >  
 >  I assumed that he meant that the man page says (simplified)
 >  "duplicate stdout to n2" which kind of suggests dup2(1,n2)
 >  whereas what really happens is dup2(n2,1).
 >  
 >  For <& the man page uses "from" - and really (aside from the
 >  default target fd) <& and >& are the exact same operation.
 >  
 >  I'm not sure I'd treat the "to" as an error though, as it makes the
 >  wording for >& match the wording for > (just as the wording for <&
 >  matches the wording for <).

 FWIW 2>&1 changes stderr to write to the same place as stdout.

 	David

 -- 
 David Laight: david@l8s.co.uk

From: Alan Barrett <apb@cequrux.com>
To: gnats-bugs@NetBSD.org
Cc: 
Subject: Re: standards/40554
Date: Thu, 5 Feb 2009 23:28:54 +0200

 On Thu, 05 Feb 2009, Robert Elz wrote:
 >    |  >  So, what's incorrect about the current wording?
 >  I assumed that he meant that the man page says (simplified)
 >  "duplicate stdout to n2" which kind of suggests dup2(1,n2)
 >  whereas what really happens is dup2(n2,1).

 We could say "redirect file descriptor n1 to a duplicate of file
 descriptor n2".

 --apb (Alan Barrett)

From: "Valeriy E. Ushakov" <uwe@NetBSD.org>
To: gnats-bugs@NetBSD.org
Cc: 
Subject: Re: standards/40554
Date: Fri, 6 Feb 2009 20:05:55 +0300

 On Thu, Feb 05, 2009 at 20:45:02 +0000, Robert Elz wrote:

 > I assumed that he meant that the man page says (simplified)
 > "duplicate stdout to n2" which kind of suggests dup2(1,n2)
 > whereas what really happens is dup2(n2,1).
 [...]
 > I'm not sure I'd treat the "to" as an error though, as it makes the
 > wording for >& match the wording for > (just as the wording for <&
 > matches the wording for <).

 Yeah, I guess the problem with the current wording is that it
 contaminates technical details and observed effects.

 We "duplicate" the descriptor, but we duplicate n2 to stdout
 (i.e. dup2(n2, 1)), which has the observed effect that what goes to
 stdout now goes "to n2".

 I agree that keeping wording for > and >& congruent is a good thing to
 do, i.e. "to" should refer to where the output ends up.

 SUS says "duplicate one output file descriptor from another" but
 doesn't specify which from which.  Later it says that n1/stdout "will
 be made to be a copy of the file descriptor denoted by word" (I don't
 really like the word "copy" there - one integer value cannot really be
 a "copy" of another integer value, the copying happens a level of
 indirection down).  SUS also doesn't explicitly say anything in that
 phrase about the observed effect, presuming that the user understands
 how dup2() works.

 I don't know how to word it all properly *and* keep it short.

 [n1]>&n2    Redirect standard output (or n1) to n2 by duplicating n2.

 ?


 On Thu, Feb 05, 2009 at 21:35:02 +0000, Alan Barrett wrote:

 > We could say "redirect file descriptor n1 to a duplicate of file
 > descriptor n2".

 That's much more confusing.

 -uwe

From: Robert Elz <kre@munnari.OZ.AU>
To: gnats-bugs@www.NetBSD.org
Cc: 
Subject: Re: standards/40554 : >& -operator incorrectly documented in sh(1)
Date: Mon, 15 Apr 2019 13:49:42 +0700

 I am planning on changing sh(1) to say:

            [n1]>& n2   Redirect standard output (or n1) to be a duplicate of
                        n2.

 and similarly for <&

            [n1]<& n2   Redirect standard input (or n1) from a duplicate of
                        file descriptor n2.

 (The <& case comes first, so is a little more wordy, the reader is
 supposed to be able to fill in the blanks...)

 As well as those changes (and in that, note the insertion of a space
 between ">&" and "n2" to make it clear that white space is permitted
 there, the same change is made for >& - (etc) as well).

 Does this seem likely (to one and all) to be a reasonable way of
 writing it, or at least, no worse than we currently have?

 I am also planning on enhancing the prelude to the Redirections section
 of sh(1) to appear as below (except the real thing will have correct
 markup - which I deleted for e-mail and especially gnats).

 What is below is all of that section (as proposed - but not yet spell
 checked, I will do that...) from the section heading down to, but not
 including the here-doc redirection operator (nothing from that point
 onwards is going to change in this update - if it happens).

 kre


    Redirections
      Redirections are used to change where a command reads its input or sends
      its output.  In general, redirections open, close, or duplicate an
      existing reference to a file.  The overall format used for redirection
      is:

            [n]redir-op file

      where redir-op is one of the redirection operators mentioned previously.
      A list of the possible redirections, and their meanings, follows.

      The [n] is an optional number, as in `3' (not `[3]'), that refers to a
      file descriptor.  If present it must occur immediately before the
      redirection operator, with no intervening white space, and becomes a part
      of that operator.  If file descriptor n was open prior to the
      redirection, its previous use is closed.

      All redirections have a single word file argument following the operator
      (white space is allowed between the redirection operator and file),
      though it is sometimes expressed as n2.  That argument is expanded (see
      Word Expansions below) using tilde expansion, parameter expansion,
      arithmetic expansion, command substitution and quote removal to produce
      the path name (or file descriptor) to be used.  No field splitting or
      pathname expansion takes place.  In the list below, where the file is
      given as n2 the result of the expansions must be a number which refers
      to a suitable open file descriptor.

            [n]> file   Redirect standard output (or n) to file.

            [n]>| file  The same, but override the -C option.

            [n]>> file  Append standard output (or n) to file.

            [n]< file   Redirect standard input (or n) from file.

            [n1]<& n2   Redirect standard input (or n1) from a duplicate of
                        file descriptor n2.

            [n]<& -     Close standard input (or n).  Note that the `-' is
                        minus sign (or hyphen) given literally or resulting
                        from the expansion of file (or n2) for this format.
                        When given literally there is usually no space between
                        the redirection operator and the `-', though that is
                        just a convention.

            [n1]>& n2   Redirect standard output (or n1) to be a duplicate of
                        n2.

            [n]>& -     Close standard output (or n).

            [n]<> file  Open file for reading and writing on standard input (or
                        n).


From: "Robert Elz" <kre@netbsd.org>
To: gnats-bugs@gnats.NetBSD.org
Cc: 
Subject: PR/40554 CVS commit: src/bin/sh
Date: Mon, 22 Apr 2019 04:04:36 +0000

 Module Name:	src
 Committed By:	kre
 Date:		Mon Apr 22 04:04:36 UTC 2019

 Modified Files:
 	src/bin/sh: sh.1

 Log Message:
 PR standards/40554

 Update the description of the <& and >& redirection operators
 (as indicated would happen in a message appended to the PR a week ago,
 which received no opposition - no feedback).

 Some rewriting of the section on redirects (including how the word
 expansion of the "file" works) to make this simpler & more accurate.


 To generate a diff of this commit:
 cvs rdiff -u -r1.221 -r1.222 src/bin/sh/sh.1

 Please note that diffs are not public domain; they are subject to the
 copyright notices on the relevant files.

State-Changed-From-To: open->feedback
State-Changed-By: kre@NetBSD.org
State-Changed-When: Mon, 22 Apr 2019 04:38:05 +0000
State-Changed-Why:
Is the text about >& and <& now in sh.1 in NetBSD HEAD adequate?
(It is identical to that appended to this PR a week ago.)

Note: as this is just a doc wording issue, which can be updated again
any time if needed, with no impact other than (hopefully) better
accuracy and readability, I will set a fairly short feedback timeout
on this one (say a week or so), after which the PR will simply close
if there has been no response.


State-Changed-From-To: feedback->closed
State-Changed-By: dholland@NetBSD.org
State-Changed-When: Sun, 07 Jul 2019 20:49:00 +0000
State-Changed-Why:
Fixed.


>Unformatted:

Home	PR Database Search