* faq-programming.xml: Revamp (mostely) for Cygwin 1.7.

	* faq-what.xml: Ditto.

1 files changed, 50 insertions, 89 deletions

diff --git a/winsup/doc/faq-programming.xml b/winsup/doc/faq-programming.xml
index 9e6fee6de..948c59d52 100644
--- a/winsup/doc/faq-programming.xml
+++ b/winsup/doc/faq-programming.xml
@@ -62,11 +62,10 @@ would be difficult.
 <question><para>Where is Objective C?</para></question>
 <answer>
 
-<para>Objective C is not distributed with the Cygwin version of gcc, and there
-are no plans to do so.  The gcc package maintainer had difficulty
-building it, and once built there were problems using it.  It appears
-that there is only minimal support for the Objective C front-end in the
-main GCC distribution, anyway.
+<para>Objective C hasn't been distributed with the Cygwin version of gcc
+for a long time.  For several reason Cygwin was stuck with gcc version 3.4.4.
+Fortunately the latest gcc maintainer is quite busy to create a working
+gcc 4.x release which also comes with an Objective C package.
 </para>
 </answer></qandaentry>
 
@@ -87,22 +86,27 @@ to enable cygexec for all executables in that folder; you will also need
 to exclude non-cygwin executables with the -x switch. Enabling cygexec
 causes cygwin executables to talk directly to one another, which increases
 the command-line limit. To enable cygexec for <literal>/bin</literal> and 
-<literal>/usr/bin</literal>, you can use these commands in a batch file:
+<literal>/usr/bin</literal>, you can add or change these entries in /etc/fstab:
 </para>
 <screen>
-mount -X -b -f c:\cygwin\bin /bin
-mount -X -b -f c:\cygwin\bin /usr/bin
-mount -x -b -f c:\cygwin\bin\tclsh84.exe /usr/bin/tclsh84.exe
-mount -x -b -f c:\cygwin\bin\tclsh84.exe /bin/tclsh84.exe
-mount -x -b -f c:\cygwin\bin\wish84.exe /usr/bin/wish84.exe
-mount -x -b -f c:\cygwin\bin\wish84.exe /bin/wish84.exe
+C:/cygwin/bin /bin ntfs binary,cygexec 0 0
+C:/cygwin/bin /usr/bin ntfs binary,cygexec 0 0
 </screen>
 
-<para>Note that if you have Tcl/Tk installed, you must specifically exclude 
-<literal>tclsh84</literal> and <literal>wish84</literal>, which are linked 
-to the Cygwin DLL but are not actually Cygwin programs. If you have added 
-other non-Cygwin programs to a path you want to mount cygexec, you can find
-them with a script like this:
+<para>Note that if you have Tcl/Tk installed, you must additionally
+exclude <literal>tclsh84</literal> and <literal>wish84</literal>, which
+are linked to the Cygwin DLL but are not actually Cygwin programs:
+</para>
+
+<screen>
+C:/cygwin/bin/tclsh84.exe /bin/tclsh84.exe ntfs binary,notexec 0 0
+C:/cygwin/bin/tclsh84.exe /usr/bin/tclsh84.exe ntfs binary,notexec 0 0
+C:/cygwin/bin/wish84.exe /bin/wish84.exe ntfs binary,notexec 0 0
+C:/cygwin/bin/wish84.exe /usr/bin/wish84.exe ntfs binary,notexec 0 0
+</screen>
+
+<para>If you have added other non-Cygwin programs to a path you want to mount
+cygexec, you can find them with a script like this:
 </para>
 <screen>
 #!/bin/sh
@@ -112,7 +116,7 @@ done
 </screen>
 
 <para>
-See <ulink url="http://www.cygwin.com/cygwin-ug-net/using-utils.html#mount" /> 
+See <ulink url="http://cygwin.com/cygwin-ug-net/using.html#mount-table" /> 
 for more information on using mount.
 </para>
 
@@ -125,7 +129,7 @@ error?</para></question>
 
 <para>
 Try running cygserver.  Read 
-<ulink url="http://www.cygwin.com/cygwin-ug-net/using-cygserver.html" />. If you're
+<ulink url="http://cygwin.com/cygwin-ug-net/using-cygserver.html" />. If you're
 trying to use PostgreSQL, also read 
 <literal>/usr/share/doc/Cygwin/postgresql-*.README</literal>.
 </para>
@@ -168,8 +172,6 @@ gcj --main=Hello Hello.java
 <question><para>How do I use Win32 API calls?</para></question>
 <answer>
 
-<para><emphasis role='bold'>(Please note: This section has not yet been updated for the latest net release.)</emphasis>
-</para>
 <para>It's pretty simple actually.  Cygwin tools require that you explicitly
 link the import libraries for whatever Win32 API functions that you
 are going to use, with the exception of kernel32, which is linked
