Re: chown man page: colon vs. dot

[Paul Eggert]

Dan Jacobson <address@hidden> writes:

> The chown man page talks about colon and dot, but only colon appears
> in examples. Add a clear statement about which is better, history etc.

I think it's better not to mention dot insted.  Dot is no longer
portable (as per POSIX-2001).

I also noticed that the code and documentation doesn't use consistent
terminology ("user ID" or "UID" or "uid" or "user id"?) so I standardized
on "user ID" (the POSIX terminology) and installed this:

2005-04-11  Paul Eggert  <address@hidden>

        * doc/coreutils.texi: For consistency, standardize on "user ID" rather
        than "uid" or "UID" or "user id".  Similarly for "group ID".
        * man/chown.x: Reword to match user manual.
        * man/id.x: Likewise.
        * src/setuidgid.c (usage): Use "user ID", not "UID", and similarly
        for "group ID".
        * src/whoami.c (usage, main): Likewise.

Index: doc/coreutils.texi
===================================================================
RCS file: /fetish/cu/doc/coreutils.texi,v
retrieving revision 1.249
diff -p -u -r1.249 coreutils.texi
--- doc/coreutils.texi  9 Apr 2005 11:56:55 -0000       1.249
+++ doc/coreutils.texi  12 Apr 2005 05:33:19 -0000
@@ -66,7 +66,7 @@
 * head: (coreutils)head invocation.             Output the first part of files.
 * hostid: (coreutils)hostid invocation.         Print numeric host identifier.
 * hostname: (coreutils)hostname invocation.     Print or set system name.
-* id: (coreutils)id invocation.                 Print real/effective uid/gid.
+* id: (coreutils)id invocation.                 Print user identity.
 * install: (coreutils)install invocation.       Copy and change attributes.
 * join: (coreutils)join invocation.             Join lines on a common field.
 * kill: (coreutils)kill invocation.             Send a signal to processes.
@@ -100,7 +100,7 @@
 * split: (coreutils)split invocation.           Split into fixed-size pieces.
 * stat: (coreutils)stat invocation.             Report file(system) status.
 * stty: (coreutils)stty invocation.             Print/change terminal settings.
-* su: (coreutils)su invocation.                 Modify user and group id.
+* su: (coreutils)su invocation.                 Modify user and group ID.
 * sum: (coreutils)sum invocation.               Print traditional checksum.
 * sync: (coreutils)sync invocation.             Synchronize memory and disk.
 * tac: (coreutils)tac invocation.               Reverse files.
@@ -120,7 +120,7 @@
 * vdir: (coreutils)vdir invocation.             List directories verbosely.
 * wc: (coreutils)wc invocation.                 Line, word, and byte counts.
 * who: (coreutils)who invocation.               Print who is logged in.
-* whoami: (coreutils)whoami invocation.         Print effective user id.
+* whoami: (coreutils)whoami invocation.         Print effective user ID.
 * yes: (coreutils)yes invocation.               Print a string indefinitely.
 @end direntry
 
@@ -379,9 +379,9 @@ Working context
 
 User information
 
-* id invocation::                Print real and effective uid and gid
+* id invocation::                Print user identity
 * logname invocation::           Print current login name
-* whoami invocation::            Print effective user id
+* whoami invocation::            Print effective user ID
 * groups invocation::            Print group names a user is in
 * users invocation::             Print login names of users currently logged in
 * who invocation::               Print who is currently logged in
@@ -409,7 +409,7 @@ Modified command invocation
 * env invocation::               Run a command in a modified environment
 * nice invocation::              Run a command with modified scheduling 
priority
 * nohup invocation::             Run a command immune to hangups
-* su invocation::                Run a command with substitute user and group 
id
+* su invocation::                Run a command with substitute user and group 
ID
 
 Process control
 
@@ -5652,8 +5652,9 @@ is a printing character (e.g., @samp{+})
 @opindex -n
 @opindex --numeric-uid-gid
 @cindex numeric uid and gid
address@hidden numeric user and group IDs
 Produce long format directory listings, but
-display numeric UIDs and GIDs instead of the owner and group names.
+display numeric user and group IDs instead of the owner and group names.
 
 @item -o
 @opindex -o
