* Revamp documentation for Cygwin 1.7, part 1.

16 files changed, 917 insertions, 755 deletions

diff --git a/winsup/doc/ChangeLog b/winsup/doc/ChangeLog
index e3b2f23e1..aa0f1800b 100644
--- a/winsup/doc/ChangeLog
+++ b/winsup/doc/ChangeLog
@@ -1,3 +1,7 @@
+2008-07-17  Corinna Vinschen  <corinna@vinschen.de>
+
+	* Revamp documentation for Cygwin 1.7, part 1.
+
 2008-07-01  Christopher Faylor  <me+cygwin@cgf.cx>
 
 	* Makefile.in: Temporarily add ability to generate pdfs.
diff --git a/winsup/doc/cygserver.sgml b/winsup/doc/cygserver.sgml
index 27e538b2a..2f34bbbd7 100644
--- a/winsup/doc/cygserver.sgml
+++ b/winsup/doc/cygserver.sgml
@@ -41,6 +41,7 @@
 </para>
 
 <itemizedlist spacing="compact">
+<listitem>
   <screen>-f, --config-file &lt;file&gt;</screen>
   <para>  
     Use &lt;file&gt; as configuration file instead of the default configuration
@@ -52,6 +53,7 @@
     This option has no counterpart in the configuration file, for obvious
    reasons.
   </para>
+</listitem>
 <listitem>
   <screen>-c, --cleanup-threads &lt;num&gt;</screen>
   <para>  
@@ -96,8 +98,7 @@
   <screen>-y, --syslog</screen>
   <para>  
     Force logging to the system log.  This is the default, if stderr is not
-    connected to a tty, e. g. redirected to a file.  Note, that on 9x/Me
-    systems the syslog is faked by a file C:\CYGWIN_SYSLOG.TXT.
+    connected to a tty, e. g. redirected to a file.
     Configuration file option:  kern.log.syslog
   </para>
 </listitem>
@@ -143,8 +144,8 @@
   <screen>-S, --shutdown</screen>
   <para>  
     Shutdown a running daemon and exit.  Other methods are sending a SIGHUP
-    to the Cygserver PID or, if running as service under NT, calling
-    `net stop cygserver' or `cygrunsrv -E cygserver'.
+    to the Cygserver PID or, if running as service, calling `net stop
+    cygserver' or `cygrunsrv -E cygserver'.
   </para>
 </listitem>
 <listitem>
@@ -168,22 +169,16 @@
 <para>
   Before you run Cygserver for the first time, you should run the
   /usr/bin/cygserver-config script once.  It creates the default
-  configuration file and, upon request, installs Cygserver as service
-  when running under NT.  The script only performs a default install,
-  with no further options given to Cygserver when running as service.
-  Due to the wide configurability by changing the configuration file,
-  that's typically not necessary.
-</para>
-<para>
-  On Windows 9x/Me, just start Cygserver in any console window.  It's
-  advisable to redirect stderr to a file of choice (e. g.
-  /var/log/cygserver.log) and to use the -e and -Y options or the
-  set the appropriate settings in the configuration file (see below).
+  configuration file and, upon request, installs Cygserver as service.
+  The script only performs a default install, with no further options
+  given to Cygserver when running as service.  Due to the wide
+  configurability by changing the configuration file, that's typically
+  not necessary.
 </para>
 <para>
-  On Windows NT/2000/XP or 2003, you should always run Cygserver as a
-  service under LocalSystem account.  This is the way it is installed
-  for you by the /usr/bin/cygserver-config script.
+  You should always run Cygserver as a service under LocalSystem account. 
+  This is the way it is installed for you by the /usr/bin/cygserver-config
+  script.
 </para>
 
 </sect2>
diff --git a/winsup/doc/cygwin-ug.in.sgml b/winsup/doc/cygwin-ug.in.sgml
index 64869fdce..65902e903 100644
--- a/winsup/doc/cygwin-ug.in.sgml
+++ b/winsup/doc/cygwin-ug.in.sgml
@@ -1,10 +1,12 @@
 <?xml version="1.0"?>
 <!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"[
-  <!ENTITY cygnus-copyright "<year>1999,2000,2001</year>
+  <!ENTITY cygnus-copyright "<year>1999,2000,2001,2002,2003,2004,2005,2006,2007,2008</year>
   <holder>Red Hat, Inc.</holder>">
   <!ENTITY cygnus-code-copyright "
 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
-Copyright (C) 1998, 1999, 2000, 2001 Red Hat, Inc.
+Copyright (C) 1998, 1999, 2000, 2001, 2002,
+              2003, 2004, 2005, 2006, 2007,
+	      2008 Red Hat, Inc.
 
 This is copyrighted software that may only
 be reproduced, modified, or distributed
diff --git a/winsup/doc/cygwinenv.sgml b/winsup/doc/cygwinenv.sgml
index dd57124c5..d3977d23d 100644
--- a/winsup/doc/cygwinenv.sgml
+++ b/winsup/doc/cygwinenv.sgml
@@ -1,10 +1,13 @@
 <sect1 id="using-cygwinenv"><title>The <envar>CYGWIN</envar> environment
 variable</title>
 
+<sect2 id="cygwinenv-implemented-options">
+<title>Implemented options</title>
+
 <para>The <envar>CYGWIN</envar> environment variable is used to configure
 many global settings for the Cygwin runtime system. It contains the options
 listed below, separated by blank characters. Many options can be turned off
-by prefixing with <literal>no </literal>.</para>
+by prefixing with <literal>no</literal>.</para>
 
 <itemizedlist mark="bullet">
 <listitem>
@@ -12,7 +15,8 @@ by prefixing with <literal>no </literal>.</para>
 (e.g. pipe and COM ports) file opens default to binary mode 
 (no CRLF translation) instead of text mode.  Defaults to set (binary
 mode).  By default, devices are opened in binary mode, so this option
-has little effect on normal cygwin operations.
+has little effect on normal cygwin operations.  Sockets are always
+in binary mode.
 
 It does affect two things, however.  For non-NTFS filesystems, this
 option will control the line endings for standard output/input/error
@@ -21,52 +25,28 @@ the default translation mode of a pipe, although most shells set the
 pipe to binary by default.
 </para>
 </listitem>
-<listitem>
-<para><envar>check_case:level</envar> - THIS OPTION IS DEPRECATED.
-Don't use it unless you know what you're doing and don't see any way
-around it.  And even then, this option is error prone, slows down Cygwin
-and not well maintained.  This option controls the behavior of
-Cygwin when a user tries to open or create a file using a case different from
-the case of the path as saved on the disk.
-<literal>level</literal> is one of <literal>relaxed</literal>,
-<literal>adjust</literal> and <literal>strict</literal>.</para>
-<itemizedlist mark="bullet">
-<listitem>
-<para><envar>relaxed</envar> which is the default behaviour simply
-ignores case. That's the default for native Windows applications as well.</para>
-</listitem>
-<listitem>
-<para><envar>adjust</envar> behaves mostly invisible. The POSIX input
-path is internally adjusted in case, so that the resulting DOS path uses the
-correct case throughout. You can see the result when changing the directory
-using a wrong case and calling <command>/bin/pwd</command> afterwards.</para>
-</listitem>
-<listitem>
-<para><envar>strict</envar> results in a error message if the case
-isn't correct. Trying to open a file <filename>Foo</filename> while a file
-<filename>fOo</filename> exists results in a "no such file or directory"
-error. Trying to create a file <filename>BAR</filename> while a file
-<filename>Bar</filename> exists results in a "Filename exists with different
-case" error.</para>
-</listitem>
-</itemizedlist>
-</listitem>
 
 <listitem>
-<para><envar>codepage:[ansi|oem]</envar> - Windows console 
-applications can use different character sets (codepages) for drawing
-characters.  The first setting, called "ansi", is the default.
-This character set contains various forms of latin characters used
-in European languages.  The name originates from the ANSI Latin1
-(ISO 8859-1) standard, used in Windows 1.0, though the character
-sets have since diverged from any standard.  The second setting
-selects an older, DOS-based character set, containing various line
-drawing and special characters.  It is called "oem" since it was
-originally encoded in the firmware of IBM PCs by original
-equipment manufacturers (OEMs).  If you find that some characters 
-(especially non-US or 'graphical' ones) do not display correctly in 
-Cygwin, you can use this option to select an appropriate codepage.
-</para>
+<para><envar>codepage:[ansi|oem|utf8]</envar> - This option controls
+which single- or multibyte character set is used for file and console
+operations.  Windows is using UTF-16 characters internally and this
+option specifies how 8-byte character sets are converted to UTF-16 and
+vice versa.  The default setting is <envar>ansi</envar> which means,
+conversion is based on the current ANSI codepage, typically 1252 in
+many Western language versions of Windows.  The name originates from the
+ANSI Latin1 (ISO 8859-1) standard, used in Windows 1.0, though the
+character sets have since diverged from any standard.  The second
+setting selects an older, DOS-based character set, containing various
+line drawing and special characters.  It is called <envar>oem</envar>
+since it was originally encoded in the firmware of IBM PCs by original
+equipment manufacturers (OEMs).</para>
+<para>If you find that some characters (especially non-US or 'graphical' ones)
+do not display correctly in Cygwin, you can use this option to select an
+appropriate codepage.  Finally, <envar>utf8</envar> treats all file names
+and console characters as UTF-8 chars.  Please note that, for correct
+operation, you have to set the environment variable LC_CTYPE to "C-UTF-8"
+for the time being.  The reason is that newlib's multibyte conversion
+functions require this setting.</para>
 </listitem>
 
 <listitem>
@@ -77,16 +57,18 @@ path name.  Defaults to set.</para>
 
 <listitem>
 <para><envar>(no)envcache</envar> - If set, environment variable
-conversions (between Win32 and POSIX) are cached.  Note that this is may
+conversions (between Win32 and POSIX) are cached.  Note that this may
 cause problems if the mount table changes, as the cache is not invalidated
 and may contain values that depend on the previous mount table
 contents. Defaults to set.</para>
 </listitem>
+
 <listitem>
 <para><envar>(no)export</envar> - If set, the final values of these
 settings are re-exported to the environment as <envar>CYGWIN</envar> again.
 Defaults to off.</para>
 </listitem>
+
 <listitem>
 <para>
 <envar>error_start:Win32filepath</envar> - if set, runs 
@@ -98,6 +80,7 @@ usually set to the path to <command>gdb</command> or
 There is no default set.
 </para>
 </listitem>
+
 <listitem>
 <para><envar>forkchunk:32768</envar> - causes the <function>fork()</function>
 to copy memory some number of bytes at a time, in the above example 
@@ -106,12 +89,14 @@ possible, which is preferable in most cases but may slow some older systems
 down.
 </para>
 </listitem>
+
 <listitem>
 <para><envar>proc_retry:n</envar> - causes the <function>fork()</function> and <function>exec*()</function>
 to retry n times when a child process fails due to certain windows-specific errors.  These errors usually
 occur when processes are being started while a user is logging off.
 </para>
 </listitem>
+
 <listitem>
 <para><envar>(no)glob[:ignorecase]</envar> - if set, command line arguments
 containing UNIX-style file wildcard characters (brackets, question mark,
@@ -122,40 +107,13 @@ Default is set.</para>
 <para>This option also accepts an optional <literal>[no]ignorecase</literal> modifer.
 If supplied, wildcard matching is case insensitive.  The default is <literal>noignorecase</literal></para>
 </listitem>
-<listitem>
-<para><envar>(no)ntea</envar> - if set, use NT Extended Attributes to
-store UNIX-like inode information.
-This option only operates under Windows NT. Defaults to not set.
-Only FAT and NTFS support Extended Attributes, not FAT32, so it's
-of no use there.  Furthermore, on NTFS partitions ntsec, which provides
-real permissions, overrides ntea, which only provides faked permissions.
-So setting ntea only makes sense if you either have FAT partitions,
-or if you switch off ntsec explicitely. </para>
-<warning><title>Warning!</title> <para>This may create additional
-<emphasis>large</emphasis> files on FAT partitions.</para></warning>
-</listitem>
-<listitem>
-<para><envar>(no)ntsec</envar> - if set, use the NT security
-model to set UNIX-like permissions on files and processes. The
-file permissions can only be set on NTFS partitions. FAT/FAT32 don't
-support the NT file security. Defaults to set. For more information, read
-the documentation in <xref linkend="ntsec"></xref>.</para>
-</listitem>
-<listitem>
-<para><envar>(no)smbntsec</envar> - if set, use <envar>ntsec</envar> on remote
-drives as well (default is "nosmbntesc"). When setting "smbntsec" there's
-a chance that you get problems with Samba shares so you should use this
-option with care.  One reason for a non working <envar>ntsec</envar> on
-remote drives could be insufficient permissions of the users. The requires
-user rights are somewhat dangerous (SeRestorePrivilege), so it's not always
-an option to grant that rights to users.  However, this shouldn't be a
-problem in NT domain environments.</para>
-</listitem>
+
 <listitem>
 <para><envar>(no)reset_com</envar> - if set, serial ports are reset
 to 9600-8-N-1 with no flow control when used. This is done at open
 time and when handles are inherited.  Defaults to set.</para>
 </listitem>
+
 <listitem>
 <para><envar>(no)server</envar> - if set, allows client applications
 to use the Cygserver facilities.  This option must be enabled explicitely
@@ -166,18 +124,18 @@ successfully.  These function calls will return with
 <literal>ENOSYS</literal>, "Bad system call".
 </para>
 </listitem>
+
 <listitem>
 <para><envar>(no)strip_title</envar> - if set, strips the directory
 part off the window title, if any.  Default is not set.</para>
 </listitem>
+
 <listitem>
 <para><envar>(no)title</envar> - if set, the title bar
 reflects the name of the program currently running.  Default is not
-set.  Note that under Win9x the title bar is always enabled and it is
-stripped by default, but this is because of the way Win9x works.  In
-order not to strip, specify <literal>title</literal> or <literal>title
-nostrip_title</literal>.</para>
+set.</para>
 </listitem>
+
 <listitem>
 <para><envar>(no)tty</envar> - if set, Cygwin enables extra support
 (i.e., termios) for UNIX-like ttys in the Windows console. 
@@ -190,11 +148,65 @@ and it cannot be changed in the shell.  It should not be set when using
 other terminals (i.e., rxvt or xterm). 
 </para>
 </listitem>
+
 <listitem>
 <para><envar>(no)winsymlinks</envar> - if set, Cygwin creates
 symlinks as Windows shortcuts with a special header and the R/O attribute
 set. If not set, Cygwin creates symlinks as plain files with a magic number,
-a path and the system attribute set. Defaults to set.</para>
+a path and the system attribute set. Defaults to not set since plain
+file symlinks are faster to write and faster to read.</para>
 </listitem>
 </itemizedlist>
+
+</sect2>
+
+<sect2 id="cygwinenv-removed-options">
+<title>Removed options</title>
+
+<para>
+Some CYGWIN options have been removed in Cygwin 1.7 for one reason or another.
+These removed options are listed below.</para>
+
+<itemizedlist mark="bullet">
+<listitem>
+<para><envar>check_case</envar> - This option has been removed in favor of
+real case sensitivity and the per-mount option "posix=[0|1]".  For more
+information, read the documentation in <xref linkend="mount-table"></xref> and
+<xref linkend="pathnames-casesensitive"></xref>.</para>
+</listitem>
+
+<listitem>
+<para><envar>(no)ntea</envar> -  This option has been removed since it
+only fakes security which is considered dangerous and useless.  It also
+created an uncontrollably large file on FAT and was entirely useless
+on FAT32.</para>
+</listitem>
+
+<listitem>
+<para><envar>(no)ntsec</envar> - This option has been removed in favor of
+the per-mount option "acl"/"noacl".  For more information, read the
+documentation in <xref linkend="mount-table"></xref>.</para>
+</listitem>
+
+<listitem>
+<para><envar>(no)smbntsec</envar> - This option has been removed in favor of
+the per-mount option "acl"/"noacl".  For more information, read the
+documentation in <xref linkend="mount-table"></xref>.</para>
+</listitem>
+
+<listitem>
+<para><envar>(no)transparent_exe</envar> - This option has been removed
+because the behaviour it switched on is now the standard behaviour in
+Cygwin.</para>
+</listitem>
+
+<listitem>
+<para><envar>(no)traverse</envar> - This option has been removed because
+traverse checking is not quite correctly implemented by Microsoft and
+it's behaviour is getting worse with each new OS version.</para>
+</listitem>
+</itemizedlist>
+
+</sect2>
+
 </sect1>
diff --git a/winsup/doc/effectively.sgml b/winsup/doc/effectively.sgml
index 6a9e95263..b1e38c35c 100644
--- a/winsup/doc/effectively.sgml
+++ b/winsup/doc/effectively.sgml
@@ -18,23 +18,27 @@ support the <literal>/?</literal> switch to display usage information.
 <para>
 Unfortunately, no standard set of tools included with all versions of 
 Windows exists.  If you are unfamiliar with the tools available 
-on your system, here is a general guide.  Windows 95, 98, and ME have 
-very limited command-line configuration tools.  Windows NT 4.0 has much 
-better coverage, which Windows 2000 and XP expanded. 
+on your system, here is a general guide.  Windows NT 4.0 has only a basic 
+set of tools, which later versions of Windows expanded. 
 Microsoft also provides free downloads for Windows NT 4.0 (the Resource Kit 
 Support Tools), Windows 2000 (the Resource Kit Tools), and XP (the 
-Windows Support Tools). Additionally, many independent sites such as 
-<ulink url="http://download.com.com">download.com</ulink>, 
+Windows Support Tools).  Generally, the younger the Windows version, the
+more complete are the on-board tools.  Additionally, many independent sites
+such as 
+<ulink url="http://download.com">download.com</ulink>, 
 <ulink url="http://simtel.net">simtel.net</ulink>, 