@@ -184,38 +186,13 @@ with gdi32 like this:
 </para>
 <para>gcc -o foo.exe foo.c bar.c -lgdi32
 </para>
-<para>The following libraries are available for use in this way:
-</para>
-<para>advapi32  largeint  ole32     scrnsave  vfw32
-cap       lz32      oleaut32  shell32   win32spl
-comctl32  mapi32    oledlg    snmp      winmm
-comdlg32  mfcuia32  olepro32  svrapi    winserve
-ctl3d32   mgmtapi   opengl32  tapi32    winspool
-dlcapi    mpr       penwin32  th32      winstrm
-gdi32     msacm32   pkpd32    thunk32   wow32
-glaux     nddeapi   rasapi32  url       wsock32
-glu32     netapi32  rpcdce4   user32    wst
-icmp      odbc32    rpcndr    uuid
-imm32     odbccp32  rpcns4    vdmdbg
-kernel32  oldnames  rpcrt4    version
-</para>
 <para>The regular setup allows you to use the option -mwindows on the
 command line to include a set of the basic libraries (and also
 make your program a GUI program instead of a console program),
 including user32, gdi32 and, IIRC, comdlg32.
 </para>
-<para>Note that you should never include -lkernel32 on your link line
-unless you are invoking ld directly.  Do not include the same import
-library twice on your link line.  Finally, it is a good idea to
-put import libraries last on your link line, or at least after
-all the object files and static libraries that reference them.
-</para>
-<para>The first two are related to problems the linker has (as of b18 at least)
-when import libraries are referenced twice.  Tables get messed up and
-programs crash randomly.  The last point has to do with the fact that
-gcc processes the files listed on the command line in sequence and
-will only resolve references to libraries if they are given after
-the file that makes the reference.
+<para>It is a good idea to put import libraries last on your link line,
+or at least after all the object files and static libraries that reference them.
 </para>
 </answer></qandaentry>
 
@@ -223,6 +200,8 @@ the file that makes the reference.
 <question><para>How do I compile a Win32 executable that doesn't use Cygwin?</para></question>
 <answer>
 
+<para><emphasis role='bold'>(Please note: This section has not yet been updated for the latest net release.)</emphasis>
+</para>
 <para>The -mno-cygwin flag to gcc makes gcc link against standard Microsoft
 DLLs instead of Cygwin.  This is desirable for native Windows programs
 that don't need a UNIX emulation layer.
@@ -297,8 +276,8 @@ have our own Win32 headers which are pretty complete.
 <answer>
 
 <para>Before you begin, note that Cygwin is licensed under the GNU GPL (as
-indeed are all other Cygwin-based libraries).  That means that if your
-code links against the cygwin dll (and if your program is calling
+indeed are many other Cygwin-based libraries).  That means that if your
+code links against the Cygwin dll (and if your program is calling
 functions from Cygwin, it must, as a matter of fact, be linked against
 it), you must apply the GPL to your source as well.  Of course, this
 only matters if you plan to distribute your program in binary form.  For
@@ -531,18 +510,7 @@ gcc as:
 <para><literal>cygcheck</literal> will do this much more concisely, and operates
 recursively, provided the command is in your path.
 </para>
-<para>Note there is currently a bug in cygcheck in that it will not report
-on a program in a Windows system dir (e.g., C:\Windows or C:\WINNT) even
-if it's in your path.  To work around this, supply the full Win32 path
-to the executable, including the .exe extension:
-</para>
-<screen>
-cygcheck c:\\winnt\\system32\\cmd.exe
-</screen>
 
-<para>(Note the windows path separator must be escaped if this is typed in
-bash.)
-</para>
 </answer></qandaentry>
 
 <qandaentry id="faq.programming.dll-building">
@@ -569,7 +537,7 @@ question.
 <question><para>How can I build a relocatable dll?</para></question>
 <answer>
 