@@ -6494,7 +6495,8 @@ to @option{--preserve=mode,ownership,tim
 
 In the absence of this option, each destination file is created with the
 permissions of the corresponding source file, minus the bits set in the
-umask and minus the set-user-id and set-group-id bits.  @xref{File 
permissions}.
+umask and minus the set-user-ID and set-group-ID bits.
address@hidden permissions}.
 
 @itemx @address@hidden@var{attribute_list}}
 @cindex file information, preserving
@@ -7002,7 +7004,7 @@ gives directories that it creates the de
 @cindex group ownership of installed files, setting
 Set the group ownership of installed files or directories to
 @var{group}.  The default is the process's current group.  @var{group}
-may be either a group name or a numeric group id.
+may be either a group name or a numeric group ID.
 
 @item -m @var{mode}
 @itemx address@hidden
@@ -8072,8 +8074,8 @@ The @command{unlink} command honors the 
 @cindex attributes, file
 
 A file is not merely its contents, a name, and a file type
-(@pxref{Special file types}).  A file also has an owner (a userid), a
-group (a group id), permissions (what the owner can do with the file,
+(@pxref{Special file types}).  A file also has an owner (a user ID), a
+group (a group ID), permissions (what the owner can do with the file,
 what people in the group can do, and what everyone else can do), various
 timestamps, and other information.  Collectively, we call these a file's
 @dfn{attributes}.
@@ -8116,13 +8118,13 @@ Specifically:
 
 @table @var
 @item owner
-If only an @var{owner} (a user name or numeric user id) is given, that
+If only an @var{owner} (a user name or numeric user ID) is given, that
 user is made the owner of each given file, and the files' group is not
 changed.
 
 @item address@hidden:}group
 If the @var{owner} is followed by a colon and a @var{group} (a
-group name or numeric group id), with no spaces between them, the group
+group name or numeric group ID), with no spaces between them, the group
 ownership of the files is changed as well (to @var{group}).
 
 @item address@hidden:}
@@ -8190,7 +8192,7 @@ by @var{old-owner}.  @var{old-owner} has
 described above.
 This option is useful primarily from a security standpoint in that
 it narrows considerably the window of potential abuse.
-For example, to reflect a UID numbering change for one user's files
+For example, to reflect a user ID numbering change for one user's files
 without an option like this, @code{root} might run
 
 @smallexample
@@ -8308,7 +8310,7 @@ chown -hR root /u
 @cindex changing group ownership
 
 @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)
+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:
 
 @example
@@ -9674,8 +9676,8 @@ These options test for particular access
 
 @item -g @var{file}
 @opindex -g
address@hidden set-group-id check
-True if @var{file} exists and has its set-group-id bit set.
address@hidden set-group-ID check
+True if @var{file} exists and has its set-group-ID bit set.
 
 @item -k @var{file}
 @opindex -k
@@ -9689,8 +9691,8 @@ True if @var{file} exists and read permi
 
 @item -u @var{file}
 @opindex -u
address@hidden set-user-id check
-True if @var{file} exists and has its set-user-id bit set.
address@hidden set-user-ID check
+True if @var{file} exists and has its set-user-ID bit set.
 
 @item -w @var{file}
 @opindex -w
@@ -9705,13 +9707,13 @@ True if @var{file} exists and execute pe
 
 @item -O @var{file}
 @opindex -O
address@hidden owned by effective uid check
-True if @var{file} exists and is owned by the current effective user id.
address@hidden owned by effective user ID check
+True if @var{file} exists and is owned by the current effective user ID.
 
 @item -G @var{file}
 @opindex -G
address@hidden owned by effective gid check
-True if @var{file} exists and is owned by the current effective group id.
address@hidden owned by effective group ID check
+True if @var{file} exists and is owned by the current effective group ID.
 
 @end table
 
@@ -11135,9 +11137,9 @@ This section describes commands that pri
 logins, groups, and so forth.
 
 @menu
-* id invocation::               Print real and effective uid and gid.
+* id invocation::               Print user identity.
 * logname invocation::          Print current login name.
-* whoami invocation::           Print effective user id.
+* whoami invocation::           Print effective user ID.
 * groups invocation::           Print group names a user is in.
 * users invocation::            Print login names of users currently logged in.
 * who invocation::              Print who is currently logged in.
@@ -11145,12 +11147,12 @@ logins, groups, and so forth.
 
 
 @node id invocation
