From root@asarian-host.net  Fri Dec 20 20:33:43 2002
Return-Path: <root@asarian-host.net>
Received: from mx1.FreeBSD.org (mx1.freebsd.org [216.136.204.125])
	by hub.freebsd.org (Postfix) with ESMTP id 3BDFA37B401
	for <freebsd-gnats-submit@freebsd.org>; Fri, 20 Dec 2002 20:33:43 -0800 (PST)
Received: from asarian-host.net (a194-109-160-70.adsl.xs4all.nl [194.109.160.70])
	by mx1.FreeBSD.org (Postfix) with ESMTP id 33AB543EDA
	for <freebsd-gnats-submit@freebsd.org>; Fri, 20 Dec 2002 20:33:42 -0800 (PST)
	(envelope-from root@asarian-host.net)
Received: (from root@localhost)
	by asarian-host.net (8.12.6/8.12.6) id gBL4Xd7L000587
	for freebsd-gnats-submit@freebsd.org; Sat, 21 Dec 2002 05:33:39 +0100 (CET)
	(envelope-from root@asarian-host.net)
Message-Id: <200212210433.GBL4XZUF000578@asarian-host.net>
Date: Sat, 21 Dec 2002 05:33:35 +0100 (CET)
From: System Administrator <root@asarian-host.net>
Reply-To: root@asarian-host.net
To: FreeBSD-gnats-submit@freebsd.org
Cc:
Subject: Proposed change in man-page wording for "chown"
X-Send-Pr-Version: 3.113
X-GNATS-Notify:

>Number:         46415
>Category:       docs
>Synopsis:       Proposed change in man-page wording for "chown"
>Confidential:   no
>Severity:       non-critical
>Priority:       low
>Responsible:    keramida
>State:          closed
>Quarter:        
>Keywords:       
>Date-Required:  
>Class:          change-request
>Submitter-Id:   current-users
>Arrival-Date:   Fri Dec 20 20:40:01 PST 2002
>Closed-Date:    Sat Jan 25 18:46:56 PST 2003
>Last-Modified:  Sat Jan 25 18:46:56 PST 2003
>Originator:     Superuser
>Release:        FreeBSD 4.7-RELEASE i386
>Organization:
Asarian-host
>Environment:
System: FreeBSD asarian-host.net 4.7-RELEASE FreeBSD 4.7-RELEASE #0: Sat Nov 30 17:01:16 CET 2002 root@asarian-host.net:/usr/obj/usr/src/sys/ASARIAN-HOST i386


>Description:

Recent discussions on the FreeBSD mailing list about the behavior of the -R parameter for "chown" (specifically in the context
of "chown -R .*"), led to some confusion as to the meaning of the current manpage wording,

-R   Change the user ID and/or the group ID for the file hierarchies
     rooted in the files instead of just the files themselves.

Therefore, I believe that perhaps a more legible wording may be in order:

-R   If file designates a directory, chown changes the ownership of
     the directory and the entire subtree connected at that point.

Perhaps, all to the discretion of the developers, of course, the following text could be added:

     Caveat: depending on your shell, ".*" may expand the parent directory!

>How-To-Repeat:
	
>Fix:

>Release-Note:
>Audit-Trail:

From: swear@attbi.com (Gary W. Swearingen)
To: root@asarian-host.net
Cc: FreeBSD-gnats-submit@FreeBSD.org
Subject: Re: docs/46415: Proposed change in man-page wording for "chown"
Date: 21 Dec 2002 11:19:50 -0800

 System Administrator <root@asarian-host.net> writes:
 
 > Therefore, I believe that perhaps a more legible wording may be in order:
 > 
 > -R   If file designates a directory, chown changes the ownership of
 >      the directory and the entire subtree connected at that point.
 
 1) That leaves one guessing what happens if "file" isn't a directory.
 2) While using just "ownership" *should* be sufficient, the manpage
 currently uses "owner" where it should use "user", so that "ownership"
 is likely to be interpreted as related only to "owner" and not also to
 "group" (groupship?).  Short of fixing "owner" throughout, "ownership"
 should be replaced with the twice-used "user ID and/or the group ID" or
 maybe just "ID". 3) While "Entire subtree" provids a strong clue as to
 meaning that just "subtree" doesn't, they can be seen as equivalent in 
 a strict reading. It could be more clear about being recursive.  Maybe:
 
 -R  Change the user ID and/or the group ID of the directory entries
     specified by the "file" arguments and, recursively, the contents
     of any directory subtrees named by those directory entries.
 
 (A little verbose, even redundant -- but clear, IMO.  I'd probably end
 it "... subtrees so specified." if it didn't sound too archaic.)
 
 > Perhaps, all to the discretion of the developers, of course, the following text could be added:
 > 
 >      Caveat: depending on your shell, ".*" may expand the parent directory!
 
 It's usually best to avoid "your", and "expand the parent directory"
 seems to imply that ".*" might turn into a list of the parent
 directory's files.  "Caveat" is unnecessarily esoteric.  How about:
 
 Beware that ".*" is expanded by some shells to include "..".
 
 (Using ".." explains how the parent directory can be included and
 it shouldn't be necessary to explain that ".." IS the parent dir.)
 
 
 Another issue is the placement of the warning.  An unexpected ".." could
 cause great harm with or without "-R".  The warning seems to belong at
 the end of the DESCRIPTION section as a separate paragraph, but it's
 far more useful in reducing the occurances of disasters if it's in the
 description of "-R".  It's short enough to put in both places.

From: System Administrator <root@asarian-host.net>
To: "Gary W. Swearingen" <swear@attbi.com>
Cc: <FreeBSD-gnats-submit@freebsd.org>
Subject: Re: docs/46415: Proposed change in man-page wording for "chown"
Date: Sun, 22 Dec 2002 02:00:09 +0100

 ----- Original Message -----
 From: "Gary W. Swearingen" <swear@attbi.com>
 To: <root@asarian-host.net>
 Cc: <FreeBSD-gnats-submit@FreeBSD.org>
 Sent: Saturday, December 21, 2002 8:19 PM
 Subject: Re: docs/46415: Proposed change in man-page wording for "chown"
 
 > System Administrator <root@asarian-host.net> writes:
 >
 > > Therefore, I believe that perhaps a more legible wording may be in
 > > order:
 > >
 > > -R If file designates a directory, chown changes the ownership of
 > > the directory and the entire subtree connected at that point.
 >
 > 1) That leaves one guessing what happens if "file" isn't a directory.
 
 True.
 
 > While "Entire subtree" provides a strong clue as to
 > meaning that just "subtree" doesn't, they can be seen as equivalent in
 > a strict reading.
 
 I paraphrased the wording of "cp" (because "cp -R .*" acts similarly), which
 reads:
 
 -R   If source_file designates a directory, cp copies the directory and
      the entire subtree connected at that point.
 
 > It could be more clear about being recursive. Maybe:
 >
 >  -R Change the user ID and/or the group ID of the directory entries
 >     specified by the "file" arguments and, recursively, the contents
 >     of any directory subtrees named by those directory entries.
 
 Much better. :)
 
 > "Caveat" is unnecessarily esoteric. How about:
 >
 > Beware that ".*" is expanded by some shells to include "..".
 
 Excellent. :) Very clear.
 
 > Another issue is the placement of the warning. An unexpected ".." could
 > cause great harm with or without "-R". The warning seems to belong at
 > the end of the DESCRIPTION section as a separate paragraph, but it's
 > far more useful in reducing the occurances of disasters if it's in the
 > description of "-R". It's short enough to put in both places.
 
 I would love a little warning; yesterday a user on the FreeBSD mailing list
 hosed his entire system doing:
 
   "chown -R /data/.*"
 
 And I can see how that might be upsetting. :)
 
 Although I understand the man pages are not meant to take the place of a
 UNIX tutorial, in cases like this, a friendly hint or two may prevent a lot
 of disasters.
 
 Well, thanks for replying anyway. :)
 
 - Mark
 
         System Administrator Asarian-host.org
 
 ---
 "If you were supposed to understand it,
 we wouldn't call it code." - FedEx
 

From: Giorgos Keramidas <keramida@freebsd.org>
To: bug-followup@freebsd.org
Cc: System Administrator <root@asarian-host.net>,
	"Gary W. Swearingen" <swear@attbi.com>
