+2010-08-13 Corinna Vinschen <corinna@vinschen.de>
+
+ * faq-programming.xml (faq.programming.win32-api): Remove simplicity.
+ Add note and xrefs to User's Guide chapters explaining restrictions
+ using the Win32 API.
+ * new-features.sgml (ov-new1.7.6): Add note about Win CWD.
+ * overview2.sgml (ov-hi-intro): Add note and xrefs about Win32 API
+ restrictions. Tone down flexibility.
+ * pathnames.sgml (pathnames-intro): Add xref to pathnames-win32-api
+ section.
+ (pathnames-win32-api): New section describing Win32 CWD restriction.
+ * setup2.sgml (setup-env-ov): New sub-section.
+ (setup-env-win32): Ditto, describing Win32 environment restriction.
+
2010-08-11 Corinna Vinschen <corinna@vinschen.de>
* new-features.sgml (ov-new1.7.6): Document "bind" option.
<question><para>How do I use Win32 API calls?</para></question>
<answer>
-<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
-automatically (because the startup and/or built-in code uses it).
+<para>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 automatically (because the startup and/or
+built-in code uses it).
</para>
<para>For example, to use graphics functions (GDI) you must link
with gdi32 like this:
<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>
+
+<note><para>There are a few restrictions for calls to the Win32 API.
+For details, see the User's Guide section
+<ulink url="http://cygwin.com/cygwin-ug-net/setup-env.html#setup-env-win32">Restricted Win32 environment</ulink>,
+as well as the User's Guide section
+<ulink url="http://cygwin.com/cygwin-ug-net/using.html#pathnames-win32-api">Using the Win32 file API in Cygwin applications</ulink>.</para></note>
</answer></qandaentry>
<qandaentry id="faq.programming.win32-no-cygwin">
clock_gettime(3) and clock_getres(3) accept CLOCK_MONOTONIC.
</para></listitem>
+<listitem><para>
+Cygwin handles the current working directory entirely on its own. The Win32
+current working directory is set to an invalid path to be out of the way.
+This affects calls to the Win32 file API (CreateFile, etc.). See
+<xref linkend="pathnames-win32-api"></xref> for details.
+</para></listitem>
+
</itemizedlist>
</sect2>
changes.
</para>
<para>
-Note that there are some workarounds
-that cause Cygwin to behave differently than most UNIX-like operating
-systems; these are described in more detail in
+Note that there are some workarounds that cause Cygwin to behave differently
+than most UNIX-like operating systems; these are described in more detail in
<xref linkend="using-effectively"></xref>.
</para>
<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
+any of the Win32 API calls. This gives the programmer some 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>
+<note><para>Some restrictions apply for calls to the Win32 API.
+For details, see <xref linkend="setup-env-win32"></xref>,
+as well as <xref linkend="pathnames-win32-api"></xref>.</para></note>
+
<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.
<note><para>The usage of Win32 paths, though possible, is deprecated,
since it circumvents important internal path handling mechanisms.
-See <xref linkend="pathnames-win32"></xref> for more information.
+See <xref linkend="pathnames-win32"></xref> and
+<xref linkend="pathnames-win32-api"></xref> for more information.
</para></note>
<para>POSIX operating systems (such as Linux) do not have the concept
</sect2>
+<sect2 id="pathnames-win32-api"><title>Using the Win32 file API in Cygwin applications</title>
+
+<para>Special care must be taken when your application uses Win32 file API
+functions like <function>CreateFile</function> to access files using relative
+pathnames.</para>
+
+<para>When a Cygwin application is started, the Win32 idea of the current
+working directory (CWD) is set to an invalid directory. This works around
+the problem that the Win32 CWD is locked in a way which restricts POSIX
+functionality. However, the side effect is that a call to, say,
+<function>CreateFile ("foo", ...);</function> will fail, since the Win32
+notion of the CWD is <emphasis>not</emphasis> the same as the Cygwin notion
+of the CWD.</para>
+
+<para>So, in general, don't use the Win32 file API in Cygwin applications.
+If you <emphasis>really</emphasis> need to access files using the Win32 API,
+and if you <emphasis>really</emphasis> have to use relative pathnames,
+you have two choices.</para>
+
+<itemizedlist spacing="compact">
+ <listitem>
+ <para>Either you call <function>SetCurrentDirectory</function> before
+ calling <function>CreateFile</function>.</para>
+ </listitem>
+ <listitem>
+ <para>Or you compile your application as native Win32 (mingw) executable,
+ rather than as Cygwin executable.</para>
+ </listitem>
+</itemizedlist>
+
+</sect2>
+
<sect2 id="pathnames-additional"><title>Additional Path-related Information</title>
<para>The <command>cygpath</command> program provides the ability to
<sect1 id="setup-env"><title>Environment Variables</title>
+<sect2 id="setup-env-ov"><title>Overview</title>
+
<para>
You may wish to specify settings of several important environment
variables that affect Cygwin's operation. Some of these settings need
</screen>
</para>
+</sect2>
+
+<sect2 id="setup-env-win32"><title>Restricted Win32 environment</title>
+
+<para>There is a restriction when calling Win32 API functions which
+require a fully set up application environment. Cygwin maintains its own
+environment in POSIX style. The Win32 environment is usually stripped
+to a bare minimum and not at all kept in sync with the Cygwin POSIX
+environment.</para>
+
+<para>If you need the full Win32 environment set up in a Cygwin process,
+you have to call</para>
+
+<screen>
+#include <sys/cygwin.h>
+
+cygwin_internal (CW_SYNC_WINENV);
+</screen>
+
+<para>to synchronize the Win32 environment with the Cygwin environment.
+Note that this only synchronizes the Win32 environment once with the
+Cygwin environment. Later changes using the <function>setenv</function>
+or <function>putenv</function> calls are not reflected in the Win32
+environment. In these cases, you have to call the aforementioned
+<function>cygwin_internal</function> call again.</para>
+
+</sect2>
+
</sect1>
<sect1 id="setup-maxmem"><title>Changing Cygwin's Maximum Memory</title>
OSDN Git Service
