Bug 84265
| Summary: | [patch] chmod(1) manpage omits implication of setting w on directory | ||||||
|---|---|---|---|---|---|---|---|
| Product: | Documentation | Reporter: | Gary W. Swearingen <garys> | ||||
| Component: | Books & Articles | Assignee: | Tom Rhodes <trhodes> | ||||
| Status: | Closed FIXED | ||||||
| Severity: | Affects Only Me | ||||||
| Priority: | Normal | ||||||
| Version: | Latest | ||||||
| Hardware: | Any | ||||||
| OS: | Any | ||||||
| Attachments: |
|
||||||
|
Description
Gary W. Swearingen
2005-07-29 03:40:13 UTC
On 29 Jul 2005, at 02:57, Gary W. Swearingen wrote: > I'd also add the following paragraph to the chmod(1) and chgrp(1) > manpages, but I'll wait for approval before making patches. > > The group of a directory will be assigned to files newly created > (eg, by > or an editor, but not by mv or cp) within it, despite the > owner or group of the creator. A reference to touch(1) rather than '>' reads better here, I think. Also, the reference to "owner" should be "user id", as the creator of the file probably doesn't have an owner ;) > --- /pr/work/chmod..orig.1 Wed Jul 27 18:05:44 2005 > +++ /pr/work/chmod.1 Wed Jul 27 18:14:08 2005 > @@ -276,6 +276,16 @@ > ``o'' by itself), in combination with the > .Ar perm > symbols ``s'' or ``t'', are ignored. > +.Pp > +Setting the write permission on a directory will enable files to be > +moved into or copied into or created in the directory. Files > +created in the directory (eg, by > +.Nm > Here too. > +or an editor, but not by > +.Nm mv > +or > +.Nm cp ) > +will be assigned the group of the directory. "Group id" (or similar) wins over "group" here for me, too. Ceri -- Only two things are infinite, the universe and human stupidity, and I'm not sure about the former. -- Einstein (attrib.) Ceri Davies <ceri@submonkey.net> writes: > On 29 Jul 2005, at 02:57, Gary W. Swearingen wrote: > > I'd also add the following paragraph to the chmod(1) and chgrp(1) > > manpages, but I'll wait for approval before making patches. > > > > The group of a directory will be assigned to files newly created > > (eg, by > or an editor, but not by mv or cp) within it, despite the > > owner or group of the creator. > A reference to touch(1) rather than '>' reads better here, I think. How about this new para for chown(1) and chgrp(1)? Files created in a directory will be generally be assigned the group ID of the directory, with exceptions including files added by cp(1) with -p and mv(1). Want patches for that? In new PR(s) or this one? > Also, the reference to "owner" should be "user id", as the creator of the file probably doesn't have an owner ;) "Owner" is a concept, while "User ID" is an implementation detail, but it's no big deal; I've changed that (and more): Setting the write permission on a directory will enable files to be added to it. Files created in the directory will be generally be assigned the group ID of the directory, with exceptions including files added by cp(1) with -p and mv(1). Note that I haven't added cp(1) and mv(1) to the "SEE ALSO" because their man pages don't sufficiently help explain chmod(1). I hope I handled that last period OK; it looks OK on my xterm. --- chmod..orig.1 Wed Jul 27 18:05:44 2005 +++ chmod.1 Sun Jul 31 10:35:18 2005 @@ -276,6 +276,16 @@ ``o'' by itself), in combination with the .Ar perm symbols ``s'' or ``t'', are ignored. +.Pp +Setting the write permission on a directory will enable files to be +added to it. Files created in the directory will be generally be +assigned the group ID of the directory, with exceptions including +files added by +.Xr cp 1 +with +.Fl p +and +.Xr mv 1 . .Sh EXAMPLES .Bl -tag -width "u=rwx,go=u-w" -compact .It Li 644 On 2005-07-31 17:50, "Gary W. Swearingen" <garys@opusnet.com> wrote: > Ceri Davies <ceri@submonkey.net> writes: > > On 29 Jul 2005, at 02:57, Gary W. Swearingen wrote: > > > I'd also add the following paragraph to the chmod(1) and chgrp(1) > > > manpages, but I'll wait for approval before making patches. > > > > > > The group of a directory will be assigned to files newly created > > > (eg, by > or an editor, but not by mv or cp) within it, despite the > > > owner or group of the creator. > > > > A reference to touch(1) rather than '>' reads better here, I think. > > > How about this new para for chown(1) and chgrp(1)? > > Files created in a directory will be generally be assigned the > group ID of the directory, with exceptions including files added > by cp(1) with -p and mv(1). ``Files created in a directory will be assigned the group ID of the directory'' period. The fact that cp(1) and mv(1) call chown to set the permissions to something else is a feature of those programs and not of the file creation code. I'm not sure if I am happy when features of programs are documented as the behavior of the file/directory creation code. Documenting the implications of write permission is important, but please let us not modify perfectly fine parts of the manpage :-/ > I hope I handled that last period OK; it looks OK on my xterm. > [...] > +with > +.Fl p > +and > +.Xr mv 1 . It is very fine, thanks for all the attention to the details :-) Giorgos Keramidas <keramida@freebsd.org> writes: > I'm not sure if I am happy when features of programs are documented as > the behavior of the file/directory creation code. I wasn't sure, either. But users with a different concept of "created" than a Unix programmer will cry "FALSE" when they read your ``Files created in a directory will be assigned the group ID of the directory''. Many users don't know or care about system libraries that do file creation or directory modification. The fact is that some software creates it with one group and some creates it with another group. Thus my "generally". If you want your sentence, it should at least have another saying something like: "This rule has exceptions." or "Some software will appear to violate this convention". > Documenting the implications of write permission is important, but > please let us not modify perfectly fine parts of the manpage :-/ The only thing my new paragraph was modifying was the DESCRIPTION section. I'm not sure which perfectly fine parts you mean. I've probably said enough; do as you wish. On 2005-07-31 14:25, "Gary W. Swearingen" <garys@opusnet.com> wrote: >Giorgos Keramidas <keramida@freebsd.org> writes: >> I'm not sure if I am happy when features of programs are documented as >> the behavior of the file/directory creation code. > > I wasn't sure, either. But users with a different concept of "created" > than a Unix programmer will cry "FALSE" when they read your ``Files > created in a directory will be assigned the group ID of the > directory''. Ah, I see. Good point. > If you want your sentence, it should at least have another saying > something like: "This rule has exceptions." or "Some software will > appear to violate this convention". How about a note that... There are exceptions, since some programs by design (or because it was requested with a special command-line option) need to create the files and then modify their owner and/or permissions for various reasons. Such exceptions include: * The cp(1) utility when the -p option is used. * The mv(1) utility. * Archiving tools, like cpio(1) or tar(1). * Backup tools, like restore(8) Does that look ok? > I've probably said enough; do as you wish. Ehm. No, please keep saying. Your comments have been extremely useful as a means to improve the manpages so far :-) Giorgos Keramidas <keramida@freebsd.org> writes: > Does that look ok? Some will think it says too much, or says it in the wrong manpage, but it looks good to me. (I'd probably delete "by design...need to".) I hope you include this in the same para as your other sentence. BTW, I forgot that you might just be commenting on the PR and it might not be assigned to you (yet?). Unless I hear otherwise, I'll just forget about it for a while and see later whether I need to do more with it, like write (small?) patches for chown & chgrp, which I'm now thinking should probably refer to this rather extensive explanation in chmod. Unless you think it needn't be mentioned anywhere else. On 2005-08-01 07:18, "Gary W. Swearingen" <garys@opusnet.com> wrote: > BTW, I forgot that you might just be commenting on the PR and it might > not be assigned to you (yet?). Unless I hear otherwise, I'll just > forget about it for a while and see later whether I need to do more > with it, like write (small?) patches for chown & chgrp, which I'm now > thinking should probably refer to this rather extensive explanation in > chmod. Unless you think it needn't be mentioned anywhere else. Sounds like a nice plan :-) Author: trhodes Date: Fri Jan 23 11:39:00 2009 New Revision: 187627 URL: http://svn.freebsd.org/changeset/base/187627 Log: Note the implication of setting the 'w' permission on directories, while here, expand the 'naughty bits' comment in BUGS. PR: 84265 and 84268 Reviewed by: keramida Obtained from: hints from ceri, keramida Modified: head/bin/chmod/chmod.1 Modified: head/bin/chmod/chmod.1 ============================================================================== --- head/bin/chmod/chmod.1 Fri Jan 23 11:11:29 2009 (r187626) +++ head/bin/chmod/chmod.1 Fri Jan 23 11:39:00 2009 (r187627) @@ -32,7 +32,7 @@ .\" @(#)chmod.1 8.4 (Berkeley) 3/31/94 .\" $FreeBSD$ .\" -.Dd December 22, 2006 +.Dd January 23, 2009 .Dt CHMOD 1 .Os .Sh NAME @@ -281,6 +281,10 @@ Operations upon the other permissions on ``o'' by itself), in combination with the .Ar perm symbols ``s'' or ``t'', are ignored. +.Pp +The ``w'' permission on directories will permit file creation, relocation, +and copy into that directory. +Files created within the directory itself will inherit its group ID. .Sh EXAMPLES .Bl -tag -width "u=rwx,go=u-w" -compact .It Li 644 @@ -343,4 +347,5 @@ command appeared in .Sh BUGS There is no .Ar perm -option for the naughty bits. +option for the naughty bits which are ``S'' and +``T'' respectively. _______________________________________________ svn-src-all@freebsd.org mailing list http://lists.freebsd.org/mailman/listinfo/svn-src-all To unsubscribe, send any mail to "svn-src-all-unsubscribe@freebsd.org" State Changed From-To: open->patched Implication of the 'w' (write) permission on directories added. Thanks. Responsible Changed From-To: freebsd-doc->trhodes Over to me. State Changed From-To: patched->closed Changes have been merged for awhile now, thanks. |