-and <ulink url="http://sysinternals.com">sysinternals.com</ulink>
-provide command-line utilities.  A few Windows tools, such as 
-<command>find.exe</command> and <command>sort.exe</command>,
-may conflict with the Cygwin versions; make sure that you use the full 
-path (<command>/usr/bin/find</command>) or that your Cygwin 
-<literal>bin</literal> directory comes first in your <envar>PATH</envar>.
+and Microsoft's own
+<ulink url="http://technet.microsoft.com/en-us/sysinternals/default.aspx">Sysinternals</ulink>
+provide quite useful command-line utilities, as far as they are not
+already provided by Cygwin.  A few Windows tools, such as 
+<command>find.exe</command>, <command>link.exe</command> and
+<command>sort.exe</command>, may conflict with the Cygwin versions
+make sure that you use the full path (<command>/usr/bin/find</command>)
+or that your Cygwin <literal>bin</literal> directory comes first in your
+<envar>PATH</envar>.
 </para>
 
-<sect2> <title>Pathnames</title>
+<sect2 id="using-pathnames-effectively"> <title>Pathnames</title>
 
 <para>
 Windows programs do not understand POSIX pathnames, so any arguments 
@@ -60,15 +64,15 @@ preferable to use <command>cygpath</command> in shell scripts.
 
 </sect2>
 
-<sect2> <title>Console Programs</title>
+<sect2 id="using-console"> <title>Console Programs</title>
 <para>
 Another issue is receiving output from or giving input to console-based 
 Windows programs.  Unfortunately, interacting with Windows console 
 applications is not a simple matter of using a translation utility. Windows 
-console applications are designed to run under <command>command.com</command> 
-or <command>cmd.exe</command>, and some do not deal gracefully with other
+console applications are designed to run under 
+<command>cmd.exe</command>, and some do not deal gracefully with other
 situations.  Cygwin can receive console input only if it
-is also running in a console (DOS box) since Windows does not provide
+is also running in a console window since Windows does not provide
 any way to attach to the backend of the console device. Another
 traditional Unix input/output method, ptys (pseudo-terminals), is
 supported by Cygwin but not entirely by Windows.  The basic problem is 
@@ -78,7 +82,7 @@ having their input or output redirected to pipes.
 
 <para>
 To help deal with these issues, Cygwin supports customizable levels of 
-Windows verses Unix compatibility behavior.  To be most compatible with 
+Windows versus Unix compatibility behavior.  To be most compatible with 
 Windows programs, use a DOS prompt, running only the occasional Cygwin 
 command or script. Next would be to run <command>bash</command> within 
 a default DOS box. To make Cygwin more Unix compatible in this case, 
@@ -92,7 +96,7 @@ but expect some compatibility problems with Windows programs.
 
 </sect2>
 
-<sect2> <title>Cygwin and Windows Networking</title>
+<sect2 id="using-net"> <title>Cygwin and Windows Networking</title>
 <para>
 Many popular Cygwin packages, such as <systemitem>ncftp</systemitem>, 
 <systemitem>lynx</systemitem>, and <systemitem>wget</systemitem>, require a 
@@ -111,11 +115,11 @@ of these programs, see if the alternate one works as expected.
 <para>
 There are a variety of other programs available for specific situations.
 If your system does not have an always-on network connection, you 
-may be interested in <command>rasdial.exe</command> (or alternatives for
-Windows 95, 98, and ME) for automating dialup connections.  
+may be interested in <command>rasdial.exe</command> for automating dialup
+connections.  
 Users who frequently change their network 
 configuration can script these changes with <command>netsh.exe</command> 
-(Windows 2000 and XP). For proxy users, the open source 
+(Windows 2000 and later). For proxy users, the open source 
 <ulink url="http://apserver.sourceforge.net">
 NTLM Authorization Proxy Server</ulink> or the no-charge
 <ulink url="http://www.hummingbird.com/products/nc/socks/index.html">
@@ -125,15 +129,15 @@ programs in your environment.
 
 </sect2>
 
-<sect2><title>The cygutils package</title>
+<sect2 id="using-cygutils"><title>The cygutils package</title>
 
 <para>
-The optional <systemitem>cygutils</systemitem> package contains miscellaneous tools that are
-small enough to not require their own package. It is not included in a
-default Cygwin install; select it from the Utils category in 
-<command>setup.exe</command>. Several of the <systemitem>cygutils</systemitem> tools are useful
-for interacting with Windows. 
-</para>
+The optional <systemitem>cygutils</systemitem> package contains
+miscellaneous tools that are small enough to not require their own package.
+It is not included in a default Cygwin install; select it from the Utils
+category in <command>setup.exe</command>. Several of the
+<systemitem>cygutils</systemitem> tools are useful for interacting with
+Windows.</para>
 
 <para>
 One of the hassles of Unix-Windows interoperability is the different line 
@@ -146,7 +150,7 @@ endings, but <systemitem>cygutils</systemitem> provides several dedicated progra
 </para>
 </sect2>
 
-<sect2><title>Creating shortcuts with cygutils</title>
+<sect2 id="using-shortcuts"><title>Creating shortcuts with cygutils</title>
 <para>
 Another problem area is between Unix-style links, which link one file
 to another, and Microsoft .lnk files, which provide a shortcut to a
@@ -172,7 +176,7 @@ Windows shortcuts.
 </para>
 </sect2>
   
