More jdf changes.

1 files changed, 176 insertions, 137 deletions

diff --git a/winsup/utils/utils.sgml b/winsup/utils/utils.sgml
index 2cbec03bb..badd89be2 100644
--- a/winsup/utils/utils.sgml
+++ b/winsup/utils/utils.sgml
@@ -268,12 +268,12 @@ The format for ACL output is as follows:
 
 <screen>
 Usage: kill [-f] [-signal] [-s signal] pid1 [pid2 ...]
-kill -l [signal]
--f, --force     force, using win32 interface if necessary
--l, --list      print a list of signal names
--s, --signal    send signal (use kill --list for a list)
--h, --help      output usage information and exit
--v, --version   output version information and exit
+       kill -l [signal]
+ -f, --force     force, using win32 interface if necessary
+ -l, --list      print a list of signal names
+ -s, --signal    send signal (use kill --list for a list)
+ -h, --help      output usage information and exit
+ -v, --version   output version information and exit
 </screen>
 
 <para>The <command>kill</command> program allows you to send arbitrary
@@ -388,9 +388,11 @@ One of `-l' or `-d' must be given on NT/W2K.
 <para>The <command>mkgroup</command> program can be used to help
 configure your Windows system to be more UNIX-like by creating an
 initial <filename>/etc/group</filename> substitute (some commands need this
-file) from your system information. It only works on NT.
-To initially set up your machine,
-you'd do something like this:</para>
+file) from your system information. It only works on the NT series
+(Windows NT, 2000, and XP). <command>mkgroup</command> does not work on 
+the Win9x series (Windows 95, 98, and Me) because they lack the security model 
+to support it. To initially set up your machine, you'd do something like 
+this:</para>
 
 <example><title>Setting up the groups file</title>
 <screen>
@@ -405,7 +407,16 @@ for it to have the new information.</para>
 
 <para>The <literal>-d</literal> and <literal>-l</literal> options
 allow you to specify where the information comes from, either the
-local machine or the default (or given) domain.</para>
+local machine or the default (or given) domain.  The <literal>-o</literal>
+option allows for special cases (such as multiple domains) where the GIDs 
+might match otherwise. The <literal>-s</literal>
+option omits the NT Security Identifier (SID).  For more information on 
+SIDs, see <Xref Linkend="ntsec"> in the Cygwin User's Guide.  The
+<literal>-u</literal> option causes <command>mkgroup</command> to 
+enumerate the users for each group, placing the group members in the 
+gr_mem (last) field.  Note that this can greatly increase
+the time for <command>mkgroup</command> to run in a large domain.
+</para>
 
 </sect2>
 
@@ -438,8 +449,11 @@ One of `-l', `-d' or `-g' must be given on NT/W2K.
 <para>The <command>mkpasswd</command> program can be used to help
 configure your Windows system to be more UNIX-like by creating an
 initial <filename>/etc/passwd</filename> substitute (some commands
-need this file) from your system information. It only works on NT.
-To initially set up your machine, you'd do something like this:</para>
+need this file) from your system information. It only works on the NT series
+(Windows NT, 2000, and XP). <command>mkpasswd</command> does not work on 
+the Win9x series (Windows 95, 98, and Me) because they lack the security model 
+to support it. To initially set up your machine, you'd do something like 
+this:</para>
 
 <example><title>Setting up the passwd file</title>
 <screen>
@@ -454,84 +468,28 @@ for it to have the new information.</para>
 
 <para>The <literal>-d</literal> and <literal>-l</literal> options
 allow you to specify where the information comes from, either the
-local machine or the default (or given) domain.</para>
-
-</sect2>
-
-<sect2 id="passwd"><title>passwd</title>
-
+local machine or the default (or given) domain.  The <literal>-o</literal>
+option allows for special cases (such as multiple domains) where the UIDs
+might match otherwise.  The <literal>-g</literal> option creates a local
+user that corresponds to each local group. This is because NT assigns groups
+file ownership.  The <literal>-m</literal> option bypasses the current
+mount table so that, for example, two users who have a Windows home 
+directory of H: could mount them differently.  The <literal>-s</literal>
+option omits the NT Security Identifier (SID).  For more information on
+SIDs, see <Xref Linkend="ntsec"> in the Cygwin User's Guide.  The
+<literal>-p</literal> option causes <command>mkpasswd</command> to
+use a prefix other than <literal>/home/</literal>. For example, this command:
+
+<example><title>Using an alternate home root</title>
 <screen>