address@hidden @command{id}: Print real and effective uid and gid
address@hidden @command{id}: Print user identity
 
 @pindex id
address@hidden real uid and gid, printing
address@hidden effective uid and gid, printing
address@hidden printing real and effective uid and gid
address@hidden real user and group IDs, printing
address@hidden effective user and group IDs, printing
address@hidden printing real and effective user and group IDs
 
 @command{id} prints information about the given user, or the process
 running it if no user is specified.  Synopsis:
@@ -11159,9 +11161,9 @@ running it if no user is specified.  Syn
 id address@hidden@dots{} address@hidden
 @end example
 
-By default, it prints the real user id, real group id, effective user id
-if different from the real user id, effective group id if different from
-the real group id, and supplemental group ids.
+By default, it prints the real user ID, real group ID, effective user ID
+if different from the real user ID, effective group ID if different from
+the real group ID, and supplemental group IDs.
 
 Each of these numeric values is preceded by an identifying string and
 followed by the corresponding user or group name in parentheses.
@@ -11174,13 +11176,13 @@ Also see @ref{Common options}.
 @itemx --group
 @opindex -g
 @opindex --group
-Print only the group id.
+Print only the group ID.
 
 @item -G
 @itemx --groups
 @opindex -G
 @opindex --groups
-Print only the group id and the supplementary groups.
+Print only the group ID and the supplementary groups.
 
 @item -n
 @itemx --name
@@ -11193,14 +11195,14 @@ Print the user or group name instead of 
 @itemx --real
 @opindex -r
 @opindex --real
-Print the real, instead of effective, user or group id.  Requires
+Print the real, instead of effective, user or group ID.  Requires
 @option{-u}, @option{-g}, or @option{-G}.
 
 @item -u
 @itemx --user
 @opindex -u
 @opindex --user
-Print only the user id.
+Print only the user ID.
 
 @end table
 
@@ -11229,14 +11231,14 @@ options}.
 
 
 @node whoami invocation
address@hidden @command{whoami}: Print effective user id
address@hidden @command{whoami}: Print effective user ID
 
 @pindex whoami
address@hidden effective UID, printing
address@hidden printing the effective UID
address@hidden effective user ID, printing
address@hidden printing the effective user ID
 
 @command{whoami} prints the user name associated with the current
-effective user id.  It is equivalent to the command @samp{id -un}.
+effective user ID.  It is equivalent to the command @samp{id -un}.
 
 The only options are @option{--help} and @option{--version}.  @xref{Common
 options}.
@@ -12250,7 +12252,7 @@ user, etc.
 * env invocation::              Modify environment variables.
 * nice invocation::             Modify scheduling priority.
 * nohup invocation::            Immunize to hangups.
-* su invocation::               Modify user and group id.
+* su invocation::               Modify user and group ID.
 @end menu
 
 
@@ -12570,17 +12572,17 @@ the exit status of @var{command} otherwi
 
 
 @node su invocation
address@hidden @command{su}: Run a command with substitute user and group id
address@hidden @command{su}: Run a command with substitute user and group ID
 
 @pindex su
address@hidden substitute user and group ids
address@hidden user id, switching
address@hidden substitute user and group IDs
address@hidden user ID, switching
 @cindex super-user, becoming
 @cindex root, becoming
 
 @command{su} allows one user to temporarily become another user.  It runs a
 command (often an interactive shell) with the real and effective user
-id, group id, and supplemental groups of a given @var{user}.  Synopsis:
+ID, group ID, and supplemental groups of a given @var{user}.  Synopsis:
 
 @example
 su address@hidden@dots{} address@hidden address@hidden@dots{}]
@@ -12593,7 +12595,7 @@ If no @var{user} is given, the default i
 The shell to use is taken from @var{user}'s @code{passwd} entry, or
 @file{/bin/sh} if none is specified there.  If @var{user} has a
 password, @command{su} prompts for the password unless run by a user with
-effective user id of zero (the super-user).
+effective user ID of zero (the super-user).
 
 @vindex HOME
 @vindex SHELL
@@ -12759,7 +12761,7 @@ valid signal, but can be used to test wh
 specify processes to which a signal could be sent.
 
 If @var{pid} is positive, the signal is sent to the process with the