-<sect2><title>Printing with cygutils</title>
+<sect2 id="using-printing"><title>Printing with cygutils</title>
 <para>
 There are several options for printing from Cygwin, including the 
 <command>lpr</command> found in <systemitem>cygutils</systemitem> (not to be confused with the 
diff --git a/winsup/doc/filemodes.sgml b/winsup/doc/filemodes.sgml
index 5f34aac84..2a644db51 100644
--- a/winsup/doc/filemodes.sgml
+++ b/winsup/doc/filemodes.sgml
@@ -1,34 +1,33 @@
 <sect1 id="using-filemodes"><title>File permissions</title>
 
-<para>On Windows 9x systems, files are always readable, and Cygwin uses the
-native read-only mode to determine if they are writable. Files are
+<para>On FAT or FAT32 filesystems, files are always readable, and Cygwin
+uses the DOS read-only attribute to determine if they are writable. Files are
 considered to be executable if the filename ends with .bat, .com or .exe, or
 if its content starts with #!. Consequently <command>chmod</command> can
 only affect the "w" mode, it silently ignores actions involving the other
 modes.  This means that <command>ls -l</command>
 needs to open and read files. It can thus be relatively slow.</para>
 
-<para>Under NT, file permissions default to the same behavior as Windows
-9x but there is optional functionality in Cygwin that can make file
-systems behave more like on UNIX systems.  This is turned on by adding
-the "ntea" option to the <envar>CYGWIN</envar> environment variable.</para>
-
-<para>When the "ntea" feature is activated, Cygwin will start with basic
-permissions as determined above, but can store POSIX file permissions in NT
-Extended Attributes.  This feature works quite well on NTFS partitions
-because the attributes can be stored sensibly inside the normal NTFS
-filesystem structure.  However, on a FAT partition, NT stores extended
-attributes in a flat file at the root of the partition called <filename>EA
-DATA. SF</filename>.  This file can grow to extremely large sizes if you
-have a large number of files on the partition in question, slowing the
-system to a crawl.  In addition, the <filename>EA DATA. SF</filename> file
-can only be deleted outside of Windows because of its "in use" status.  For
-these reasons, the use of NT Extended Attributes is off by default in
-Cygwin.  Finally, note that specifying "ntea" in <envar>CYGWIN</envar> has no
-effect under Windows 9x. </para>
-
-<para>Under NT, the test "[ -w filename]" is only true if filename is
-writable across the board, e.g. <command>chmod +w filename</command>. </para>
+<para>On NTFS, file permissions are evaluated using the Access Control
+Lists (ACLs) attached to a file.  This can be switched off by using the
+"noacl" option to the respective mount point in the
+<filename>/etc/fstab</filename> or <filename>/etc/fstab.d/$USER</filename>
+file.  For more information on file permissions, see
+
+<!-- TODO: Put the file permission stuff from ntsec here??? -->
+
+<xref linkend="ntsec"></xref>.
+</para>
+
+<!-- TODO -->
+
+<para>On NFS shares, file permissions are exactly the POSIX permissions
+transmitted from the server using the NFSv3 protocol, if the NFS client
+is the one from Microsoft's "Services For Unix", or the one built into
+Windows Vista or later.
+</para>
+
+<para>Only the user and group ownership is not necessarily correct.</para>
 
 </sect1>
 
diff --git a/winsup/doc/gcc.sgml b/winsup/doc/gcc.sgml
index f1d5431b7..60202d949 100644
--- a/winsup/doc/gcc.sgml
+++ b/winsup/doc/gcc.sgml
@@ -6,7 +6,7 @@
 Refer to the GCC User's Guide for information on standard usage and
 options.  Here's a simple example:</para>
 
-<example>
+<example id="gcc-hello-world">
 <title>Building Hello World with GCC</title>
 <screen>
 <prompt>C:\&gt;</prompt> <userinput>gcc hello.c -o hello.exe</userinput>
diff --git a/winsup/doc/gdb.sgml b/winsup/doc/gdb.sgml
index 732004f49..1b26599c7 100644
--- a/winsup/doc/gdb.sgml
+++ b/winsup/doc/gdb.sgml
@@ -18,7 +18,7 @@ program for debugging.  What you need to do is add
 <literal>-g</literal> to all the other flags you use when compiling
 your sources to objects.</para>
 
-<example><title>Compiling with -g</title>
+<example id="gdb-g"><title>Compiling with -g</title>
 <screen>
 <prompt>$</prompt> gcc -g -O2 -c myapp.c
 <prompt>$</prompt> gcc -g myapp.c -o myapp
@@ -57,7 +57,7 @@ at individual variables or what pointers point to.</para>
 <command>break</command> command to tell gdb to stop your program when it
 gets to a specific function or line number:</para>
 
-<example><title>"break" in gdb</title>
+<example id="gdb-break"><title>"break" in gdb</title>
 <screen>
 <prompt>(gdb)</prompt> break my_function
 <prompt>(gdb)</prompt> break 47
@@ -75,7 +75,7 @@ time.</para>
 your program.  These two cases are the same as far as your program is
 concerned:</para>
 
-<example><title>Debugging with command line arguments</title>
+<example id="gdb-cliargs"><title>Debugging with command line arguments</title>
 <screen>
 <prompt>$</prompt> myprog -t foo --queue 47
 
diff --git a/winsup/doc/legal.sgml b/winsup/doc/legal.sgml
index aad3edf7c..80f404670 100644
--- a/winsup/doc/legal.sgml
+++ b/winsup/doc/legal.sgml
@@ -1,6 +1,6 @@
 <legalnotice id="legal">
 
-<para>Copyright &copy; 1998, 1999, 2000, 2001, 2002, 2003, 2004, 2005, 2006, 2007 Red Hat, Inc.</para>
+<para>Copyright &copy; 1998, 1999, 2000, 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008 Red Hat, Inc.</para>
 
 <!--
 
diff --git a/winsup/doc/ntsec.sgml b/winsup/doc/ntsec.sgml
index 4859feb48..b44c04919 100644
--- a/winsup/doc/ntsec.sgml
+++ b/winsup/doc/ntsec.sgml
@@ -1,123 +1,146 @@
-<sect1 id="ntsec"><title>NT security and usage of <literal>ntsec</literal></title>
+<sect1 id="ntsec"><title>NT security</title>
 
-<para>The setting of UNIX like object permissions is controlled by the 
-<link linkend="using-cygwinenv"><envar>CYGWIN</envar> environment
-variable</link> setting <literal>(no)ntsec</literal> which is set to
-<literal>ntsec</literal> by default.</para>
+<para>The setting of POSIX like object permissions is controlled by the 
+<link linkend="mount-table">mount option</link> <literal>(no)acl</literal>
+which is set to <literal>acl</literal> by default.  The design goal
+is to utilize the Windows access control API to implement real POSIX
+permissions.</para>
 
-<para>The design goal of <literal>ntsec</literal> is to get a more UNIX-like
-permission structure based upon the security features of Windows NT.
-To describe the changes, I will first give a short overview in
-<xref linkend="ntsec-common"></xref>.
-</para>
-<para><link linkend="ntsec-processes" endterm="ntsec-processes.title"></link>
-discusses the changes in ntsec related to privileges on processes.</para>
-
-<para><link linkend="ntsec-files" endterm="ntsec-files.title"></link> shows
-the basics of UNIX-like setting of file permissions.</para>
+<para>We start with a short overview.  Note that this overview must
+be necessarily short.  If you want to learn more about the Windows security
+model, see the <ulink url="http://msdn.microsoft.com/en-us/library/aa374860(VS.85).aspx">Access Control</ulink> article in MSDN documentation.</para>
 
-<para><link linkend="ntsec-sids" endterm="ntsec-sids.title"></link>
-talks about using SIDs in <filename>/etc/passwd</filename> and
-<filename>/etc/group</filename>.</para>
-
-<para><link linkend="ntsec-mapping" endterm="ntsec-mapping.title"></link>
-illustrates the permission mapping leak of Windows NT.</para>
+<sect2 id="ntsec-common"><title>NT security</title>
 
-<para><link linkend="ntsec-aclfuncs" endterm="ntsec-aclfuncs.title"></link>
-describes in short the ACL API since release 1.1.</para>
+<para>In the NT security model, almost any "object" is securable.
+"Objects" are files, processes, threads, semaphores, etc.</para>
 
-<para><link linkend="ntsec-setuid" endterm="ntsec-setuid.title"></link>
-describes the new support of a setuid concept introduced with release
-1.1.3.</para>
+<para>Every object has a data structure called "security descriptor" (SD)
+attached.  The SD contains all information necessary to control who can
+how access an object.  The SD of an object consists of five parts:</para>
 
-<para><link linkend="ntsec-switch" endterm="ntsec-switch.title"></link>
-gives the basics of using the SYSTEM user to switch user context.
-</para>
+<itemizedlist spacing="compact">
+<listitem><para>Flags which control several aspects of this SD. This is
+not discussed here.</para></listitem>
+<listitem><para>The SID of the object owner.</para></listitem>
+<listitem><para>The SID of the object owner group.</para></listitem>
+<listitem><para>A list of "Access Control Entries" (ACE), called the
+"Discretionary Access Control List" (DACL).</para></listitem>
+<listitem><para>Another list of ACEs, called the
+"Security Access Control List" (SACL), which doesn't matter for our
+purpose.</para></listitem>
+</itemizedlist>
 
-<para><link linkend="ntsec-ids" endterm="ntsec-ids.title"></link>
-explains the way Cygwin shows users and groups that are not in 
-<filename>/etc/passwd</filename> or <filename>/etc/group</filename>.
+<para>Every ACE contains a so-called "Security IDentifier" (SID) and
+other stuff which is explained a bit later.  Let's talk about the SID first.
 </para>
 
-<sect2 id="ntsec-common"><title>NT security</title>
-
-<para>The NT security allows a process to allow or deny access of
-different kind to `objects'. `Objects' are files, processes,
-threads, semaphores, etc.</para>
-
-<para>The main data structure of NT security is the `security descriptor'
-(SD) structure. It explains the permissions, that are granted (or denied)
-to an object and contains information, that is related to so called
-`security identifiers' (SID).</para>
+<para>A SID is a unique identifier for users, groups, computers and AD
+domains.  SIDs are basically comparable to POSIX UIDs and GIDs, but are
+more complicated because they are unique across multiple machines or
+domains.  A SID is a structure of multiple numerical values.  There's
+a convenient convention to type SIDs.  Here's an example:</para>
 
-<para>A SID is a unique identifier for users, groups and domains. 
-SIDs are comparable to UNIX UIDs and GIDs, but are more complicated
-because they are unique across networks. Example:</para>
-
-<para>SID of a system `foo':</para>
+<para>SID of a machine "foo":</para>
 
 <screen>
   S-1-5-21-165875785-1005667432-441284377
 </screen>
 
-<para>SID of a user `johndoe' of the system `foo':</para>
+<para>SID of a user "johndoe" of the system "foo":</para>
 
 <screen>
   S-1-5-21-165875785-1005667432-441284377-1023
 </screen>
 
-<para>The above example shows the convention for printing SIDs. The leading
-`S' should show that it is a SID. The next number is a version number which
-is always 1. The next number is the so called `top-level authority' that
-identifies the source that issued the SID.</para>
+<para>The leading "S" has no further meaning except to show that this is
+a SID.  The next number is a version number which is always 1 so far.
+The next two numbers are the authority which shows the initiated what
+kind of SID this is.  There are a couple of builtin accounts and
+accounts with very special meaning. However, computer and domain SIDs
+always start with "S-1-5-21".  The next three numbers, all 32 bit values,
+are the unique 96 bit identifier of the comupter system.  This is
+hopefully unique all over the world, but in practice it's sufficient if
+the comuter SIDs are unique within a single Windows network.</para>
+
+<para>As you can see in the above example, SIDs of users (and groups)
+are identical to the computer SID, except for an additional part, the
+so-called "relative identifier" (RID).  So the SID of a user is always 
+uniquely attached to the system on which the account has been generated.</para>
 
-<para>While each system in a NT network has it's own SID, the situation
-is modified in NT domains: The SID of the domain controller is the
-base SID for each domain user. If an NT user has one account as domain
-user and another account on his local machine, these accounts are under
-any circumstances DIFFERENT, regardless of the usage of the same user
-name and password!</para>
+<para>It's a bit different in domains.  The domain has its own SID, and
+that SID is identical to the SID of the first domain controller, on
+which the domain is created.  Domain user SIDs look exactly like the
+computer user SIDs, the leading part is just the domain SID and the RID
+is created when the user is created.</para>
 
-<para>SID of a domain `bar':</para>
+<para>Ok, consider you created a new domain "bar" on some new domain
+controller and you would like to create a domain account "johndoe":</para>
+
+<para>SID of a domain "bar.local":</para>
 
 <screen>
   S-1-5-21-186985262-1144665072-740312968
 </screen>
 
-<para>SID of a user `johndoe' in the domain `bar':</para>
+<para>SID of a user "johndoe" in the domain "bar.local":</para>
 
 <screen>
   S-1-5-21-186985262-1144665072-740312968-1207
 </screen>
 
-<para>The last part of the SID, the so called `relative identifier' (RID),
-is by default used as UID and/or GID under Cygwin. As the name and the
-above example implies, this id is unique only relative to one system or
-domain.</para>
-
-<para>Note, that it's possible that a user has the same RID on two
-different systems. The resulting SIDs are nevertheless different, so
-the SIDs are representing different users in an NT network.</para>
-
-<para>There is a big difference between UNIX IDs and NT SIDs: the existence of
-the so called `well known groups'. For example UNIX has no GID for the
-group of `all users'. NT has an SID for them, called `Everyone' in the
-English versions. The SIDs of well-known groups are not unique across
-an NT network but their meanings are unmistakable.
-Examples of well-known groups:</para>
-
-<screen>
-everyone                        S-1-1-0
-creator/owner                   S-1-3-0
-batch process (via `at')        S-1-5-3
-authenticated users             S-1-5-11
-system                          S-1-5-18
-</screen>
+<para>Ok, so you now have two accounts called johndoe, one account
+created on the machine "foo", one created in the domain "bar.local".
+Both have different SIDs and not even the RID is the same.  How do
+the systems know it's the same account?  After all, the name is
+the same, right?  The answer is, these accounts are NOT identical.
+For all the machines know there are two different accounts, one is
+"FOO\johndoe", the other one is "BAR\johndoe" or "johndoe@bar.local".
+Different SID, different account.  Full stop.
+</para>
 
-<para>The last important group of SIDs are the `predefined groups'. This
-groups are used mainly on systems outside of domains to simplify the 
-administration of user permissions. The corresponding SIDs are not unique
-across the network so they are interpreted only locally:</para>
+<para>The last part of the SID, the so called "Relative IDentifier" (RID),
+is by default used as UID and/or GID under Cygwin when you create the
+<filename>/etc/passwd</filename> and <filename>/etc/group</filename>
+files using the <command>mkpasswd</command> and <command>mkgroup</command>
+tools.  Domain account UIDs and GIDs are offset by 10000 by default
+which might be a bit low for very big organizations.  Fortunately there's
+an option in both tools to change the offset...</para>
+
+<para>Do you still remember the SIDs with special meaning?  In offical
+notation they are called "well-known SIDs".  For example, POSIX has no GID
+for the group of "all users" or "world" or "others".  The last three rwx
+bits in a permission value just represent the permissions for "everyone
+who is not the owner or is member of the owning group".  Windows has a
+SID for these poor souls, the "Everyone" SID.  Other well-known SIDs
+represent more circumstances instead of actual users or groups.  Here
+are a few examples for well-known SIDs:</para>
+
+<screen>
+Everyone                        S-1-1-0    Simply everyone...
+Batch                           S-1-5-3    Processes started via the task
+					   scheduler are member of this group.
+Interactive			S-1-5-4    Only processes of users which are
+					   logged in via an interactive
+					   session are members here.
+Authenticated Users             S-1-5-11   Users which have gone through
+                                           the authentication process and
+					   survived.  Anonymously accessing
+					   users are not incuded here.
+SYSTEM                          S-1-5-18   A special account which has all
+					   kinds of dangerous rights, sort of
+					   an uber-root account.
+</screen>
+
+<para>For a full list please refer to
+<ulink url="http://msdn.microsoft.com/en-us/library/aa379649.aspx">Well-known SIDs</ulink>.
+Naturally well-known SIDs are the same on each machine, so they are
+not unique to a machine or domain.  They have the same meaning across
+the Windows network.</para>
+
+<para>Additionally there are a couple of well-known builtin groups,
+which have the same SID on every machine and which have certain user
+rights by default:</para>
 
 <screen>
 administrators                  S-1-5-32-544
@@ -126,186 +149,142 @@ guests                          S-1-5-32-546
 ...
 </screen>
 
-<para>Now, how are permissions given to objects? A process may assign an SD
-to the object. The SD of an object consists of three parts:</para>
-
-<itemizedlist spacing="compact">
-<listitem><para>the SID of the owner </para></listitem>
-<listitem><para>the SID of the group </para></listitem>
-<listitem><para>a list of SIDs with their permissions, called
-`access control list' (ACL) </para></listitem>
-</itemizedlist>
-
-<para>UNIX is able to create three different permissions, the permissions
-for the owner, for the group and for the world. In contrast the ACL
-has a potentially infinite number of members. Every member is a so called
-`access control element' (ACE). An ACE contains three parts:</para>
+<para>For instance, every account is usually member in the "Users"
+group.  All administrator accounts are member of the "Administrators"
+group.  That's all about it as far as single machines are involved.  In
+a domain environment it's a bit more tricky.  Since these SIDs are not
+unique to a machine, every domain user and every domain group can be a
+member of these well known groups.  Consider the domain group "Domain
+Admins".  This group is by default in the "Administrators" group.  Let's
+assume the above computer called "foo" is a member machine of the domain
+"bar.local".  If you stick the user "BAR\johndoe" into the group "Domain
+Admins", this guy will automatically be a mamber of the administrators
+group on "foo", when logging in on "foo".  Neat, isn't it?</para>
+
+<para>Back to ACE and ACL.  POSIX is able to create three different
+permissions, the permissions for the owner, for the group and for the
+world.  In contrast the Windows ACL has a potentially infinite number of
+members... as long as they fit into 64K.  Every member is an ACE.
+ACE consist of three parts:</para>
 
 <itemizedlist spacing="compact">
-<listitem><para>the type of the ACE </para></listitem>
-<listitem><para>permissions, described with a DWORD </para></listitem>
-<listitem><para>the SID, for which the above mentioned permissions are
-set </para></listitem>
+<listitem><para>The type of the ACE (allow ACE or deny ACE).</para></listitem>
+<listitem><para>Permission bits, 32 of them.</para></listitem>
+<listitem><para>The SID for which the permissions are allowed or denied.</para></listitem>
 </itemizedlist>
 
-<!-- Is the historical note really important here? we're at version 1.5.9, after all.. -->
-<para>The two important types of ACEs are the `access allowed ACE' and the
-`access denied ACE'. The ntsec functionality only used `access allowed ACEs' up
-to Cygwin version 1.1.0. Later versions also use `access denied ACEs' 
-to reflect the UNIX permissions as well as possible.</para>
+<para>The two (for us) important types of ACEs are the "access allowed
+ACE" and the "access denied ACE".  As the names imply, the allow ACE
+tells the system to allow the given permissions to the SID, the deny ACE
+results in denying the specific permission bits.</para>
 
 <para>The possible permissions on objects are more detailed than in
-UNIX. For example, the permission to delete an object is different
-from the write permission.</para>
-
-<para>With the aforementioned method NT is able to grant or revoke permissions
-to objects in a far more specific way. But what about cygwin? In a POSIX
-environment it would be fine to have the security behavior of a POSIX
-system. The NT security model is MOSTLY able to reproduce the POSIX model.
-The ntsec method tries to do this in cygwin.</para>
-
-<para>You ask "Mostly? Why mostly???" Because there's a leak in the NT model.
-I will describe that in detail in chapter 5.</para>
-
-<para>Creating  explicit object security is not that easy so you will often
-see only two simple variations in use:</para>
-
-<itemizedlist spacing="compact">
-<listitem><para>default permissions, computed by the operating system </para></listitem>
-<listitem><para>each permission to everyone </para></listitem>
-</itemizedlist>
-
-<para>For parameters to functions that create or open securable objects another
-data structure is used, the `security attributes' (SA). This structure
-contains an SD and a flag that specifies whether the returned handle
-to the object is inherited to child processes or not.
-This property is not important for ntsec so in
-this document the difference between SDs and SAs is ignored.</para>
-
-</sect2>
-
-<sect2 id="ntsec-processes"><title id="ntsec-processes.title">Process privileges</title>
-
-<para>Any process started under control of Cygwin has a semaphore attached
-to it, that is used for signaling purposes. The creation of this semaphore
-can be found in sigproc.cc, function `getsem'. The first parameter to the
-function call `CreateSemaphore' is an SA. Without ntsec this SA 
-assigns default security to the semaphore. There is a simple disadvantage:
-Only the owner of the process may send signals to it. Or, in other words,
-if the owner of the process is not a member of the administrators' group,
-no administrator may kill the process! This is especially annoying, if
-processes are started via service manager.</para>
-
-<para>Ntsec now assigns an SA to the process control semaphore, that
-has each permission set for the user of the process, for the
-administrators' group and for `system', which is a synonym for the
-operating system itself. The creation of this SA is done by the function
-`sec_user', that can be found in `shared.cc'. Each member of the
-administrators' group is now allowed to send signals to any process
-created in Cygwin, regardless of the process owner.</para>
-
-<para>Moreover, each process now has the appropriate security settings, when
-it is started via `CreateProcess'. You will find this in function
-`spawn_guts' in module `spawn.cc'. The security settings for starting a
-process in another user context have to add the SID of the new user, too.
-In the case of the `CreateProcessAsUser' call, sec_user creates an SA with
-an additional entry for the sid of the new user.</para>
+POSIX.  For example, the permission to delete an object is different
+from the permission to change object data, and even changing object data
+can be separated into different permission bits for different kind of
+data.</para>
 
 </sect2>
 
 <sect2 id="ntsec-files"><title id="ntsec-files.title">File permissions</title>
 
-<para>If ntsec is turned on, file permissions are set as in UNIX. An SD is
-assigned to the file containing the owner and group and ACEs for the
-owner, the group and `Everyone'.</para>
+<para>On NTFS and if the <literal>noacl</literal> mount option is not
+specified for a mount point, Cygwin sets file permissions as in POSIX.
+Basically this is done by defining a SD with the matching owner and group
+SIDs, and a DACL which contains ACEs for the owner, the group and for
+"Everyone", which represents what POSIX calls "others".</para>
 
-<para>The complete settings of UNIX like permissions can be found in the file
-`security.cc'. The two functions `get_nt_attribute' and `set_nt_attribute'
-are the main code. The reading and writing of the SDs is done by the
-functions `read_sd' and `write_sd'. `write_sd' uses the function `BackupRead'
-instead of the simpler function `SetFileSecurity' because the latter is
-unable to set owners different from the caller.</para>
+<para>To use NT security correctly, Cygwin depends on the files
+<filename>/etc/passwd</filename> and <filename>/etc/group</filename>.
+These files define the traslation between the Cygwin uid/gid and the
+Windows SID.  The SID is stored in the pw_gecos field in
+<filename>/etc/passwd</filename>, and in the gr_passwd field in
+<filename>/etc/group</filename>. Since the pw_gecos field can contain
+more information than just a SID, there are some rules for the layout.
+It's required that the SID is the last entry of the pw_gecos field,
+assuming that the entries in pw_gecos are comma-separated.  The
+commands <command>mkpasswd</command> and <command>mkgroup</command>
+usually do this for you.</para>
+
+<para>Another interesting entry in the pw_gecos field (which is also
+usually created by running <command>mkpasswd</command>) is the Windows user
+name entry.  It takes the form "U-domain\username" and is typically used
+by services to authenticate a user.  Logging in through <command>ssh</command>
+or <command>telnet</command> are two typical scenarios.
+</para>
 
-<para>If you are creating a file `foo' outside of Cygwin, you will see something
-like the following on <command>ls -ln</command>:</para>
+<para>A typical snippet from <filename>/etc/passwd</filename>:</para>
 
-<para>If your login is member of the administrators' group:</para>
-<screen>
-  rwxrwxrwx 1  544  513  ... foo
-</screen>
-<para>if not:</para>
+<example id="ntsec-passwd">
+<title>/etc/passwd:</title>
 <screen>
-  rwxrwxrwx 1  1000  513  ... foo
+SYSTEM:*:18:544:,S-1-5-18::
+Administrators:*:544:544:,S-1-5-32-544::
+Administrator:unused:500:513:U-FOO\Administrator,S-1-5-21-790525478-115176313-839522115-500:/home/Administrator:/bin/bash
+corinna:unused:11001:11125:U-BAR\corinna,S-1-5-21-2913048732-1697188782-3448811101-1001:/home/corinna:/bin/tcsh
 </screen>
+</example>
 
-<para>Note the user and group IDs. 544 is the UID of the administrators' group.
-This is a `feature' <literal>:-P</literal> of WinNT. If you are a member of
-the administrators' group, every file that you create is owned by the
-administrators' group, instead of by you.</para>
-
-<para>The second example shows the UID of the first user, that has been
-created with NT's the user administration tool. The users and groups are
-sequentially numbered, starting with 1000. Users and groups are using the
-same numbering scheme, so a user and a group don't share the same ID.</para>
-
-<para>In both examples the GID 513 is of special interest. This GID is a
-well known group with different naming in local systems and domains.
-Outside of domains the group is named 'None' (`Kein' in German, `Aucun'
-in French, etc.), in domains it is named 'Domain Users'.  Unfortunately,
-the group `None' is never shown in the user admin tool outside of domains!
-This is very confusing but this seems to have no negative consequences.</para>
-
-<para>To work correctly, ntsec depends on the files
-<filename>/etc/passwd</filename> and <filename>/etc/group</filename>.
-In Cygwin release 1.0 the names and the IDs must correspond to the
-appropriate NT IDs! The IDs used in Cygwin are the RID of the NT SID, as
-mentioned earlier.
-A SID of e.g. the user `corinna' on my NT workstation:</para>
-
-<screen>
-  S-1-5-21-165875785-1005667432-441284377-1000
+<para>The SYSTEM entry is usually needed by services.  The Administrators
+entry (Huh?  A group in /etc/passwd?) is only here to allow
+<command>ls</command> to print some file ownerships correctly.  Windows
+doesn't care if the owner of a file is a user or a group.  In older
+versions of Windows NT the default ownership for files created by an
+administrator account was set to the group Administrators instead of to
+the creating user account.  This has changed, but for those older
+systems it's convenient to have the Administrators group in
+<filename>/etc/passwd</filename>.</para>
+
+<para>The really interesting entries are the next two.  The Administrator
+entry is for the local administrator, the corinna entry matches the corinna
+account in the domain BAR.  The information given in the pw_gecos field
+are all we need to exactly identify an account, and to have a two way
+translation, from Windows account name/SID to Cygwin account name uid and
+vice versa.  Having this complete information allows us to choose a Cygwin
+name and uid which doesn't have to match the Windows account at all.  As
+long as the pw_gecos information is available, we're on the safe side:</para>
+
+<example id="ntsec-passwd-tweaked">
+<title>/etc/passwd, tweaked:</title>
+<screen>
+root:unused:0:513:U-FOO\Administrator,S-1-5-21-790525478-115176313-839522115-500:/home/Administrator:/bin/bash
+thursday_next:unused:11001:11125:U-BAR\corinna,S-1-5-21-2913048732-1697188782-3448811101-1001:/home/corinna:/bin/tcsh
 </screen>
+</example>
 
-<para>Note the last number: It's the RID 1000, Cygwin's UID.</para>
-
-<para>Unfortunately, workstations and servers outside of domains are not
-able to set primary groups! In these cases, where there is no correlation
-of users to primary groups, NT returns 513 (None) as primary group,
-regardless of the membership to existing local groups.</para>
-
-<para>When using <command>mkpasswd  -l -g</command> on such systems, you
-have to change the primary group by hand if `None' as primary group is
-not what you want (and I'm sure, it's not what you want!)</para>
+<para>  The above <filename>/etc/passwd</filename> will still work fine.
+You can now login via <command>ssh</command> as the user "root", and
+Cygwin dutyfully translates "root" into the Windows user
+"FOO\Administrators" and files owned by FOO\Administrators are shown to
+have the uid 0 when calling <command>ls -ln</command>.  All you do you're
+actually doing as Administrator.  Files created as root will be owned by
+FOO\Administrator.  And the domain user BAR\corinna can now happily
+pretend to be Thursday Next, but will wake up sooner or later finding
+out she's still actually the domain user BAR\corinna...</para>
 
-<para>Look at the following examples, which were parts of my files before
-storing SIDs in /etc/passwd and /etc/group had been introduced (See next
-chapter for details).  With the exception of my personal user entry, all
-entries are well known entries.</para> 
+<para>Do I have to mention that you can also rename groups in
+<filename>/etc/group</filename>?  As long as the SID is present and correct,
+all is well.  This allows for instance to rename the "Administrators" group
+to "root" as well:</para>
 
-<example>
-<title>/etc/passwd</title>
+<example id="ntsec-group-tweaked">
+<title>/etc/group, tweaked:</title>
 <screen>
-everyone:*:0:0:::
-system:*:18:18:::
-administrator::500:544::/home/root:/bin/bash
-guest:*:501:546:::
-administrators:*:544:544::/home/root:
-corinna::1000:547:Corinna Vinschen:/home/corinna:/bin/tcsh
+root:S-1-5-32-544:544:
 </screen>
 </example>
 
-<example>
-<title>/etc/group</title>
-<screen>
-everyone::0:
-system::18:
-none::513:
-administrators::544:
-users::545:
-guests::546:
-powerusers::547:
-</screen>
-</example>
+<para>Last but not least you can also change the primary group of a user
+in <filename>/etc/passwd</filename>.  The only requirement is that the user
+is actually a member of the new primary group in Windows.  For instance,
+normal users in a domain environment are members in the group "Domain Users",
+which in turn is member of the well-known group "Users".  Additionally let's
+assume the user is also a member of the newly created group .  The default
+primary group for users is 
+
+<!-- TODO: The rest of the file... -->
+
+</para>
 
 <para>As you can see, I changed my primary group membership from 513 (None)
 to 547 (powerusers).  So all files I created inside of Cygwin were now owned
@@ -330,14 +309,6 @@ processes, which are started through service manager.</para>
 
 <sect2 id="ntsec-sids"><title id="ntsec-sids.title">NT SIDs in Cygwin</title>
 
-<para>In Cygwin release 1.1 a new technique of using the 
-<filename>/etc/passwd</filename> and <filename>/etc/group</filename>
- was introduced.</para>
-
-<para>Both files may now contain SIDs of users and groups. They
-are saved in the last field of pw_gecos in <filename>/etc/passwd</filename>
-and in the gr_passwd field in <filename>/etc/group</filename>.</para>
-
 <para>This has the following advantages:</para>
 <itemizedlist spacing="compact">
 <listitem><para>ntsec works better in domain environments.</para></listitem>
@@ -378,14 +349,14 @@ root::500:513::/home/root:/bin/sh
 <listitem><para>As in U*X systems UIDs and GIDs numbering scheme now
 don't influence each other. So it's possible to have same Id's for a
 user and a group:</para>
-<example>
+<example id="ntsec-passwd-root">
 <title>/etc/passwd:</title>
 <screen>
 root::0:0:S-1-5-21-54355234-56236534-345635656-500:/home/root:/bin/sh
 </screen>
 </example>
 
-<example>
+<example id="ntsec-group-root">
 <title>/etc/group:</title>
 <screen>
 root:S-1-5-32-544:0:
@@ -402,14 +373,6 @@ not to do this since ntsec works better when having the SIDs available.</para>
 <para>Please note that the pw_gecos field in <filename>/etc/passwd</filename>
 is defined as a comma separated list. The SID has to be the last field!</para>
 
-<para>As aforementioned you are able to use Cygwin account names different
-from the NT account names. If you want to login through `telnet' or something
-else you have to use the special <command>login</command>. You may then
-add another field to pw_gecos which contains the NT user name including
-it's domain. So you are able to login as each domain user. The syntax
-is easy: Just add an entry of the form U-ntdomain\ntusername to the pw_gecos
-field. Note that the SID must still remain the last field in pw_gecos!</para>
-
 <screen>
 the_king::1:1:Elvis Presley,U-STILLHERE\elvis,S-1-5-21-1234-5678-9012-1000:/bin/sh
 </screen>
@@ -429,7 +392,7 @@ examples.  Please note that I've changed these files heavily!  There's no
 need to change them that way, it's just for testing purposes and...
 for fun.</para>
 
-<example>
+<example id="ntsec-passwd-ex-2">
 <title>/etc/passwd</title>
 <screen>
 root:*:0:0:Administrators group,S-1-5-32-544::
@@ -440,7 +403,7 @@ Guest:*:501:546:,S-1-5-21-1844237615-436374069-1060284298-501:/home/Guest:/bin/b
 </screen>
 </example>
 
-<example>
+<example id="ntsec-group-ex-2">
 <title>/etc/group</title>
 <screen>
 root:S-1-5-32-544:0:
@@ -593,7 +556,7 @@ found on <ulink url="http://docs.sun.com">http://docs.sun.com</ulink> </para>
 
 <sect2 id="ntsec-setuid"><title id="ntsec-setuid.title">New setuid concept</title>
 
-<para>UNIX applications which have to switch the user context are using
+<para>POSIX applications which have to switch the user context are using
 the <command>setuid</command> and <command>seteuid</command> calls which
 are not part of the Windows API.
 Nevertheless these calls are supported under Windows NT/W2K since Cygwin
diff --git a/winsup/doc/overview.sgml b/winsup/doc/overview.sgml
index 6e38832e8..b0b80b549 100644
--- a/winsup/doc/overview.sgml
+++ b/winsup/doc/overview.sgml
@@ -5,17 +5,15 @@
 <para>
 Cygwin is a Linux-like environment for Windows. It consists of a DLL
 (<filename>cygwin1.dll</filename>), which acts as an emulation layer
-providing substantial <ulink
-url="http://www.pasc.org/#POSIX">POSIX</ulink> (Portable Operating
-System Interface) system call functionality, and a collection of tools,
-which provide a Linux look and feel. The Cygwin DLL works with all x86
-versions of Windows since Windows 95. The API follows the <ulink
-url="http://www.opengroup.org/onlinepubs/009695399/nfindex.html">Single
+providing substantial <ulink url="http://www.pasc.org/#POSIX">POSIX</ulink>
+(Portable Operating System Interface) system call functionality, and a
+collection of tools, which provide a Linux look and feel. The Cygwin DLL
+works with all x86 and AMD64 versions of Windows NT since Windows NT 4.
+The API follows the
+<ulink url="http://www.opengroup.org/onlinepubs/009695399/nfindex.html">Single
 Unix Specification</ulink> as much as possible, and then Linux practice.
-Two other major differences between Cygwin and Linux are the C library
-(<literal>newlib</literal> instead of <literal>glibc</literal>) and
-default <command>/bin/sh</command>, which is <command>ash</command> on
-Cygwin but <command>bash</command> on most Linux distributions.
+The major differences between Cygwin and Linux is the C library
+(<literal>newlib</literal> instead of <literal>glibc</literal>).
 </para>
 <para>
 With Cygwin installed, users have access to many standard UNIX
@@ -48,8 +46,8 @@ information on how the GNU GPL may affect your use of these
 tools. If you intend to port a proprietary application using the Cygwin
 library, you may want the Cygwin proprietary-use license.
 For more information about the proprietary-use license, please go to
-<ulink url="http://www.redhat.com/software/tools/cygwin/">http://www.redhat.com/software/tools/cygwin/
-</ulink>.  Customers of the native Win32 GNUPro should feel free to submit bug
+<ulink url="http://www.redhat.com/software/tools/cygwin/">http://www.redhat.com/software/tools/cygwin/</ulink>. 
+Customers of the native Win32 GNUPro should feel free to submit bug
 reports and ask questions through the normal channels.  All other
 questions should be sent to the project mailing list
 <email>cygwin@cygwin.com</email>.</para>
@@ -60,9 +58,9 @@ questions should be sent to the project mailing list
 
 <note>
 <para>
-A more complete historical look Cygwin is Geoffrey J. Noer's 1998 paper,
-"Cygwin32: A Free Win32 Porting Layer for UNIX&reg; Applications" which can be
-found at the <ulink
+A historical look into the first years of Cygwin development is
+Geoffrey J. Noer's 1998 paper, "Cygwin32: A Free Win32 Porting Layer for
+UNIX&reg; Applications" which can be found at the <ulink
 url="http://www.usenix.org/publications/library/proceedings/usenix-nt98/technical.html">
 2nd USENIX Windows NT Symposium Online Proceedings</ulink>.
 </para>
@@ -108,6 +106,14 @@ New Cygwin Net Release</ulink> which provided the native Win32 program
 separately. Since then, the Cygwin DLL and <command>setup.exe</command> 
 have seen continuous development.
 </para>
+
+<para>
+The latest major improvement in this development is the 1.7 release in
+2008, which dropped Windows 95/98/Me support in favor of using Windows
+NT features more extensively.  It adds a lot of new features like
+case-sensitive filenames, NFS interoperability, IPv6 support and much
+more.</para>
+
 </sect1>
 
 DOCTOOL-INSERT-highlights
diff --git a/winsup/doc/overview2.sgml b/winsup/doc/overview2.sgml
index 0d7be896b..7cdc3e889 100644
--- a/winsup/doc/overview2.sgml
+++ b/winsup/doc/overview2.sgml
@@ -33,11 +33,11 @@ After installation, you can find Cygwin-specific documentation in
 the <literal>/usr/share/doc/Cygwin/</literal> directory.
 </para>
 <para>
-Developers coming from a Windows background will find a set of tools capable of
-writing console or GUI executables that rely on the Microsoft Win32 API.  The
-<command>dlltool</command> utility may be used to write Windows Dynamically
-Linked Libraries (DLLs).  The resource compiler <command>windres</command> is
-also provided.
+Developers coming from a Windows background will be able to write 
+console or GUI executables that rely on the Microsoft Win32 API instead
+of Cygwin using the -mno-cygwin option to GCC.  The <command>-shared</command>
+option allows to write Windows Dynamically Linked Libraries (DLLs).  The
+resource compiler <command>windres</command> is also provided.
 </para>
 </sect1>
 
@@ -75,7 +75,7 @@ Developers coming from a UNIX background will find a set of utilities
 they are already comfortable using, including a working UNIX shell.  The
 compiler tools are the standard GNU compilers most people will have previously
 used under UNIX, only ported to the Windows host.  Programmers wishing to port
-UNIX software to Windows NT or 9x will find that the Cygwin library provides
+UNIX software to Windows NT will find that the Cygwin library provides
 an easy way to port many UNIX packages, with only minimal source code
 changes.
 </para>
@@ -88,138 +88,148 @@ changes.
 against the library is executed, the Cygwin DLL is loaded into the
 application's text segment.  Because we are trying to emulate a UNIX kernel
 which needs access to all processes running under it, the first Cygwin DLL to
-run creates shared memory areas that other processes using separate instances
-of the DLL can access.  This is used to keep track of open file descriptors and
-assist fork and exec, among other purposes.  In addition to the shared memory
-regions, every process also has a per_process structure that contains
+run creates shared memory areas and global synchronization objects that other
+processes using separate instances of the DLL can access.  This is used to keep track of open file descriptors and to assist fork and exec, among other
+purposes.  Every process also has a per_process structure that contains
 information such as process id, user id, signal masks, and other similar
 process-specific information.</para>
 
-<para>The DLL is implemented using the Win32 API, which allows it to run on all
-Win32 hosts.  Because processes run under the standard Win32 subsystem, they
+<para>The DLL is implemented as a standard DLL in the Win32 subsystem.  Under
+the hood it's using the Win32 API, as well as the native NT API, where
+appropriate.</para>
+
+<para>Because processes run under the standard Win32 subsystem, they
 can access both the UNIX compatibility calls provided by Cygwin as well as
 any of the Win32 API calls.  This gives the programmer complete flexibility in
 designing the structure of their program in terms of the APIs used.  For
 example, they could write a Win32-specific GUI using Win32 API calls on top of
 a UNIX back-end that uses Cygwin.</para>
 
-<para>Early on in the development process, we made the important design
-decision that it would not be necessary to strictly adhere to existing UNIX
-standards like POSIX.1 if it was not possible or if it would significantly
-diminish the usability of the tools on the Win32 platform.  In many cases, an
-environment variable can be set to override the default behavior and force
-standards compliance.</para>
-</sect2>
+<para>The native NT API is used mainly for speed, as well as to access
+NT capabilities which are useful to implement certain POSIX features, but
+are hidden to the Win32 API.
+</para>
 
-<sect2 id="ov-hi-win9xnt"><title>Supporting both Windows NT and 9x</title>
-<para>While Windows 95 and Windows 98 are similar enough to each other that we
-can safely ignore the distinction when implementing Cygwin, Windows NT is an
-extremely different operating system.  For this reason, whenever the DLL is
-loaded, the library checks which operating system is active so that it can act
-accordingly.</para>
-
-<para>In some cases, the Win32 API is only different for
-historical reasons.  In this situation, the same basic functionality is
-available under Windows 9x and NT but the method used to gain this
-functionality differs.  A trivial example: in our implementation of
-uname, the library examines the sysinfo.dwProcessorType structure
-member to figure out the processor type under Windows 9x.  This field
-is not supported in NT, which has its own operating system-specific
-structure member called sysinfo.wProcessorLevel.</para>
-
-<para>Other differences between NT and 9x are much more fundamental in
-nature.  The best example is that only NT provides a security model.</para>
+<para>Due to some restrictions in Windows, it's not always possible
+to strictly adhere to existing UNIX standards like POSIX.1.  Fortunately
+these are mostely border cases.</para>
 </sect2>
 
 <sect2 id="ov-hi-perm"><title>Permissions and Security</title>
 <para>Windows NT includes a sophisticated security model based on Access
-Control Lists (ACLs).  Cygwin maps Win32 file ownership and permissions to the
-more standard, older UNIX model by default.  Cygwin version 1.1 introduces
-support for ACLs according to the system calls used on newer versions of
-Solaris. This ability is used when the `ntsec' feature is switched on which
-is described in <xref linkend="ntsec"></xref>.
-The chmod call maps UNIX-style permissions
-back to the Win32 equivalents.  Because many programs expect to be able to find
-the /etc/passwd and /etc/group files, we provide <ulink 
-url="http://cygwin.com/cygwin-ug-net/using-utils.html#mount">utilities</ulink>
+Control Lists (ACLs).  Cygwin maps Win32 file ownership and permissions to
+ACLs by default, on file systems supporting them (usually NTFS).  Solaris
+style ACLs and accompanying function calls are also supported.
+The chmod call maps UNIX-style permissions back to the Win32 equivalents. 
+Because many programs expect to be able to find the
+<filename>/etc/passwd</filename> and
+<filename>/etc/group</filename> files, we provide <ulink 
+url="http://cygwin.com/cygwin-ug-net/using-utils.html">utilities</ulink>
 that can be used to construct them from the user and group information
 provided by the operating system.</para>
 
-<para>Under Windows NT, users with Administrator rights are permitted to 
-chown files.  With version 1.1.3 Cygwin introduced a mechanism for setting real
-and effective UIDs under Windows NT/W2K. This is described in 
-<xref linkend="ntsec"></xref>.  As of version 1.5.13, the Cygwin developers
-are not aware of any feature in the Cygwin DLL that would allow users to gain
-privileges or to access objects to which they have no rights under Windows.
-However there is no guarantee that Cygwin is as secure as the Windows it runs
-on. Cygwin processes share some variables and are thus easier targets of
-denial of service type of attacks.
+<para>Users with Administrator rights are permitted to chown files.
+With version 1.1.3 Cygwin introduced a mechanism for setting real and
+effective UIDs. This is described in <xref linkend="ntsec"></xref>.  As
+of version 1.5.13, the Cygwin developers are not aware of any feature in
+the Cygwin DLL that would allow users to gain privileges or to access
+objects to which they have no rights under Windows.  However there is no
+guarantee that Cygwin is as secure as the Windows it runs on. Cygwin
+processes share some variables and are thus easier targets of denial of
+service type of attacks.
 </para>
 
-<para>Under Windows 9x, the situation is considerably different.  Since a
-security model is not provided, Cygwin fakes file ownership by making all
-files look like they are owned by a default user and group id.  As under NT,
-file permissions can still be determined by examining their read/write/execute
-status.  Rather than return an unimplemented error, under Windows 9x, the
-chown call succeeds immediately without actually performing any action
-whatsoever.  This is appropriate since essentially all users jointly own the
-files when no concept of file ownership exists.</para>
-
 </sect2>
 
 <sect2 id="ov-hi-files"><title>File Access</title> <para>Cygwin supports
-both Win32- and POSIX-style paths, using either forward or back slashes as the
-directory delimiter.  Paths coming into the DLL are translated from Win32 to
-POSIX as needed.  As a result, the library believes that the file system is a
-POSIX-compliant one, translating paths back to Win32 paths whenever it calls a
-Win32 API function.  UNC pathnames (starting with two slashes) are
-supported.</para>
-
-<para>The layout of this POSIX view of the Windows file system space is stored
-in the Windows registry.  While the slash ('/') directory points to the system
-partition by default, this is easy to change with the Cygwin mount utility.
-In addition to selecting the slash partition, it allows mounting arbitrary
-Win32 paths into the POSIX file system space.  Many people use the utility to
-mount each drive letter under the slash partition (e.g. C:\ to /c, D:\ to /d,
-etc...).</para>
+both POSIX- and Win32-style paths, using either forward or back slashes as the
+directory delimiter.  Paths coming into the DLL are translated from POSIX to
+native NT as needed.  From the application perspective, the file system is
+a POSIX-compliant one.  The implementation details are safely hidden in the
+Cygwin DLL.  UNC pathnames (starting with two slashes) are supported for
+network paths.</para>
+
+<para>Since version 1.7.0, the layout of this POSIX view of the Windows file
+system space is stored in the <filename>/etc/fstab</filename> file.  Actually,
+there is a system-wide <filename>/etc/fstab</filename> file as well as a
+user-specific fstab file <filename>/etc/fstab.d/${USER}</filename>.</para>
+
+<para>At startup the DLL has to find out where it can find the
+<filename>/etc/fstab</filename> file.  The mechanism used for this is simple.
+First it retrieves it's own path, for instance
+<filename>C:\Cygwin\bin\cygwin1.dll</filename>.  From there it deduces
+that the root path is <filename>C:\Cygwin</filename>.  So it looks for the
+<filename>fstab</filename> file in <filename>C:\Cygwin\etc\fstab</filename>. 
+The layout of this file is very similar to the layout of the
+<filename>fstab</filename> file on Linux.  Just instead of block devices,
+the mount points point to Win32 paths.  An installation with
+<command>setup.exe</command> installs a <filename>fstab</filename> file by
+default, which can easily be changed using the editor of your choice.</para>
+
+<para>In addition to selecting the root partition, the
+<filename>fstab</filename> file allows mounting arbitrary Win32 paths into
+the POSIX file system space.  A special case is the so-called cygdrive prefix.
+It's the path under which every available drive in the system is mounted
+under its drive letter.  The default value is <filename>/cygdrive</filename>,
+so you can access the drives as <filename>/cygdrive/c</filename>,
+<filename>/cygdrive/d</filename>, etc...  The cygdrive prefix can be set to
+some other value (<filename>/mnt</filename> for instance) in the
+<filename>fstab</filename> file(s).</para>
 
 <para>The library exports several Cygwin-specific functions that can be used
 by external programs to convert a path or path list from Win32 to POSIX or vice
 versa.  Shell scripts and Makefiles cannot call these functions directly.
-Instead, they can do the same path translations by executing the cygpath
-utility program that we provide with Cygwin.</para>
-
-<para>Win32 file systems are case preserving but case insensitive.  Cygwin
-does not currently support case distinction because, in practice, few UNIX
-programs actually rely on it.  While we could mangle file names to support case
-distinction, this would add unnecessary overhead to the library and make it
-more difficult for non-Cygwin applications to access those files.</para>
-
-<para>Symbolic links are emulated by files containing a magic cookie followed
-by the path to which the link points.  They are marked with the System
-attribute so that only files with that attribute have to be read to determine
-whether or not the file is a symbolic link.  Hard links are fully supported
-under Windows NT on NTFS file systems.  On a FAT file system, the call falls
-back to simply copying the file, a strategy that works in many cases.</para>
-
-<para>The inode number for a file is calculated by hashing its full Win32 path.
-The inode number generated by the stat call always matches the one returned in
-d_ino of the dirent structure.  It is worth noting that the number produced by
-this method is not guaranteed to be unique.  However, we have not found this to
-be a significant problem because of the low probability of generating a
-duplicate inode number.</para>
-
-<para>Chroot is supported since release 1.1.3. Note that chroot isn't
-supported native by Windows. This implies some restrictions. First of all,
-the chroot call isn't a privileged call. Each user may call it. Second, the
-chroot environment isn't safe against native windows processes. If you
-want to support a chroot environment as, for example, by allowing an
-anonymous ftp with restricted access, you'll have to care that only
-native Cygwin applications are accessible inside of the chroot environment.
-Since that applications are only using the Cygwin POSIX API to access the
-file system their access can be restricted as it is intended. This includes
-not only POSIX paths but Win32 paths (containing drive letter and/or
-backslashes) and CIFS paths (//server/share or \\server\share) as well.</para>
+Instead, they can do the same path translations by executing the
+<command>cygpath</command> utility program that we provide with Cygwin.</para>
+
+<para>Win32 applications handle filenames case preserving but case
+insensitive.  Cygwin supports case sensitivity on file systems supporting
+that.  Since Windows XP, the OS only supports case sensitivity when a
+specific registry value is changed.  Therefore case sensitivity is not
+the default usually.</para>
+
+<para>Symbolic links are not present and supported on Windows up to and
+including Windows Server 2003 R2.  Only starting with Windows Vista,
+native symlinks are available.  Unfortunately they are strangly implemented
+and so not very useful for a POSIX emulation layer.  Consequentially
+Cygwin recognizes them as symlinks but does not create them.</para>
+
+<para>Symbolic links are potentially created in two different ways.
+The file style symlinks are files containing a magic cookie followed by
+the path to which the link points.  They are marked with the System DOS
+attribute so that only files with that attribute have to be read to
+determine whether or not the file is a symbolic link.  The shortcut style
+symlinks are Windows shortcut files with a special header and the
+Readonly DOS attribute set.  The advantage of file symlinks is speed,
+the advantage of shortcut symlinks is the fact that they can be utilized
+by non-Cygwin Win32 tools as well.</para>
+
+<para>Hard links are fully supported on NTFS and NFS file systems.  On FAT
+and some other file systems, the call falls back to simply copying the file,
+a strategy that works in many cases.</para>
+
+<para>On file systems which don't support unique persistent file IDs (FAT,
+older Samba shares) the inode number for a file is calculated by hashing its
+full Win32 path.  The inode number generated by the stat call always matches
+the one returned in <literal>d_ino</literal> of the <literal>dirent</literal>
+structure.  It is worth noting that the number produced by this method is not
+guaranteed to be unique.  However, we have not found this to be a significant
+problem because of the low probability of generating a duplicate inode number.
+</para>
+
+<para><function>chroot(2)</function> is supported since Cygwin 1.1.3.
+However, chroot is not a concept known by Windows.  This implies some
+restrictions.  First of all, the <function>chroot</function> call isn't a
+privileged call.  Each user may call it.  Second, the chroot environment
+isn't safe against native windows processes.  If you want to support a
+chroot environment as, for example, by allowing an anonymous ftp with
+restricted access, you'll have to care that only native Cygwin applications
+are accessible inside of the chroot environment.  Since those applications
+are only using the Cygwin POSIX API to access the file system their access
+can be restricted as it is intended.  This includes not only POSIX paths but
+Win32 paths containing drive letter and/or backslashes as well as UNC paths
+(<filename>//server/share</filename> or <filename>\\server\share</filename>).
+</para>
 </sect2>
 
 <sect2 id="ov-hi-textvsbinary"><title>Text Mode vs. Binary Mode</title>
@@ -246,7 +256,9 @@ set to override this behavior.</para>
 "newlib" as part of the library, rather than write all of the lib C
 and math calls from scratch.  Newlib is a BSD-derived ANSI C library,
 previously only used by cross-compilers for embedded systems
-development.</para>
+development.  Other functions, which are not supported by newlib have
+been added to the Cygwin sources using BSD implementations as much as
+possible.</para>
 
 <para>The reuse of existing free implementations of such things
 as the glob, regexp, and getopt libraries saved us considerable
@@ -258,8 +270,8 @@ malloc if it so desires.</para>
 </sect2>
 
 <sect2 id="ov-hi-process"><title>Process Creation</title>
-<para>The fork call in Cygwin is particularly interesting because it
-does not map well on top of the Win32 API.  This makes it very
+<para>The <function>fork</function> call in Cygwin is particularly interesting
+because it does not map well on top of the Win32 API.  This makes it very
 difficult to implement correctly.  Currently, the Cygwin fork is a
 non-copy-on-write implementation similar to what was present in early
 flavors of UNIX.</para>
@@ -335,26 +347,43 @@ it.</para>
 </sect2>
 
 <sect2 id="ov-hi-sockets"><title>Sockets</title>
-<para>Socket-related calls in Cygwin simply
-call the functions by the same name in Winsock, Microsoft's
-implementation of Berkeley sockets.  Only a few changes were needed to
-match the expected UNIX semantics - one of the most troublesome
-differences was that Winsock must be initialized before the first
-socket function is called.  As a result, Cygwin has to perform this
-initialization when appropriate.  In order to support sockets across
-fork calls, child processes initialize Winsock if any inherited file
-descriptor is a socket.</para>
-
-<para>Unfortunately, implicitly loading DLLs
-at process startup is usually a slow affair.  Because many processes
-do not use sockets, Cygwin explicitly loads the Winsock DLL the
-first time it calls the Winsock initialization routine.  This single
-change sped up GNU configure times by thirty
-percent.</para>
+<para>Socket-related calls in Cygwin basically call the functions by the
+same name in Winsock, Microsoft's implementation of Berkeley sockets, but
+with lots of tweaks.  All sockets are non-blocking under the hood to allow
+to interrupt blocking calls by POSIX signals.  Additional bookkeeping is
+necessary to implement correct socket sharing POSIX semantics and especially
+for the select call.  Some socket-related functions are not implemented at
+all in Winsock, as, for example, socketpair.  Starting with Windows Vista,
+Microsoft removed the legacy calls <function>rcmd(3)</function>,
+<function>rexec(3)</function> and <function>rresvport(3)</function>.
+Recent versions of Cygwin now implement all these calls internally.</para>
+
+<para>An especially troublesome feature of Winsock is that it must be
+initialized before the first socket function is called.  As a result, Cygwin
+has to perform this initialization on the fly, as soon as the first
+socket-related function is called by the application.  In order to support
+sockets across fork calls, child processes initialize Winsock if any
+inherited file descriptor is a socket.</para>
+
+<para>AF_UNIX (AF_LOCAL) sockets are not available in Winsock.  They are
+implemented in Cygwin by using local AF_INET sockets instead.  This is
+completely transparent to the application.  Cygwin's implementation also
+supports the getpeereid BSD extension.  A yet missing feature is
+descriptor passing, though.</para>
+
+<para>Starting with release 1.7.0, Cygwin gets IPv6 support.  However, this
+depends on the availability of the Windows IPv6 stack.  Up to Windows 2003,
+the IPv6 stack is treated as "experimental" and it's not feature complete.
+Full support is only available starting with Windows Vista and Windows Server
+2008.  The newly implemented <function>getaddrinfo</function> and
+<function>getnameinfo</function> functions are not dependent on the OS,
+though.  Cygwin 1.7.0 adds replacement functions which implement the full
+functionality for IPv4.</para>
+
 </sect2>
 
 <sect2 id="ov-hi-select"><title>Select</title>
-<para>The UNIX select function is another
+<para>The UNIX <function>select</function> function is another
 call that does not map cleanly on top of the Win32 API.  Much to our
 dismay, we discovered that the Win32 select in Winsock only worked on
 socket handles.  Our implementation allows select to function normally
diff --git a/winsup/doc/pathnames.sgml b/winsup/doc/pathnames.sgml
index 8dc55d7c2..403505295 100644
--- a/winsup/doc/pathnames.sgml
+++ b/winsup/doc/pathnames.sgml
@@ -1,6 +1,6 @@
 <sect1 id="using-pathnames"><title>Mapping path names</title>
 
-<sect2><title>Introduction</title>
+<sect2 id="pathnames-intro"><title>Introduction</title>
 
 <para>Cygwin supports both Win32- and POSIX-style paths, where
 directory delimiters may be either forward or back slashes.  UNC
@@ -24,41 +24,112 @@ necessary.</para>
 
 <sect2 id="mount-table"><title>The Cygwin Mount Table</title>
 
-<para>The <command>mount</command> utility program is used to
-to map Win32 drives and network shares into Cygwin's internal POSIX
-directory tree.  This is a similar concept to the typical UNIX mount
-program.  For those people coming from a Windows background, the
-<command>mount</command> utility is very similar to the old DOS
-<command>join</command>, in that it makes your drive letters appear as
-subdirectories somewhere else.</para>
-
-<para>The mapping is stored in the current user's Cygwin
-<firstterm>mount table</firstterm> in the Windows registry so that the
-information will be retrieved next time the user logs in.  Because it
-is sometimes desirable to have system-wide as well as user-specific
-mounts, there is also a system-wide mount table that all Cygwin users
-inherit.  The system-wide table may only be modified by a user with
-the appropriate privileges (Administrator privileges in Windows
-NT).</para>
-
-<para>The current user's table is located under
-"HKEY_CURRENT_USER/Software/Cygnus Solutions/Cygwin/mounts
-v&lt;version&gt;"
-where &lt;version&gt; is the latest registry version associated with
-the Cygwin library (this version is not the same as the release
-number).  The system-wide table is located under the same subkeys
-under HKEY_LOCAL_SYSTEM.  The user mount table takes precedence over 
-the system-wide table if a path is mounted in both.  This includes the
-setting of the cygdrive prefix.</para>
-
-<para>The <command>mount</command> command can set the POSIX root
-<filename>/</filename> to any directory in the Windows file system.
-In absence of such a mount, Cygwin maps <filename>/</filename> to the
-root of the current Windows working directory (for example, 
-<filename>H:\</filename> or <filename>\\computer\share</filename>). 
-Normally Cygwin's <command>setup.exe</command> creates the initial
-mount point for the POSIX root. 
-</para>
+<para>The <filename>/etc/fstab</filename> file is used to map Win32
+drives and network shares into Cygwin's internal POSIX directory tree.
+This is a similar concept to the typical UNIX fstab file.  The mount
+points stored in <filename>/etc/fstab</filename> are globally set for
+all users.  Sometimes there's a requirement to have user specific
+mount points.  The Cygwin DLL supports user specific fstab files.
+These are stored in the directory <filename>/etc/fstab.d</filename>
+and the name of the file is the Cygwin username of the user, as it's
+stored in the <filename>/etc/passwd</filename> file.  The content of the
+user specifc file is identical to the system-wide
+<filename>fstab</filename> file.</para>
+
+<para>The file fstab contains descriptive information about the various file
+systems.  fstab is only read by programs, and not written; it is the
+duty of the system administrator to properly create and maintain this
+file.  Each filesystem is described on a separate line; fields on each
+line are separated by tabs or spaces.  Lines starting with '#' are
+comments.</para>
+
+<para>The first field describes the block special device or
+remote filesystem to be mounted.  On Cygwin, this is the native Windows
+path which the mount point links in.  As path separator you MUST use a
+slash.  Usage of a backslash might lead to unexpected results.  UNC
+paths (using slashes, not backslashes) are allowed.  If the path
+contains spaces these can be escaped as <literal>'\040'</literal>.</para>
+
+<para>The second field describes the mount point for the filesystem. 
+If the name of the mount point contains spaces these can be
+escaped as '\040'.</para>
+
+<para>The third field describes the type of the filesystem.
+Cygwin supports any string here, since the file system type is usually
+not evaluated.  The noticable exception is the file system type
+cygdrive.  This type is used to set the cygdrive prefix.</para>
+
+<para>The fourth field describes the mount options associated
+with the filesystem.  It is formatted as a comma separated list of
+options.  It contains at least the type of mount (binary or text) plus
+any additional options appropriate to the filesystem type.  Recognized
+options are binary, text, nouser, user, exec, notexec, cygexec, nosuid,
+posix=[0|1].  The meaning of the options is as follows.</para>
+
+<screen>
+  acl      - Cygwin uses the filesystem's access control lists (ACLs) to
+             implement real POSIX permissions (default).  This flag only
+	     affects filesystems supporting ACLs (NTFS) and is ignored
+	     otherwise.
+  noacl    - Cygwin ignores filesystem ACLs and only fakes a subset of
+	     permission bits based on the DOS readonly attribute.  This
+	     behaviour is the default on FAT and FAT32.  The flag is
+	     ignored on NFS filesystems.
+  binary   - Files default to binary mode (default).
+  text     - Files default to CRLF text mode line endings.
+  nouser   - Mount is a system-wide mount.
+  user     - Mount is a user mount.
+  exec     - Treat all files below mount point as executable.
+  notexec  - Treat all files below mount point as not executable.
+  cygexec  - Treat all files below mount point as cygwin executables.
+  nosuid   - No suid files are allowed (currently unimplemented).
+  posix=0  - Switch off case sensitivity for paths under this mount point.
+  posix=1  - Switch on case sensitivity for paths under this mount point
+	     (default).
+</screen>
+
+<para>Note that nouser mount points are not overridable by a later call
+to mount(2).  This is only possible for user mount points.  Mount points
+are by default nouser mount points, unless you specify the option user. 
+In contrast, all mount points in the user specific fstab file are user
+mount points.</para>
+
+<para>The fifth and sixth field are ignored.  They are
+so far only specified to keep a Linux-like fstab file layout.</para>
+
+<para>Note that you don't have to specify an fstab entry for the root dir,
+unless you want to have the root dir pointing to somewhere entirely
+different (hopefully you know what you're doing), or if you want to
+mount the root dir with special options (for instance, as text mount).</para>
+
+<para>Example entries:</para>
+
+<itemizedlist spacing="compact">
+<listitem>
+  <para>Just a normal mount point:</para>
+  <screen>c:/foo /bar fat32 binary 0 0</screen>
+</listitem>
+<listitem>
+  <para>A mount point for a managed, textmode mount:</para>
+  <screen>C:/foo /bar/baz ntfs text,managed 0 0</screen>
+</listitem>
+<listitem>
+  <para>A mount point for a Windows directory with spaces in it:</para>
+  <screen>C:/Documents\040and\040Settings /docs ext3 binary 0 0</screen>
+</listitem>
+<listitem>
+  <para>A mount point for a remote directory:</para>
+  <screen>//server/share/subdir /srv/subdir smbfs binary 0 0</screen>
+</listitem>
+<listitem>
+  <para>This is just a comment:</para>
+  <screen># This is just a comment</screen>
+</listitem>
+<listitem>
+  <para>Set the cygdrive prefix to /mnt:</para>
+  <screen>none /mnt cygdrive binary 0 0</screen>
+</listitem>
+</itemizedlist>
 
 <para>Whenever Cygwin generates a Win32 path from a POSIX one, it uses
 the longest matching prefix in the mount table.  Thus, if
@@ -70,19 +141,14 @@ POSIX equivalent current directory.  Otherwise, the handling of MS-DOS
 filenames bypasses the mount table.
 </para>
 
-<para>Invoking <command>mount</command> without any arguments displays
-Cygwin's current set of mount points.
-In the following example, the C
-drive 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
-to the current user.</para>
+<para>If you want to see the current set of mount points valid in your
+session, you can invoking the Cygwin tool <command>mount</command> without
+arguments:</para>
 
-<example>
+<example id="pathnames-mount-ex">
 <title>Displaying the current set of mount points</title>
 <screen>
-<prompt>c:\&gt;</prompt> <userinput>mount</userinput>
+<prompt>bash-3.2$</prompt> <userinput>mount</userinput>
 f:\cygwin\bin on /usr/bin type system (binmode)
 f:\cygwin\lib on /usr/lib type system (binmode)
 f:\cygwin on / type system (binmode)
@@ -94,9 +160,10 @@ e: on /cygdrive/e type user (binmode,noumount)
 
 <para>You can also use the <command>mount</command> command to add
 new mount points, and the <command>umount</command> to delete
-them.  See <xref linkend="mount"></xref> and <xref linkend="umount"></xref> for more
-information on how to use these utilities to set up your Cygwin POSIX
-file system.</para>
+them.  However, since they are only noted in memory, these mount
+points will disappear as soon as your last Cygwin process ends.
+See <xref linkend="mount"></xref> and <xref linkend="umount"></xref> for more
+information.</para>
 
 <para>Whenever Cygwin cannot use any of the existing mounts to convert
 from a particular Win32 path to a POSIX one, Cygwin will
@@ -105,19 +172,12 @@ path <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> would be automatically
 converted to <filename>/cygdrive/Z</filename>.  The default
-prefix of <filename>/cygdrive</filename> may be changed (see the
-<xref linkend="mount"></xref> for more information).</para>
-
-<para>It is possible to assign some special attributes to each mount
-point.  Automatically mounted partitions are displayed as "auto"
-mounts.  Mounts can also be marked as either "textmode" or "binmode"
--- whether text files are read in the same manner as binary files by
-default or not (see <xref linkend="using-textbinary"></xref> for more
-information on text and binary modes.</para>
+prefix of <filename>/cygdrive</filename> may be changed in the fstab file
+as outlined above.</para>
 
 </sect2>
 
-<sect2><title>Additional Path-related Information</title>
+<sect2 id="pathnames-additional"><title>Additional Path-related Information</title>
 
 <para>The <command>cygpath</command> program provides the ability to
 translate between Win32 and POSIX pathnames in shell scripts. See
@@ -150,23 +210,113 @@ not by default, for example).</para>
 
 <sect1 id="using-specialnames"><title>Special filenames</title>
 
-<sect2> <title>DOS devices</title>
+<sect2 id="pathnames-dosdevices">
+<title>DOS devices</title>
 
-<para>Windows filenames invalid under Windows are also invalid under
-Cygwin.  This means that base filenames such as 
+<para>Filenames invalid under Win32 are not necessarily invalid
+under Cygwin since release 1.7.0.  There are a couple of rules which
+apply to Windows filenames.  First of all, DOS device names like
 <filename>AUX</filename>, <filename>COM1</filename>,
 <filename>LPT1</filename> or <filename>PRN</filename> (to name a few)
-cannot be used in a regular Cygwin Windows or POSIX path, even with an
-extension (<filename>prn.txt</filename>). However the special names can be
-used as filename extensions (<filename>file.aux</filename>). You can use
-the special names as you would under DOS, for example you can print on your
-default printer with the command <command>cat filename > PRN</command>
-(make sure to end with a Form Feed).
+cannot be used in a native Win32 application, even with an
+extension (<filename>prn.txt</filename>).  Cygwin can handle files with
+these names just fine.</para>
+
+</sect2>
+
+<sect2 id="pathnames-specialchars">
+<title>Special characters in filenames</title>
+
+<para>Win32 filenames can't contain trailing dots and spaces for backward
+compatibility.  When trying to create files with trailing dots or spaces,
+all of them are removed before the file is created.  This restriction does
+only affect native Win32 applications.  Cygwin applications can create and
+access files with trailing dots and spaces without problems.</para>
+
+<para>Some characters are disallowed in filenames on Windows filesystems:</para>
+
+<screen>
+  "   *   :   &lt;   &gt;   ?   |   \
+</screen>
+
+<para>Cygwin can't fix this, but it has a method to workaround this
+restriction.  All of the above characters, except for the backslash,
+are converted to special UNICODE characters in the range 0xf000 to 0xf0ff
+(the "Private use area") when creating or accessing files.</para>
+
+</sect2>
+
+<sect2 id="pathnames-casesensitive">
+<title>Case sensitive filenames</title>
+
+<para>In the Win32 subsystem filenames are only case-preserved, but not
+case-sensitive.  You can't access two files in the same directory which
+only differ by case, like <filename>Abc</filename> and
+<filename>aBc</filename>.  While NTFS (and some remote filesystems)
+support case-sensitivity, the NT kernel starting with Windows XP does
+not support it by default.  Rather, you have to tweak a registry setting
+and reboot.  For that reason, case-sensitivity is not supported by Cygwin,
+unless you change that registry value.</para>
+
+<para>If you really want case-sensitivity in Cygwin, you can switch it
+on by setting the registry value</para>
+
+<screen>
+HKLM\SYSTEM\CurrentControlSet\Control\Session Manager\kernel\obcaseinsensitive
+</screen>
+
+<para>to 0 and reboot the machine.  For least surprise, Cygwin expects
+this registry value also on Windows NT4 and Windows 2000, which usually
+both don't know this registry key.  If you want case-sensitivity on these
+systems, create that registry value and set it to 0.  On these systems
+(and *only* on these systems) you don't have to reboot to bring it
+into effect.</para>
+
+<note>
+<para>
+Note that when installing Microsoft's Services For Unix (SFU), you're asked if
+you want to use case-sensitive filenames.  If you answer "yes" at this point,
+the installer will change the aforementioned registry value to 0, too.  So, if
+you have SFU installed, there's some chance that the registry value is already
+set to case sensitivity.
 </para>
+</note>
+
+<para>After you set this registry value to 0, Cygwin will be case-sensitive
+by default on NTFS and NFS filesystems.  Be aware that using two filenames
+which only differ by case might result in some weird interoperability
+issues with native Win32 applications.  You're using case-sensitivity 
+at your own risk.  You have been warned!</para>
+
+<para>Even if you use case-sensitivity, it might be feasible to switch to
+case-insensitivity for certain paths for better interoperability with
+native Win32 applications (even if it's just Windows Explorer).  You can do
+this on a per-mount point base, by using the "posix=0" mount option in
+/etc/fstab, or your /etc/fstab.d/$USER file.</para>
+
+<para>For a start, it might be best to switch the cygdrive path to
+case-insensitivity, because the default Windows $PATH variable is not
+always using the correct case by default.  As a result, your shell will
+claim that it can't find Windows commands like <command>attrib</command>
+or <command>net</command>.  Here's an example how you can switch the
+cygdrive prefix to case-insensitivity:</para>
+
+<example id="mount-caseinsensitive">
+<title>Example mount point to enforce case-insensitivity on cygdrive paths</title>
+<screen>
+none /cygdrive cygdrive binary,posix=0 0 0
+</screen>
+</example>
+
+<para>Note that mount points as well as device names and virtual
+paths like /proc are always case-sensitive!  The only exception are
+the subdirs and filenames under /proc/registry, /proc/registry32
+and /proc/registry64.  Registry access is always case-insensitive.
+Read on for more information.</para>
 
 </sect2>
 
-<sect2> <title>POSIX devices</title>
+<sect2 id="pathnames-posixdevices"> <title>POSIX devices</title>
 <para>There is no need to create a POSIX <filename>/dev</filename> 
 directory as Cygwin automatically simulates it internally. 
 These devices cannot be seen with the command <command>ls /dev/</command>
@@ -177,67 +327,97 @@ If you want to be able to see all devices in
 url="http://cygwin.com/ml/cygwin/2004-03/txt00028.txt">create_devices.sh</ulink>
 script.
 </para>
+
 <para>
-Cygwin supports the following devices commonly found on POSIX systems:
-<filename>/dev/dsp</filename>, <filename>/dev/null</filename>, 
-<filename>/dev/zero</filename>, <filename>/dev/console</filename>,
-<filename>/dev/tty</filename>, <filename>/dev/ttym</filename>, 
-<filename>/dev/ttyX</filename>, <filename>/dev/ttySX</filename>, 
-<filename>/dev/pipe</filename>, <filename>/dev/port</filename>, 
-<filename>/dev/ptmx</filename>, <filename>/dev/mem</filename>,
-<filename>/dev/random</filename>, and <filename>/dev/urandom</filename>.
-Some other POSIX devices, such as 
-<filename>/dev/kmem</filename>, are planned for development.
-Cygwin also has several Windows-specific devices:
-<filename>/dev/comX</filename> (the serial ports, starting with 
-<filename>COM1</filename> which is the same as <filename>ttyS0</filename>),
-<filename>/dev/conin</filename> (Windows <filename>CONIN$</filename>),
-<filename>/dev/conout</filename> (Windows <filename>CONOUT$</filename>),
-<filename>/dev/clipboard</filename> (the Windows clipboard, currently
-text only), and <filename>/dev/windows</filename> (the Windows message
-queue).
+Cygwin supports the following character devices commonly found on POSIX systems:
 </para>
 
-<para>Windows NT/W2K/XP additionally support raw devices like floppies,
-disks, partitions and tapes.  These are accessed from Cygwin applications
-using POSIX device names which are supported in two different ways.
-</para>
+<screen>
+/dev/null
+/dev/zero
+/dev/full
+
+/dev/console	Pseudo device name for the standard console window created
+		by Windows.  Same as the one used for cmd.exe.  Every one
+		of them has this name.  It's not quite comparable with the
+		console device on UNIX machines.
 
-<para>Up to Cygwin 1.3.3 the only way to access those devices was
-to mount the Win32 device names to a POSIX device name but this usage
-is discouraged since Cygwin 1.3.4 and only kept for backward compatibility.
+/dev/tty	The current tty of a session running in a pseudo tty.
+/dev/ptmx	Pseudo tty master device.
+/dev/ttym
+
+/dev/tty0	Pseudo ttys are numbered from /dev/tty0 upwards as they are
+/dev/tty1	requested.
+...
+
+/dev/ttyS0	Serial communication devices.  ttyS0 == Win32 COM1,
+/dev/ttyS1	ttyS1 == COM2, etc.
+...
+
+/dev/pipe
+/dev/fifo
+
+/dev/mem	The physical memory of the machine.  Note that access to the
+/dev/port	physical memory has been restricted with Windows Server 2003.
+/dev/kmem	Since this OS, you can't access physical memory from user space.
+
+/dev/kmsg	Kernel message pipe, for usage with sys logger services.
+
+/dev/random	Random number generator.
+/dev/urandom
+
+/dev/dsp	Default sound device of the system.
+</screen>
+
+<para>
+Cygwin also has several Windows-specific devices:
 </para>
 
+<screen>
+/dev/com1	The serial ports, starting with COM1 which is the same as ttyS0.
+/dev/com2	Please use /dev/ttySx instead.
+...
+
+/dev/conin	Same as Windows CONIN$.
+/dev/conout	Same as Windows CONOUT$.
+/dev/clipboard	The Windows clipboard, text only
+/dev/windows	The Windows message queue.
+</screen>
+
 <para>
-Beginning with Cygwin 1.3.4, raw devices are accessible by Cygwin processes
-using fixed POSIX device names.  These fixed POSIX device names are generated
-using a direct conversion from the POSIX namespace to the internal NT namespace.
+Block devices are accessible by Cygwin processes using fixed POSIX device
+names.  These POSIX device names are generated using a direct conversion
+from the POSIX namespace to the internal NT namespace.
 E.g. the first harddisk is the NT internal device \device\harddisk0\partition0
 or the first partition on the third harddisk is \device\harddisk2\partition1.
 The first floppy in the system is \device\floppy0, the first CD-ROM is
-\device\cdrom0 and the first tape drive is \device\tape0.
+\device\cdrom0 and the first tape drive is \device\tape0.  The mapping
+to the POSIX /dev namespace is as follows:
 </para>
 
-<para>The new fixed POSIX names are mapped to NT internal devices as
-follows:</para>
-
 <screen>
 /dev/st0	\device\tape0, rewind
 /dev/nst0	\device\tape0, no-rewind
 /dev/st1	\device\tape1
+/dev/nst1	\device\tape1
 ...
+/dev/st15
+/dev/nst15
 
 /dev/fd0	\device\floppy0
 /dev/fd1	\device\floppy1
 ...
-
-/dev/scd0	\device\cdrom0
-/dev/scd1	\device\cdrom1
-...
+/dev/fd15
 
 /dev/sr0	\device\cdrom0
 /dev/sr1	\device\cdrom1
 ...
+/dev/sr15
+
+/dev/scd0	\device\cdrom0
+/dev/scd1	\device\cdrom1
+...
+/dev/scd15
 
 /dev/sda	\device\harddisk0\partition0	(whole disk)
 /dev/sda1	\device\harddisk0\partition1	(first partition)
@@ -249,10 +429,10 @@ follows:</para>
 
 [up to]
 
-/dev/sdl	\device\harddisk11\partition0
-/dev/sdl1	\device\harddisk11\partition1
+/dev/sddx	\device\harddisk127\partition0
+/dev/sddx1	\device\harddisk127\partition1
 ...
-/dev/sdl15	\device\harddisk11\partition15
+/dev/sddx15	\device\harddisk127\partition15
 </screen>
 
 <para>
@@ -261,32 +441,16 @@ links as they are created on Linux systems for convenience:
 </para>
 
 <screen>
-ln -s /dev/scd0 /dev/cdrom
-ln -s /dev/nst0  /dev/tape
+ln -s /dev/sr0 /dev/cdrom
+ln -s /dev/nst0 /dev/tape
 ...
 </screen>
 
-<warning>
-<para>
-Note that you can't use the mount table to map from a fixed device name
-to your own device name or to map from internal NT device name to
-your own device name.  Also using symbolic links to map from the internal
-NT device name to your own device name will not do what you want.
-The following three examples will not work as expected:
-</para>
-
-<screen>
-mount -f -b /dev/nst0 /dev/tape     # DOES NOT WORK
-mount -f -b /device/tape0 /dev/tape # DOES NOT WORK
-ln -s /device/tape0 /dev/tape       # DOES NOT WORK
-</screen>
-</warning>
-
 </sect2>
 
-<sect2><title>The .exe extension</title>
+<sect2 id="pathnames-exe"><title>The .exe extension</title>
 
-<para> Executable program filenames end with <filename>.exe</filename>
+<para>Win32 executable filenames end with <filename>.exe</filename>
 but the <filename>.exe</filename> need not be included in the command,
 so that traditional UNIX names can be used.  However, for programs that
 end in <filename>.bat</filename> and <filename>.com</filename>, you
@@ -319,18 +483,9 @@ Cygwin 1.5.19.  It has been changed for consistency with the rest of Cygwin.
 <filename>filename</filename>. This allows many makefiles written
 for UNIX systems to work well under Cygwin.</para>
 
-<para>Unfortunately, the <command>install</command> and
-<command>strip</command> commands do distinguish between
-<filename>filename</filename> and <filename>filename.exe</filename>. They
-fail when working on a non-existing <filename>filename</filename> even if
-<filename>filename.exe</filename> exists, thus breaking some makefiles.
-This problem can be solved by writing <command>install</command> and
-<command>strip</command> shell scripts to provide the extension ".exe"
-when needed.
-</para>
 </sect2>
 
-<sect2><title>The /proc filesystem</title> 
+<sect2 id="pathnames-proc"><title>The /proc filesystem</title> 
 <para>
 Cygwin, like Linux and other similar operating systems, supports the
 <filename>/proc</filename> virtual filesystem. The files in this
@@ -344,7 +499,12 @@ is <filename>/proc/registry</filename>, which displays the Windows
 registry with each <literal>KEY</literal> as a directory and each
 <literal>VALUE</literal> as a file. As anytime you deal with the
 Windows registry, use caution since changes may result in an unstable
-or broken system.
+or broken system.  There are additionally subdirectories called
+<filename>/proc/registry32</filename> and <filename>/proc/registry64</filename>.
+They are identical to <filename>/proc/registry</filename> on 32 bit
+host OSes.  On 64 bit host OSes, <filename>/proc/registry32</filename>
+opens the 32 bit processes view on the registry, while
+<filename>/proc/registry64</filename> opens the 64 bit processes view.
 </para>
 <para>
 The Cygwin <filename>/proc</filename> is not as complete as the
@@ -354,7 +514,7 @@ that use it.
 </para>
 </sect2>
 
-<sect2><title>The @pathnames</title> 
+<sect2 id="pathnames-at"><title>The @pathnames</title> 
 <para>To circumvent the limitations on shell line length in the native
 Windows command shells, Cygwin programs expand their arguments
 starting with "@" in a special way.  If a file
@@ -366,7 +526,7 @@ Embedded double quotes must be repeated.
 In the following example compare the behaviors of the bash built-in
 <command>echo</command> and of the program <command>/bin/echo</command>.</para>
 
-<example><title> Using @pathname</title>
+<example id="pathnames-at-ex"><title> Using @pathname</title>
 <screen>
 <prompt>bash$</prompt> <userinput>echo  'This   is   "a     long"  line' > mylist</userinput>
 <prompt>bash$</prompt> <userinput>echo @mylist</userinput>
diff --git a/winsup/doc/setup-net.sgml b/winsup/doc/setup-net.sgml
index c098c32ea..165924d07 100644
--- a/winsup/doc/setup-net.sgml
+++ b/winsup/doc/setup-net.sgml
@@ -35,7 +35,7 @@ to make use of <ulink url="http://www.google.com/search?q=new+to+unix">
 other resources</ulink>.
 </para>
 
-<sect2><title>Download Source</title>
+<sect2 id="setup-download"><title>Download Source</title>
 <para>
 Cygwin uses packages to manage installing various software. When
 the default <literal>Install from Internet</literal> option is chosen,
@@ -69,7 +69,7 @@ this; search the list for <command>mkcygwget</command> for ideas.
 </para>
 </sect2>
 
-<sect2><title>Selecting an Install Directory</title>
+<sect2 id="setup-dir"><title>Selecting an Install Directory</title>
 <para>
 The <literal>Root Directory</literal> for Cygwin (default
 <literal>C:\cygwin</literal>) will become <literal>/</literal> 
@@ -97,7 +97,7 @@ have a very good reason to switch it to
 </para>
 </sect2>
 
-<sect2><title>Local Package Directory</title>
+<sect2 id="setup-localdir"><title>Local Package Directory</title>
 <para>
 The <literal>Local Package Directory</literal> is the cache where 
 <command>setup.exe</command> stores the packages before they are
@@ -111,7 +111,7 @@ or in case you need to reinstall a package.
 </para>
 </sect2>
 
-<sect2><title>Connection Method</title>
+<sect2 id="setup-connection"><title>Connection Method</title>
 <para>
 The <literal>Direct Connection</literal> method of downloading will 
 directly download the packages, while the IE5 method will leverage your 
@@ -124,7 +124,7 @@ authorization for proxy servers.
 </para>
 </sect2>
 
-<sect2><title>Choosing Mirrors</title>
+<sect2 id="setup-mirror"><title>Choosing Mirrors</title>
 <para>
 Since there is no way of knowing from where you will be downloading
 Cygwin, you need to choose at least one mirror site.  Cygwin mirrors 
@@ -137,7 +137,7 @@ mirror) you can add it.
 </para>
 </sect2>
 
-<sect2><title>Choosing Packages</title>
+<sect2 id="setup-packages"><title>Choosing Packages</title>
 <para>
 For each selected mirror site, <command>setup.exe</command> downloads a 
 small text file called <literal>setup.bz2</literal> that contains a list
@@ -201,7 +201,7 @@ stable version.
 </para>
 </sect2>
 
-<sect2><title>Download and Installation Progress</title>
+<sect2 id="setup-progress"><title>Download and Installation Progress</title>
 <para>
 First, <command>setup.exe</command> will download all selected packages
 to the local directory chosen earlier. Before installing, 
@@ -212,7 +212,7 @@ show progress bars for the current task and total remaining disk space.
 </para>
 </sect2>
 
-<sect2><title>Icons</title>
+<sect2 id="setup-icons"><title>Icons</title>
 <para>
 You may choose to install shortcuts on the Desktop and/or Start Menu
 to start a <literal>bash</literal> shell. If you prefer to use a different
@@ -221,7 +221,7 @@ use these shortcuts as a guide to creating your own.
 </para>
 </sect2>
 
-<sect2><title>Post-Install Scripts</title>
+<sect2 id="setup-postinstall"><title>Post-Install Scripts</title>
 <para>
 Last of all, <command>setup.exe</command> will run any post-install
 scripts to finish correctly setting up installed packages. Since each
@@ -236,7 +236,7 @@ Relevant documentation can be found in the <literal>/usr/doc/Cygwin/</literal>
 or <literal>/usr/share/doc/Cygwin/</literal> directory.
 </para>
 </sect2>
-<sect2><title>Troubleshooting</title>
+<sect2 id="setup-troubleshooting"><title>Troubleshooting</title>
 <para>
 Unfortunately, the complex setup process means that odd problems can
 occur. If you're having trouble downloading packages, it may be network
diff --git a/winsup/doc/setup2.sgml b/winsup/doc/setup2.sgml
index bd1e8dec0..5bdfef989 100644
--- a/winsup/doc/setup2.sgml
+++ b/winsup/doc/setup2.sgml
@@ -23,20 +23,21 @@ DOS shell, before launching bash.  </para>
 The <envar>PATH</envar> environment variable is used by Cygwin
 applications as a list of directories to search for executable files
 to run.  This environment variable is converted from Windows format
-(e.g. <filename>C:\WinNT\system32;C:\WinNT</filename>) to UNIX format
-(e.g., <filename>/WinNT/system32:/WinNT</filename>) when a Cygwin
-process first starts.
+(e.g. <filename>C:\Windows\system32;C:\Windows</filename>) to UNIX format
+(e.g., <filename>/cygdrive/c/Windows/system32:/cygdrive/c/Windows</filename>)
+when a Cygwin process first starts.
 Set it so that it contains at least the <filename>x:\cygwin\bin</filename>
 directory where "<filename>x:\cygwin</filename> is the "root" of your
 cygwin installation if you wish to use cygwin tools outside of bash.
+This is usually done by the batch file you're starting your shell with.
 </para>
 
 <para> 
 The <envar>HOME</envar> environment variable is used by many programs to
 determine the location of your home directory and we recommend that it be
 defined.  This environment variable is also converted from Windows format
-when a Cygwin process first starts.  Set it to point to your home directory
-before launching bash. 
+when a Cygwin process first starts.  It's usually set in the shell
+profile scripts in the /etc directory.
 </para>
 
 <para>
@@ -79,8 +80,8 @@ when using <command>regtool</command> since damaging your system registry can
 result in an unusable system.  This example sets memory limit to 1024 MB:
 
 <screen>
-regtool -i set /HKLM/Software/Cygnus\ Solutions/Cygwin/heap_chunk_in_mb 1024
-regtool -v list /HKLM/Software/Cygnus\ Solutions/Cygwin
+regtool -i set /HKLM/Software/Cygwin/heap_chunk_in_mb 1024
+regtool -v list /HKLM/Software/Cygwin
 </screen>
 </para>
 
@@ -121,6 +122,7 @@ gcc max_memory.c -o max_memory.exe
 
 Run the program and it will output the maximum amount of allocatable memory.
 </para>
+
 </sect1>
 
 <sect1 id="setup-files"><title>Customizing bash</title>
@@ -128,19 +130,19 @@ Run the program and it will output the maximum amount of allocatable memory.
 <para>
 To set bash up so that cut and paste work properly, click on the
 "Properties" button of the window, then on the "Misc" tab.  Make sure
-that "Quick Edit" is checked and "Fast Pasting" isn't.  These settings
-will be remembered next time you run bash from that
-shortcut. Similarly you can set the working directory inside the
-"Program" tab. The entry "%HOME%" is valid.
+that "QuickEdit mode" and "Insert mode" are checked.  These settings
+will be remembered next time you run bash from that shortcut. Similarly
+you can set the working directory inside the "Program" tab. The entry
+"%HOME%" is valid, but requires that you set <envar>HOME</envar> in
+the Windows environment.
 </para>
 
 <para>
 Your home directory should contain three initialization files
 that control the behavior of bash.  They are
 <filename>.profile</filename>, <filename>.bashrc</filename> and
-<filename>.inputrc</filename>.  These initialization files will only
-be read if <envar>HOME</envar> is defined before starting bash.
-</para>
+<filename>.inputrc</filename>.  The Cygwin base installation creates
+stub files when you start bash for the first time.</para>
 
 <para>
 <filename>.profile</filename> (other names are also valid, see the bash man
diff --git a/winsup/doc/textbinary.sgml b/winsup/doc/textbinary.sgml
index 1e74c5861..674c39ef2 100644
--- a/winsup/doc/textbinary.sgml
+++ b/winsup/doc/textbinary.sgml
@@ -1,6 +1,6 @@
 <sect1 id="using-textbinary"><title>Text and Binary modes</title>
 
-<sect2> <title>The Issue</title>
+<sect2 id="textbin-issue"> <title>The Issue</title>
 
 <para>On a UNIX system, when an application reads from a file it gets
 exactly what's in the file on disk and the converse is true for writing.
@@ -28,7 +28,7 @@ other programs (such as <command>cat</command>, <command>cmp</command>,
 
 </sect2>
 
-<sect2><title>The default Cygwin behavior</title>
+<sect2 id="textbin-default"><title>The default Cygwin behavior</title>
 
 <para>The Cygwin system gives us some flexibility in deciding how files 
 are to be opened when the mode is not specified explicitly. 
@@ -49,22 +49,8 @@ backslash or a colon), the default is binary.
 <listitem>
 <para>Pipes and non-file devices are opened in binary mode,
 except if the <envar>CYGWIN</envar> environment variable contains
-<literal>nobinmode</literal>.</para>
-<warning><title>Warning!</title><para>In b20.1 of 12/98, a file will be opened
-in binary mode if any of the following conditions hold:</para> 
-<orderedlist numeration="arabic" spacing="compact">
-<listitem><para>binary mode is specified in the open call</para>
-</listitem>
-<listitem><para>the filename is a MS-DOS filename</para>
-</listitem>
-<listitem><para>the file resides on a binary mounted partition</para>
-</listitem>
-<listitem><para><envar>CYGWIN</envar> contains <literal>binmode</literal></para>
-</listitem>
-<listitem><para>the file is not a disk file</para>
-</listitem>
-</orderedlist>
-</warning>
+<literal>nobinmode</literal>.  Sockets are always opened in binary
+mode.</para>
 </listitem>
 
 <listitem>
@@ -79,7 +65,7 @@ and <command> program &lt; filename </command> are not equivalent when
 </orderedlist>
 </sect2>
 
-<sect2><title>Example</title>
+<sect2 id="textbin-example"><title>Example</title>
 <para>To illustrate the various rules, we provide scripts to delete CRs
 from files by using the <command>tr</command> program, which can only write
 to standard output. 
@@ -115,7 +101,7 @@ In the second case we rely on the DOS shell to redirect in binary mode.
 </para>
 </sect2>
 
-<sect2><title>Binary or text?</title>
+<sect2 id="textbin-question"><title>Binary or text?</title>
 
 <para>UNIX programs that have been written for maximum portability
 will know the difference between text and binary files and act
@@ -150,7 +136,7 @@ in binary mode.</para>
 
 </sect2>
 
-<sect2><title>Programming</title>
+<sect2 id="textbin-devel"><title>Programming</title>
 
 <para>In the <function>open()</function> function call, binary mode can be
 specified with the flag <literal>O_BINARY</literal> and text mode with