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:
(Contact us)
$NetBSD: query-full-pr,v 1.43 2018/01/16 07:36:43 maya Exp $
$NetBSD: gnats_config.sh,v 1.9 2014/08/02 14:16:04 spz Exp $
Copyright © 1994-2017
The NetBSD Foundation, Inc. ALL RIGHTS RESERVED.