-Usage: passwd (-l|-u|-S) [USER]
-       passwd [-i NUM] [-n MINDAYS] [-x MAXDAYS] [-L LEN]
-
-User operations:
- -l, --lock      lock USER's account
- -u, --unlock    unlock USER's account
- -S, --status    display password status for USER (locked, expired, etc.)
-
-System operations:
- -i, --inactive  set NUM of days before inactive accounts are disabled
-                 (inactive accounts are those with expired passwords)
- -n, --minage    set system minimum password age to MINDAYS
- -x, --maxage    set system maximum password age to MAXDAYS
- -L, --length    set system minimum password length to LEN
-
-Other options:
- -h, --help      output usage information and exit
- -v, --version   output version information and exit
+<prompt>$</prompt> <userinput>mkpasswd -l -p "$(cygpath -H)" &gt; /etc/passwd</userinput>
 </screen>
+</example>
 
-<para> <command>passwd</command> changes passwords for user accounts.
-A normal user may only change the password for their own account,
-the administrators may change the password for any account.
-<command>passwd</command> also changes account information, such as
-password expiry dates and intervals.</para>
-
-<para>Password changes: The user is first prompted for their old
-password, if one is present.  This password is then encrypted and
-compared against the stored password.  The user has only one chance to
-enter the correct password.  The administrators are permitted to
-bypass this step so that forgotten passwords may be changed.</para>
-
-<para>The user is then prompted for a replacement password.
-<command>passwd</command> will prompt again and compare the second entry
-against the first.  Both entries are require to match in order for the
-password to be changed.</para>
-
-<para>After the password has been entered, password aging information
-is checked to see if the user is permitted to change their password
-at this time.  If not, <command>passwd</command> refuses to change the
-password and exits.</para>
-
-<para>Password expiry and length: The password aging information may be
-changed by the administrators with the <literal>-x</literal>,
-<literal>-n</literal> and <literal>-i</literal> options.  The
-<literal>-x</literal> option is used to set the maximum number of days
-a password remains valid.  After <emphasis>max</emphasis> days, the
-password is required to be changed.  The <literal>-n</literal> option is
-used to set the minimum number of days before a password may be changed.
-The user will not be permitted to change the password until
-<emphasis>min</emphasis> days have elapsed.  The <literal>-i</literal>
-option is used to disable an account after the password has been expired
-for a number of days.  After a user account has had an expired password
-for <emphasis>inact</emphasis> days, the user may no longer sign on to
-the account. Allowed values for the above options are 0 to 999.  The
-<literal>-L</literal> option sets the minimum length of allowed passwords
-for users, which doesn't belong to the administrators group, to
-<emphasis>len</emphasis> characters.  Allowed values for the minimum
-password length are 0 to 14.  In any of the above cases, a value of 0
-means `no restrictions'.</para>
-
-<para>Account maintenance: User accounts may be locked and unlocked with the
-<literal>-l</literal> and <literal>-u</literal> flags.  The
-<literal>-l</literal> option disables an account.  The <literal>-u</literal>
-option re-enables an account.</para>
-
-<para>The account status may be given with the <literal>-S</literal>
-option.  The status information is self explanatory.</para>
-
-<para>Limitations: Users may not be able to change their password on
-some systems.</para>
+would put local users' home directories in the Windows 'Profiles' directory. 
+The <literal>-u</literal> option allows <command>mkpasswd</command> to 
+search for a specific username, greatly reducing the amount of time it 
+takes in a large domain. 
 
 </sect2>
 
@@ -574,15 +532,16 @@ will display the current mount table for you.</para>
 <example>
 <title>Displaying the current set of mount points</title>
 <screen>
-<prompt>c:\cygnus\&gt;</prompt> <userinput>mount</userinput>
-Device           Directory           Type        Flags
-D:               /d                  user        textmode
-C:               /                   system      textmode
+<prompt>c:\cygwin\&gt;</prompt> <userinput>mount</userinput>
+c:\cygwin\bin on /usr/bin type system (binmode)
+c:\cygwin\lib on /usr/lib type system (binmode)
+c:\cygwin on / type system (binmode)
+c: on /c type user (binmode,noumount)
+d: on /d type user (binmode,noumount)
 </screen>
 </example>
 
-<para>In this example, the C
-drive is the POSIX root and D drive is mapped to
+<para>In this example, c:\cygwin is the POSIX root and D drive is mapped to
 <filename>/d</filename>.  Note that in this case, the root mount is a
 system-wide mount point that is visible to all users running Cygwin
 programs, whereas the <filename>/d</filename> mount is only visible
@@ -591,31 +550,23 @@ to the current user.</para>
 <para>The <command>mount</command> utility is also the mechanism for
 adding new mounts to the mount table.  The following example
 demonstrates how to mount the directory
-<filename>C:\cygnus\cygwin-b20\H-i586-cygwin32\bin</filename>
-to <filename>/bin</filename> and the network directory
 <filename>\\pollux\home\joe\data</filename> to <filename>/data</filename>.
-<filename>/bin</filename> is assumed to already exist.</para>
+</para>
 
 <example>
 <title>Adding mount points</title>
 <screen>
-<prompt>c:\cygnus\&gt;</prompt> <userinput>ls /bin /data</userinput>
+<prompt>c:\cygwin\&gt;</prompt> <userinput>ls /data</userinput>
 ls: /data: No such file or directory
-<prompt>c:\cygnus\&gt;</prompt> <userinput>mount C:\cygnus\cygwin-b20\H-i586-cygwin32\bin /bin</userinput>
-<prompt>c:\cygnus\&gt;</prompt> <userinput>mount \\pollux\home\joe\data /data</userinput>
-Warning: /data does not exist!
-<prompt>c:\cygnus\&gt;</prompt> <userinput>mount</userinput>
-Device           Directory           Type        Flags
-\\pollux\home\joe\data   /data       user        textmode
-C:\cygnus\cygwin-b20\H-i586-cygwin32\bin   /bin   user   textmode
-D:               /d                  user        textmode
-\\.\tape1:       /dev/st1            user        textmode
-\\.\tape0:       /dev/st0            user        textmode
-\\.\b:           /dev/fd1            user        textmode
-\\.\a:           /dev/fd0            user        textmode
-C:               /                   system      textmode
-<prompt>c:\cygnus\&gt;</prompt> <userinput>ls /bin/sh</userinput>
-/bin/sh
+<prompt>c:\cygwin\&gt;</prompt> <userinput>mount \\pollux\home\joe\data /data</userinput>
+mount: warning - /data does not exist!
+<prompt>c:\cygwin\&gt;</prompt> <userinput>mount</userinput>
+\\pollux\home\joe\data on /data type sytem (binmode)
+c:\cygwin\bin on /usr/bin type system (binmode)
+c:\cygwin\lib on /usr/lib type system (binmode)
+c:\cygwin on / type system (binmode)
+c: on /c type user (binmode,noumount)
+d: on /d type user (binmode,noumount)
 </screen>
 </example>
 
@@ -624,7 +575,7 @@ command shell in the previous example.  In many Unix shells, including
 bash, it is legal and convenient to use the forward "/" in Win32
 pathnames since the "\" is the shell's escape character. </para>
 
-<para>The "-s" flag to <command>mount</command> is used to add a mount
+<para>The <literal>-s</literal> flag to <command>mount</command> is used to add a mount
 in the system-wide mount table used by all Cygwin users on the system,
 instead of the user-specific one.  System-wide mounts are displayed
 by <command>mount</command> as being of the "system" type, as is the
@@ -634,25 +585,38 @@ permitted to modify the system-wide mount table.</para>
 
 <para>Note that a given POSIX path may only exist once in the user
 table and once in the global, system-wide table.  Attempts to replace
-the mount will fail with a busy error.  The "-f" (force) flag causes
+the mount will fail with a busy error.  The <literal>-f</literal> (force) flag causes
 the old mount to be silently replaced with the new one.  It will also
 silence warnings about the non-existence of directories at the Win32
 path location.</para>
 
-<para>The "-b" flag is used to instruct Cygwin to treat binary and
+<para>The <literal>-b</literal> flag is used to instruct Cygwin to treat binary and
 text files in the same manner by default.  Binary mode mounts are
 marked as "binmode" in the Flags column of <command>mount</command>
 output.  By default, mounts are in text mode ("textmode" in the Flags
 column).</para>
 
-<para>The "-x" flag is used to instruct Cygwin that the mounted file
-is "executable".  If the "-x" flag is used with a directory then
-all files in the directory are executable.  Files ending in certain
-extensions (.exe, .com, .bat, .cmd) are assumed to be executable
-by default.  Files whose first two characters begin with '#!' are
-also considered to be executable.  This option allows other files
-to be marked as executable and avoids the overhead of opening each
-file to check for a '#!'.</para>
+<para>Normally, files ending in certain extensions (.exe, .com, .bat, .cmd) 
+are assumed to be executable.  Files whose first two characters begin with 
+'#!' are also considered to be executable.  
+The <literal>-x</literal> flag is used to instruct Cygwin that the 
+mounted file is "executable".  If the <literal>-x</literal> flag is used 
+with a directory then all files in the directory are executable.  
+This option allows other files to be marked as executable and avoids the 
+overhead of opening each file to check for a '#!'.  The <literal>-X</literal>
+option is very similar to <literal>-x</literal>, but also prevents Cygwin
+from setting up commands and environment variables for a normal Windows 
+program, adding another small performance gain.  The opposite of these 
+flags is the <literal>-E</literal> flag, which means that no files should be 
+marked as executable.  </para>
+
+<para>
+The <literal>-m</literal> option causes the <command>mount</command> utility
+to output a series of commands that could recreate both user and system mount 
+points. You can save this output as a backup when experimenting with the
+mount table. It also makes moving your settings to a different machine
+much easier.
+</para>
 
 </sect3>
 
@@ -662,29 +626,27 @@ file to check for a '#!'.</para>
 from a particular Win32 path to a POSIX one, Cygwin will, instead,
 convert to a POSIX path using a default mount point:
 <filename>/cygdrive</filename>.  For example, if Cygwin accesses
-<filename>Z:\foo</filename> and the Z drive is not currently in the
-mount table, then <filename>Z:\</filename> will be accessible as
-<filename>/cygdrive/Z</filename>.  The default prefix of
-<filename>/cygdrive</filename> may be changed via the
-<Xref Linkend="mount"> command.</para>
-
-<para>The <command>mount</command> utility can be used to change this
-default automount prefix through the use of the
-"--change-cygdrive-prefix" flag.  In the following example, we will
+<filename>z:\foo</filename> and the z drive is not currently in the
+mount table, then <filename>z:\</filename> will be accessible as
+<filename>/cygdrive/z</filename>.  The <command>mount</command> utility 
+can be used to change this default automount prefix through the use of the
+"--change-cygdrive-prefix" option.  In the following example, we will
 set the automount prefix to <filename>/</filename>:</para>
 
 <example>
 <title>Changing the default prefix</title>
 <screen>
-<prompt>c:\cygnus\&gt;</prompt> <userinput>mount --change-cygdrive-prefix /</userinput>
+<prompt>c:\cygwin\&gt;</prompt> <userinput>mount --change-cygdrive-prefix /</userinput>
 </screen>
 </example>
 
 <para>Note that you if you set a new prefix in this manner, you can
-specify the "-s" flag to make this the system-wide default prefix.  By
-default, the cygdrive-prefix applies only to the current user.  In the
-same way, you can specify the "-b" flag such that all new automounted
-filesystems default to binary mode file accesses.</para>
+specify the <literal>-s</literal> flag to make this the system-wide default 
+prefix.  By default, the cygdrive-prefix applies only to the current user.  
+You can always see the user and system cygdrive prefixes with the 
+<literal>-p</literal> option.  Using the <literal>-b</literal>
+flag with <literal>--change-cygdrive-prefix</literal> makes all new 
+automounted filesystems default to binary mode file accesses.</para>
 
 </sect3>
 
@@ -724,6 +686,83 @@ find <filename>mtpt</filename>.
 
 </sect2>
 
+<sect2 id="passwd"><title>passwd</title>
+
+<screen>
+Usage: passwd (-l|-u|-S) [USER]
+       passwd [-i NUM] [-n MINDAYS] [-x MAXDAYS] [-L LEN]
+
+User operations:
+ -l, --lock      lock USER's account
+ -u, --unlock    unlock USER's account
+ -S, --status    display password status for USER (locked, expired, etc.)
+
+System operations:
+ -i, --inactive  set NUM of days before inactive accounts are disabled
+                 (inactive accounts are those with expired passwords)
+ -n, --minage    set system minimum password age to MINDAYS
+ -x, --maxage    set system maximum password age to MAXDAYS
+ -L, --length    set system minimum password length to LEN
+
+Other options:
+ -h, --help      output usage information and exit
+ -v, --version   output version information and exit
+</screen>
+
+<para> <command>passwd</command> changes passwords for user accounts.
+A normal user may only change the password for their own account,
+the administrators may change the password for any account.
+<command>passwd</command> also changes account information, such as
+password expiry dates and intervals.</para>
+
+<para>Password changes: The user is first prompted for their old
+password, if one is present.  This password is then encrypted and
+compared against the stored password.  The user has only one chance to
+enter the correct password.  The administrators are permitted to
+bypass this step so that forgotten passwords may be changed.</para>
+
+<para>The user is then prompted for a replacement password.
+<command>passwd</command> will prompt again and compare the second entry
+against the first.  Both entries are require to match in order for the
+password to be changed.</para>
+
+<para>After the password has been entered, password aging information
+is checked to see if the user is permitted to change their password
+at this time.  If not, <command>passwd</command> refuses to change the
+password and exits.</para>
+
+<para>Password expiry and length: The password aging information may be
+changed by the administrators with the <literal>-x</literal>,
+<literal>-n</literal> and <literal>-i</literal> options.  The
+<literal>-x</literal> option is used to set the maximum number of days
+a password remains valid.  After <emphasis>max</emphasis> days, the
+password is required to be changed.  The <literal>-n</literal> option is
+used to set the minimum number of days before a password may be changed.
+The user will not be permitted to change the password until
+<emphasis>min</emphasis> days have elapsed.  The <literal>-i</literal>
+option is used to disable an account after the password has been expired
+for a number of days.  After a user account has had an expired password
+for <emphasis>inact</emphasis> days, the user may no longer sign on to
+the account. Allowed values for the above options are 0 to 999.  The
+<literal>-L</literal> option sets the minimum length of allowed passwords
+for users, which doesn't belong to the administrators group, to
+<emphasis>len</emphasis> characters.  Allowed values for the minimum
+password length are 0 to 14.  In any of the above cases, a value of 0
+means `no restrictions'.</para>
+
+<para>Account maintenance: User accounts may be locked and unlocked with the
+<literal>-l</literal> and <literal>-u</literal> flags.  The
+<literal>-l</literal> option disables an account.  The <literal>-u</literal>
+option re-enables an account.</para>
+
+<para>The account status may be given with the <literal>-S</literal>
+option.  The status information is self explanatory.</para>
+
+<para>Limitations: Users may not be able to change their password on
+some systems.</para>
+
+</sect2>
+
 <sect2 id="ps"><title>ps</title>
 
 <screen>