[Top][All Lists]
[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
Document new syntax: "chown +0:+287 file", "chgrp +99 file"
From: |
Jim Meyering |
Subject: |
Document new syntax: "chown +0:+287 file", "chgrp +99 file" |
Date: |
Mon, 29 Jan 2007 18:11:13 +0100 |
Here's the documentation for the new chown/chgrp syntax:
* coreutils.texi (Disambiguating names and IDs): New section.
(chown invocation, chgrp invocation): Mention the new syntax
with an xref to the new section.
diff --git a/doc/coreutils.texi b/doc/coreutils.texi
index ff049bc..05bf7c6 100644
--- a/doc/coreutils.texi
+++ b/doc/coreutils.texi
@@ -208,6 +208,7 @@ Common Options
* Exit status:: Indicating program success or failure.
* Backup options:: Backup options
* Block size:: Block size
+* Disambiguating names and IDs:: chgrp and chown owner and group syntax
* Random sources:: Sources of random data
* Target directory:: Target directory
* Trailing slashes:: Trailing slashes
@@ -644,6 +645,7 @@ name.
* Exit status:: Indicating program success or failure.
* Backup options:: -b -S, in some programs.
* Block size:: BLOCK_SIZE and --block-size, in some programs.
+* Disambiguating names and IDs:: chgrp and chown owner and group syntax
* Random sources:: --random-source, in some programs.
* Target directory:: Specifying a target directory, in some
programs.
* Trailing slashes:: --strip-trailing-slashes, in some programs.
@@ -924,6 +926,46 @@ set. The @option{-h} or @option{--human-readable} option
is equivalent to
@option{--block-size=human-readable}. The @option{--si} option is
equivalent to @option{--block-size=si}.
address@hidden Disambiguating names and IDs
address@hidden chown and chgrp: Disambiguating user names and IDs
address@hidden user names, disambiguating
address@hidden user IDs, disambiguating
address@hidden group names, disambiguating
address@hidden group IDs, disambiguating
address@hidden disambiguating group names and IDs
+
+Since the @var{owner} and @var{group} arguments to @command{chown} and
address@hidden may be specified as names or numeric IDs, there is an
+apparent ambiguity.
+What if a user or group @emph{name} is a string of digits?
address@hidden a number as a user name is common in some environments.}
+Should the command interpret it as a user name or as an ID?
address@hidden requires that @command{chown} and @command{chgrp}
+first attempt to resolve the specified string as a name, and
+only once that fails, then try to interpret it as an ID.
+This is troublesome when you want to specify a numeric ID, say 42,
+and it must work even in a pathological situation where
address@hidden is a user name that maps to some other user ID, say 1000.
+Simply invoking @code{chown 42 F}, will set @file{F}s owner ID to
+1000---not what you intended.
+
+GNU @command{chown} and @command{chgrp} provide a way to work around this,
+that at the same time may result in a significant performance improvement
+by eliminating a database look-up.
+Simply precede each numeric user ID and/or group ID with a @samp{+},
+in order to force its interpretation as an integer:
+
address@hidden
+chown +42 F
+chgrp +$numeric_group_id another-file
+chown +0:+0 /
address@hidden example
+
+GNU @command{chown} and @command{chgrp}
+skip the name look-up process for each @samp{+}-prefixed string,
+because a string containing @samp{+} is never a valid user or group name.
+This syntax is accepted on most common Unix systems, but not on Solaris 10.
+
@node Random sources
@section Sources of random data
@@ -8778,6 +8820,10 @@ owner nor the group is changed.
@end table
+If @var{owner} or @var{group} is intended to represent a numeric user
+or group ID, then you may specify it with a leading @samp{+}.
address@hidden names and IDs}.
+
Some older scripts may still use @samp{.} in place of the @samp{:} separator.
@acronym{POSIX} 1003.1-2001 (@pxref{Standards conformance}) does not
require support for that, but for backward compatibility @acronym{GNU}
@@ -8953,6 +8999,10 @@ or to the group of an existing reference file. Synopsis:
chgrp address@hidden@dots{} @address@hidden | address@hidden@} @address@hidden
@end example
+If @var{group} is intended to represent a
+numeric group ID, then you may specify it with a leading @samp{+}.
address@hidden names and IDs}.
+
The program accepts the following options. Also see @ref{Common options}.
@table @samp
[Prev in Thread] |
Current Thread |
[Next in Thread] |
- Document new syntax: "chown +0:+287 file", "chgrp +99 file",
Jim Meyering <=