From garys@opusnet.com  Fri Jul 29 02:37:34 2005
Return-Path: <garys@opusnet.com>
Received: from mx1.FreeBSD.org (mx1.freebsd.org [216.136.204.125])
	by hub.freebsd.org (Postfix) with ESMTP id 7E7B816A425
	for <FreeBSD-gnats-submit@freebsd.org>; Fri, 29 Jul 2005 02:37:34 +0000 (GMT)
	(envelope-from garys@opusnet.com)
Received: from opusnet.com (mail.opusnet.com [209.210.200.6])
	by mx1.FreeBSD.org (Postfix) with ESMTP id D54DE43D7D
	for <FreeBSD-gnats-submit@freebsd.org>; Fri, 29 Jul 2005 01:56:20 +0000 (GMT)
	(envelope-from garys@opusnet.com)
Received: from localhost.localhost [70.98.246.232] by opusnet.com with ESMTP
  (SMTPD32-8.05) id ACC13D9C0034; Thu, 28 Jul 2005 18:56:17 -0700
Received: from localhost.localhost (localhost.localhost [127.0.0.1])
	by localhost.localhost (8.13.3/8.13.3) with ESMTP id j6T1vIYJ080155
	for <FreeBSD-gnats-submit@freebsd.org>; Thu, 28 Jul 2005 18:57:18 -0700 (PDT)
	(envelope-from garys@opusnet.com)
Received: (from jojo@localhost)
	by localhost.localhost (8.13.3/8.13.3/Submit) id j6T1vDhH080154;
	Thu, 28 Jul 2005 18:57:13 -0700 (PDT)
	(envelope-from garys@opusnet.com)
Message-Id: <2uvf2ubchy.f2u@mail.opusnet.com>
Date: Thu, 28 Jul 2005 18:57:13 -0700
From: "Gary W. Swearingen" <garys@opusnet.com>
Reply-To: garys@opusnet.com
To: FreeBSD-gnats-submit@freebsd.org
Subject: chmod(1) manpage omits implication of setting w on directory
X-GNATS-Notify:

>Number:         84265
>Category:       docs
>Synopsis:       [patch] chmod(1) manpage omits implication of setting w on directory
>Confidential:   no
>Severity:       non-critical
>Priority:       low
>Responsible:    trhodes
>State:          closed
>Quarter:        
>Keywords:       
>Date-Required:  
>Class:          change-request
>Submitter-Id:   current-users
>Arrival-Date:   Fri Jul 29 02:40:13 GMT 2005
>Closed-Date:    Sat Jul 21 15:42:42 UTC 2012
>Last-Modified:  Sat Jul 21 15:42:42 UTC 2012
>Originator:     Gary W. Swearingen
>Release:        FreeBSD 5.4-RELEASE i386
>Organization:
none
>Environment:
n/a
>Description:

The manpage gives some implications of setting SUID on a directory
but not W.

The concept mentioned below is not covered elsewhere AFAIK, at least
outside c-programmer manpages.  It should be.

>How-To-Repeat:
n/a

>Fix:
Apply patch.

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.


--- /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 >
+or an editor, but not by
+.Nm mv
+or 
+.Nm cp )
+will be assigned the group of the directory.
 .Sh EXAMPLES
 .Bl -tag -width "u=rwx,go=u-w" -compact
 .It Li 644
>Release-Note:
>Audit-Trail:

From: Ceri Davies <ceri@submonkey.net>
To: garys@opusnet.com
Cc: FreeBSD-gnats-submit@FreeBSD.org
Subject: Re: docs/84265: chmod(1) manpage omits implication of setting w on directory
Date: Sun, 31 Jul 2005 14:44:38 +0100

 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.)
 
 

From: garys@opusnet.com (Gary W. Swearingen)
To: Ceri Davies <ceri@submonkey.net>
Cc: FreeBSD-gnats-submit@FreeBSD.org
Subject: Re: docs/84265: chmod(1) manpage omits implication of setting w on
 directory
Date: Sun, 31 Jul 2005 10:49:15 -0700

 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

From: Giorgos Keramidas <keramida@freebsd.org>
To: "Gary W. Swearingen" <garys@opusnet.com>
Cc: bug-followup@freebsd.org
Subject: Re: docs/84265: chmod(1) manpage omits implication of setting w on directory
Date: Sun, 31 Jul 2005 23:25:09 +0300

 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 :-)
 

From: garys@opusnet.com (Gary W. Swearingen)
To: Giorgos Keramidas <keramida@freebsd.org>
Cc: bug-followup@freebsd.org
Subject: Re: docs/84265: chmod(1) manpage omits implication of setting w on
 directory
Date: Sun, 31 Jul 2005 14:25:12 -0700

 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.

From: Giorgos Keramidas <keramida@freebsd.org>
To: "Gary W. Swearingen" <garys@opusnet.com>
Cc: bug-followup@freebsd.org
Subject: Re: docs/84265: chmod(1) manpage omits implication of setting w on directory
Date: Mon, 1 Aug 2005 11:59:35 +0300

 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 :-)
 

From: garys@opusnet.com (Gary W. Swearingen)
To: Giorgos Keramidas <keramida@freebsd.org>
Cc: bug-followup@freebsd.org
Subject: Re: docs/84265: chmod(1) manpage omits implication of setting w on
 directory
Date: Mon, 01 Aug 2005 07:18:47 -0700

 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.

From: Giorgos Keramidas <keramida@freebsd.org>
To: "Gary W. Swearingen" <garys@opusnet.com>
Cc: bug-followup@freebsd.org
Subject: Re: docs/84265: chmod(1) manpage omits implication of setting w on directory
Date: Mon, 1 Aug 2005 17:25:43 +0300

 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 :-)
 
State-Changed-From-To: open->patched 
State-Changed-By: trhodes 
State-Changed-When: Fri Jan 23 11:39:59 UTC 2009 
State-Changed-Why:  
Implication of the 'w' (write) permission on directories 
added.  Thanks. 


Responsible-Changed-From-To: freebsd-doc->trhodes 
Responsible-Changed-By: trhodes 
Responsible-Changed-When: Fri Jan 23 11:39:59 UTC 2009 
Responsible-Changed-Why:  
Over to me. 

http://www.freebsd.org/cgi/query-pr.cgi?pr=84265 

From: dfilter@FreeBSD.ORG (dfilter service)
To: bug-followup@FreeBSD.org
Cc:  
Subject: Re: docs/84265: commit references a PR
Date: Fri, 23 Jan 2009 11:39:11 +0000 (UTC)

 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: patched->closed 
State-Changed-By: trhodes 
State-Changed-When: Sat Jul 21 15:42:25 UTC 2012 
State-Changed-Why:  
Changes have been merged for awhile now, thanks. 

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