Bug 46415
| Summary: | Proposed change in man-page wording for "chown" | ||
|---|---|---|---|
| Product: | Documentation | Reporter: | System Administrator <root> |
| Component: | Books & Articles | Assignee: | Giorgos Keramidas <keramida> |
| Status: | Closed FIXED | ||
| Severity: | Affects Only Me | ||
| Priority: | Normal | ||
| Version: | Latest | ||
| Hardware: | Any | ||
| OS: | Any | ||
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. ----- 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 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? 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 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 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 |
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!