Subject: Re: bug#17495: chgrp: mention of being a member of the target group

From: Pádraig Brady <[email-masked]>
Date: Thu, 19 Jun 2014 18:57:41 +0100

On 06/19/2014 02:34 PM, Pádraig Brady wrote:
> The variation on some systems where users can give away files
> is discussed at the "APPLICATION USAGE" and "RATIONALE" sections of:
> http://pubs.opengroup.org/onlinepubs/9699919799/functions/chown.html
> 
> We should mention this _portable_ behavior in the info doc at least
> for chown and chgrp

Done in the attached.

thanks,
Pádraig.

>From e548deddaacb63b00b9d2878c3bdf222db955c0c Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?P=C3=A1draig=20Brady?= <[email-masked]>
Date: Thu, 19 Jun 2014 18:49:18 +0100
Subject: [PATCH] doc: clarify chgrp restrictions

* doc/coreutils.texi (chown invocation): Mention the system dependent
restrictions on setting groups.
(chgrp invocation): Likewise. Reference the 'chown' superset.
*man/chgrp.x: Cross reference chown(1) which is the superset interface,
and also chown(2) which gives details of the platform restrictions.
Fixes http://bugs.gnu.org/17495
---
 doc/coreutils.texi |   12 +++++++++++-
 man/chgrp.x        |    2 ++
 man/chown.x        |    2 +-
 3 files changed, 14 insertions(+), 2 deletions(-)

diff --git a/doc/coreutils.texi b/doc/coreutils.texi
index 3cdfb72..b3ea88c 100644
--- a/doc/coreutils.texi
+++ b/doc/coreutils.texi
@@ -10525,6 +10525,13 @@ portable, and because it has undesirable results if the entire
 @var{owner@samp{.}group} happens to identify a user whose name
 contains @samp{.}.
 
+@macro chownGroupRestrictions
+It's system dependent whether a user can change the group to an arbitrary one,
+or the more portable behavior of being restricted to setting a group in
+which the user is a member.
+@end macro
+@chownGroupRestrictions
+
 The @command{chown} command sometimes clears the set-user-ID or
 set-group-ID permission bits.  This behavior depends on the policy and
 functionality of the underlying @code{chown} system call, which may
@@ -10685,7 +10692,8 @@ chown -hR root /u
 
 @command{chgrp} changes the group ownership of each given @var{file}
 to @var{group} (which can be either a group name or a numeric group ID)
-or to the group of an existing reference file.  Synopsis:
+or to the group of an existing reference file.  @xref{chown invocation}.
+Synopsis:
 
 @example
 chgrp [@var{option}]@dots{} @{@var{group} | --reference=@var{ref_file}@}@c
@@ -10696,6 +10704,8 @@ If @var{group} is intended to represent a
 numeric group ID, then you may specify it with a leading @samp{+}.
 @xref{Disambiguating names and IDs}.
 
+@chownGroupRestrictions
+
 The program accepts the following options.  Also see @ref{Common options}.
 
 @table @samp
diff --git a/man/chgrp.x b/man/chgrp.x
index 1ceeafc..b146a46 100644
--- a/man/chgrp.x
+++ b/man/chgrp.x
@@ -2,3 +2,5 @@
 chgrp \- change group ownership
 [DESCRIPTION]
 .\" Add any additional description here
+[SEE ALSO]
+chown(1)
diff --git a/man/chown.x b/man/chown.x
index 96b0c23..31e7104 100644
--- a/man/chown.x
+++ b/man/chown.x
@@ -27,4 +27,4 @@ If only a colon is given, or if the entire operand is empty, neither the
 owner nor the group is changed.
 .SH OPTIONS
 [SEE ALSO]
-chown(2)
+chown(1), chown(2)
-- 
1.7.7.6