Subject: Re: docs/46415: Proposed change in man-page wording for "chown"
Date: Sat, 25 Jan 2003 01:15:08 +0200

 swear@attbi.com (Gary W. Swearingen) wrote:
 >It could be more clear about being recursive.  Maybe:
 >
 >  -R  Change the user ID and/or the group ID of the directory entries
 >      specified by the "file" arguments and, recursively, the contents
 >      of any directory subtrees named by those directory entries.
 >
 >(A little verbose, even redundant -- but clear, IMO.  I'd probably end
 >it "... subtrees so specified." if it didn't sound too archaic.)
 
 The current description of -R in chown(8) is the same in the current
 and stable branches:
 
    -R   Change the user ID and/or the group ID for the file hierarchies
         rooted in the files instead of just the files themselves.
 
 Instead of replacing it altogether with a new version, we could add a
 note to it.  I was thinking of something like:
 
     Index: chown.8
     ===================================================================
     RCS file: /home/ncvs/src/usr.sbin/chown/chown.8,v
     retrieving revision 1.20
     diff -u -r1.20 chown.8
     --- chown.8	14 Jul 2002 14:42:43 -0000	1.20
     +++ chown.8	24 Jan 2003 23:09:45 -0000
     @@ -82,6 +82,11 @@
      .It Fl R
      Change the user ID and/or the group ID for the file hierarchies rooted
      in the files instead of just the files themselves.
     +Be careful when you use wildcard patterns that include a dot
     +.Ql \&.
     +character, since when expanded by your shell it might result in
     +.Nm
     +changing files outside of the current directory.
      .It Fl f
      Don't report any failure to change file owner or group, nor modify
      the exit status to reflect such failures.
 
 What do you think?
 

From: swear@attbi.com (Gary W. Swearingen)
To: Giorgos Keramidas <keramida@freebsd.org>
Cc: bug-followup@freebsd.org,
	System Administrator <root@asarian-host.net>
Subject: Re: docs/46415: Proposed change in man-page wording for "chown"
Date: 24 Jan 2003 19:19:08 -0800

 Giorgos Keramidas <keramida@freebsd.org> writes:
 
 >      Change the user ID and/or the group ID for the file hierarchies rooted
 >      in the files instead of just the files themselves.
 
 I guess it'll do.  It sure is geeky.  "Hierarchies rooted in files"?
 I'm not sure that it's even explained in intro Unix books that "files"
 can mean "directories" or what "rooted" means.  But I guess newbies can
 learn to decypher geek-speak the same way we did -- the hard way.
 
 >     +Be careful when you use wildcard patterns that include a dot
 >     +.Ql \&.
 >     +character, since when expanded by your shell it might result in
 >     +.Nm
 >     +changing files outside of the current directory.
 
 It probably needs to mention the culprit, ".." as it's not obvious why
 a dot needs care.  "*dog.cat" needs no care, but "dog/../../cat" does.
 (The latter's need for care can probably go without saying with or
 without a "*".)  How about:
 
 Beware of unintentionally operating on the ".." hard link when using
 wildcards which start with a dot (e.g., ".*") .
 
 Also: In your sentence, I think you ought to paren the dot character and
 move it after "character", or just remove the word "dot".
 
 P.S.  Here's a little log of a test I just ran.  I guess I don't know
 what we're trying to document, now. It didn't pick up the ".." link.
 ????
 
 $ chown -R root:wheel .*
 chown: .*: No such file or directory

From: Giorgos Keramidas <keramida@freebsd.org>
To: bug-followup@freebsd.org
Cc: "Gary W. Swearingen" <swear@attbi.com>,
	System Administrator <root@asarian-host.net>
Subject: Re: docs/46415: Proposed change in man-page wording for "chown"
Date: Sat, 25 Jan 2003 05:51:36 +0200

 On 2003-01-24 19:19, "Gary W. Swearingen" <swear@attbi.com> wrote:
 > Giorgos Keramidas <keramida@freebsd.org> writes:
 > >      Change the user ID and/or the group ID for the file hierarchies rooted
 > >      in the files instead of just the files themselves.
 >
 > I guess it'll do.  It sure is geeky.  "Hierarchies rooted in files"?
 > I'm not sure that it's even explained in intro Unix books that "files"
 > can mean "directories" or what "rooted" means.  But I guess newbies can
 > learn to decypher geek-speak the same way we did -- the hard way.
 
 I just checked the other two BSDs.  They haven't changed anything
 here.  My guess is that they share the opinion that "everything is a
 file under Unix".  A more verbose description can't hurt though.
 
 
 > It probably needs to mention the culprit, ".." as it's not obvious why
 > a dot needs care.  "*dog.cat" needs no care, but "dog/../../cat" does.
 > (The latter's need for care can probably go without saying with or
 > without a "*".)  How about:
 >
 > Beware of unintentionally operating on the ".." hard link when using
 > wildcards which start with a dot (e.g., ".*") .
 
 This is nice, short and precise.  Paraphrasing your initial change
 here a bit, does this look better?
 
     - -R  Change the user ID and/or the group ID of the directory entries
     -     specified by the "file" arguments and, recursively, the contents
     -     of any directory subtrees named by those directory entries.
     + -R  Change the user ID and/or the group ID of the directory
     +	  entries specified by the "file" arguments and, recursively,
     +	  the contents of any directory subtrees in the argument list.
     +	  When the -R option is used, beware of unintentionally
     +	  operating on the ".." hard link when using wildcards which
     +	  start with a dot (e.g., ".*").
 
 > Also: In your sentence, I think you ought to paren the dot character and
 > move it after "character", or just remove the word "dot".
 
 True.  I'll dust my groff_mdoc stuff and use parens.
 
 > P.S.  Here's a little log of a test I just ran.  I guess I don't
 > know what we're trying to document, now. It didn't pick up the ".."
 > link.  ????
 >
 > $ chown -R root:wheel .*
 > chown: .*: No such file or directory
 
 Hmmm, what is your shell?  I've tried both /bin/sh and bash with the
 following and .. shows up in the list printed:
 
   $ echo chown -R root:wheel .*
   chown -R root:wheel . .. .X0-lock .X11-unix
   $
 
 - Giorgos
State-Changed-From-To: open->closed 
State-Changed-By: keramida 
State-Changed-When: Sat Jan 25 18:44:24 PST 2003 
State-Changed-Why:  
Committed a change that Gary maild to me that dscribes -R better. 
Look for revision 1.21 of src/usr.sbin/chown/chown.8,v 


Responsible-Changed-From-To: freebsd-doc->keramida 
Responsible-Changed-By: keramida 
Responsible-Changed-When: Sat Jan 25 18:44:24 PST 2003 
Responsible-Changed-Why:  

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