* 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.
This commit is contained in:
Corinna Vinschen
parent
260b80740e
commit
a016fed8ba
|
|
@ -1,3 +1,17 @@
|
|||
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.
|
||||
|
|
|
|||
|
|
@ -172,10 +172,10 @@ gcj --main=Hello Hello.java
|
|||
<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:
|
||||
|
|
@ -194,6 +194,12 @@ including user32, gdi32 and, IIRC, comdlg32.
|
|||
<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">
|
||||
|
|
|
|||
|
|
@ -47,6 +47,13 @@ New virtual file /proc/filesystems.
|
|||
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>
|
||||
|
|
|
|||
|
|
@ -55,9 +55,8 @@ an easy way to port many UNIX packages, with only minimal source code
|
|||
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>
|
||||
|
|
@ -111,11 +110,15 @@ 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
|
||||
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.
|
||||
|
|
|
|||
|
|
@ -11,7 +11,8 @@ paths and file access might fail in surprising ways. UNC pathnames
|
|||
|
||||
<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
|
||||
|
|
@ -363,6 +364,38 @@ permissions.</para>
|
|||
|
||||
</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
|
||||
|
|
|
|||
|
|
@ -1,5 +1,7 @@
|
|||
<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
|
||||
|
|
@ -99,6 +101,34 @@ export TEMP=/tmp
|
|||
</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>
|
||||
|
|
|
|||
Loading…
Reference in New Issue