-process id @var{pid}.  If @var{pid} is zero, the signal is sent to all
+process ID @var{pid}.  If @var{pid} is zero, the signal is sent to all
 processes in the process group of the current process.  If @var{pid}
 is @minus{}1, the signal is sent to all processes for which the user has
 permission to send a signal.  If @var{pid} is less than @minus{}1, the signal
Index: man/chown.x
===================================================================
RCS file: /fetish/cu/man/chown.x,v
retrieving revision 1.3
diff -p -u -r1.3 chown.x
--- man/chown.x 13 Oct 2001 16:50:59 -0000      1.3
+++ man/chown.x 12 Apr 2005 05:33:19 -0000
@@ -5,18 +5,19 @@ This manual page
 documents the GNU version of
 .BR chown .
 .B chown
-changes the user and/or group ownership of each given file, according
-to its first non-option argument, which is interpreted as follows.  If
-only a user name (or numeric user ID) is given, that user is made the
+changes the user and/or group ownership of each given file.  If
+only an owner (a user name or numeric user ID) is given, that user is made the
 owner of each given file, and the files' group is not changed.  If the
-user name is followed by a colon or dot and a group name (or numeric group ID),
+owner is followed by a colon and a group name (or numeric group ID),
 with no spaces between them, the group ownership of the files is
-changed as well.  If a colon or dot but no group name follows the user name,
+changed as well.  If a colon but no group name follows the user name,
 that user is made the owner of the files and the group of the files is
-changed to that user's login group.  If the colon or dot and group are given,
-but the user name is omitted, only the group of the files is changed;
+changed to that user's login group.  If the colon and group are given,
+but the owner is omitted, only the group of the files is changed;
 in this case,
 .B chown
 performs the same function as
 .BR chgrp .
+If only a colon is given, or if the entire operand is empty, neither the
+owner nor the group is changed.
 .SH OPTIONS
Index: man/id.x
===================================================================
RCS file: /fetish/cu/man/id.x,v
retrieving revision 1.2
diff -p -u -r1.2 id.x
--- man/id.x    2 Nov 1999 14:07:36 -0000       1.2
+++ man/id.x    12 Apr 2005 05:33:19 -0000
@@ -1,4 +1,4 @@
 [NAME]
-id \- print real and effective UIDs and GIDs
+id \- print user identity
 [DESCRIPTION]
 .\" Add any additional description here
Index: src/setuidgid.c
===================================================================
RCS file: /fetish/cu/src/setuidgid.c,v
retrieving revision 1.13
diff -p -u -r1.13 setuidgid.c
--- src/setuidgid.c     17 Nov 2004 00:56:25 -0000      1.13
+++ src/setuidgid.c     12 Apr 2005 05:33:19 -0000
@@ -57,7 +57,7 @@ Usage: %s USERNAME COMMAND [ARGUMENT]...
       fputs (_("\
 Drop any supplemental groups, assume the user-ID and group-ID of\n\
 the specified USERNAME, and run COMMAND with any specified ARGUMENTs.\n\
-Exit with status 111 if unable to assume the required UID and GID.\n\
+Exit with status 111 if unable to assume the required user and group ID.\n\
 Otherwise, exit with the exit status of COMMAND.\n\
 This program is useful only when run by root (UID=0).\n\
 \n\
Index: src/whoami.c
===================================================================
RCS file: /fetish/cu/src/whoami.c,v
retrieving revision 1.46
diff -p -u -r1.46 whoami.c
--- src/whoami.c        6 Mar 2005 16:19:44 -0000       1.46
+++ src/whoami.c        12 Apr 2005 05:33:19 -0000
@@ -49,7 +49,7 @@ usage (int status)
     {
       printf (_("Usage: %s [OPTION]...\n"), program_name);
       fputs (_("\
-Print the user name associated with the current effective user id.\n\
+Print the user name associated with the current effective user ID.\n\
 Same as id -un.\n\
 \n\
 "), stdout);
@@ -92,7 +92,7 @@ main (int argc, char **argv)
       puts (pw->pw_name);
       exit (EXIT_SUCCESS);
     }
-  fprintf (stderr, _("%s: cannot find username for UID %lu\n"),
+  fprintf (stderr, _("%s: cannot find name for user ID %lu\n"),
           program_name, (unsigned long int) uid);
   exit (EXIT_FAILURE);
 }