-<para><emphasis role='bold'>(Please note: This section has not yet been updated for the latest net release.  However, there was a discussion on the cygwin mailing list recently that addresses this issue.  Read <ulink url="http://cygwin.com/ml/cygwin/2000-06/msg00688.html">http://cygwin.com/ml/cygwin/2000-06/msg00688.html</ulink> and related messages.)</emphasis>
+<para><emphasis role='bold'>(Please note: This section has not yet been updated for the latest net release.  However, there was a discussion on the cygwin mailing list once that addresses this issue.  Read <ulink url="http://cygwin.com/ml/cygwin/2000-06/msg00688.html">http://cygwin.com/ml/cygwin/2000-06/msg00688.html</ulink> and related messages.)</emphasis>
 </para>
 <para>You must execute the following sequence of five commands, in this
 order:
@@ -689,7 +657,7 @@ info would not be compatible with gdb).
 <para>Yes.  You can use the <literal>strace.exe</literal> utility to run other cygwin
 programs with various debug and trace messages enabled.  For information
 on using <literal>strace</literal>, see the Cygwin User's Guide or the file
-<literal>winsup/utils/utils.sgml</literal>.
+<literal>winsup/utils/utils.sgml</literal> in the Cygwin sources.
 </para>
 </answer></qandaentry>
 
@@ -722,7 +690,7 @@ This is right <literal>gcc hello.cc -lstdc++</literal>.
 <answer>
 
 <para><literal>struct stat64</literal> is not used in Cygwin, just
-use <literal>struct stat</literal>.</para>
+use <literal>struct stat</literal>.  It's 64 bit aware.</para>
 </answer></qandaentry>
 
 <qandaentry id="faq.programming.undeclared-functions">
@@ -746,9 +714,9 @@ the UNICODE stuff for it isn't filled in.
 <question><para>Where is malloc.h?</para></question>
 <answer>
 
-<para><emphasis role='bold'>(Please note: This section has not yet been updated for the latest net release.)</emphasis>
-</para>
-<para>Include stdlib.h instead of malloc.h.
+<para>It exists, but you should rather include stdlib.h instead of malloc.h.
+stdlib.h is POSIX standard for defining malloc and friends, malloc.h is
+definitely non-standard.
 </para>
 </answer></qandaentry>
 
@@ -809,7 +777,7 @@ data types, line numbers, local variables etc.
 <para>CPU reference manuals for Intel's current chips are available in
 downloadable PDF form on Intel's web site:
 </para>
-<para><ulink url="http://developer.intel.com/design/pro/manuals/">http://developer.intel.com/design/pro/manuals/</ulink>
+<para><ulink url="http://developer.intel.com/">http://developer.intel.com/</ulink>
 </para>
 </answer></qandaentry>
 
@@ -818,41 +786,34 @@ downloadable PDF form on Intel's web site:
 <answer>
 
 <para>If your scripts are in the current directory, you must have <literal>.</literal>
-(dot) in your $PATH.  (It is not normally there by default.)  Otherwise,
-you would need to add /bin/sh in front of each and every shell script
-invoked in your Makefiles.
+(dot) in your $PATH.  (It is not normally there by default.)  Better yet,
+add /bin/sh in front of each and every shell script invoked in your Makefiles.
 </para>
 </answer></qandaentry>
 
 <qandaentry id="faq.programming.preprocessor">
-<question><para>What preprocessor do I need to know about?</para></question>
+<question><para>What preprocessor macros do I need to know about?</para></question>
 <answer>
 
-<para>We use _WIN32 to signify access to the Win32 API and __CYGWIN__ for
-access to the Cygwin environment provided by the dll.
+<para>gcc for Cygwin defines __CYGWIN__ when building for a Cygwin
+environment.
 </para>
-<para>We chose _WIN32 because this is what Microsoft defines in VC++ and
-we thought it would be a good idea for compatibility with VC++ code
-to follow their example.  We use _MFC_VER to indicate code that should
-be compiled with VC++.
+<para>Microsoft defines the preprocessor symbol _WIN32 in their Windows
+development environment.
 </para>
-<para>_WIN32 is only defined when you use either the -mno-cygwin or -mwin32
+<para>In gcc for Cygwin, _WIN32 is only defined when you use the -mwin32
 gcc command line options.  This is because Cygwin is supposed to be a
-Unix emulation environment and defining _WIN32 confuses some programs
-which think that they have to make special concessions for a Windows
-environment which Cygwin handles automatically.
+POSIX emulation environment in the first place and defining _WIN32 confuses
+some programs which think that they have to make special concessions for
+a Windows environment which Cygwin handles automatically.
 </para>
-<para>Note that using -mno-cygwin replaces __CYGWIN__ with __MINGW32__ as to
-tell which compiler (or settings) you're running.
-Check this out in detail by running, for example
+<para>Check out the predefined symbols in detail by running, for example
 </para>
 <screen>
        $ gcc  -dM -E -xc /dev/null &gt;gcc.txt
-       $ gcc -mno-cygwin -dM -E -xc /dev/null &gt;gcc-mno-cygwin.txt
        $ gcc -mwin32 -dM -E -xc /dev/null &gt;gcc-mwin32.txt
 </screen>
-<para>Then use the diff and grep utilities to check
-what the difference is.
+<para>Then use the diff and grep utilities to check what the difference is.
 </para>
 </answer></qandaentry>
 
@@ -866,7 +827,7 @@ what the difference is.
 V (and others?).  Typically, you will end up with a GUI on Windows that
 requires some runtime support.  With tcl/tk, you'll want to include the
 necessary library files and the tcl/tk DLLs.  In the case of X11, you'll
-need everyone using your program to have an X11 server installed.
+need everyone using your program to have the X11 server installed.
 </para>
 <para>The second method is to rewrite your GUI using Win32 API calls (or MFC
 with VC++).  If your program is written in a fairly modular fashion, you