From a016fed8bae15b01b279288639215e5fc225678a Mon Sep 17 00:00:00 2001 From: Corinna Vinschen Date: Fri, 13 Aug 2010 11:52:13 +0000 Subject: [PATCH] * 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. --- winsup/doc/ChangeLog | 14 ++++++++++++++ winsup/doc/faq-programming.xml | 14 ++++++++++---- winsup/doc/new-features.sgml | 7 +++++++ winsup/doc/overview2.sgml | 11 +++++++---- winsup/doc/pathnames.sgml | 35 +++++++++++++++++++++++++++++++++- winsup/doc/setup2.sgml | 30 +++++++++++++++++++++++++++++ 6 files changed, 102 insertions(+), 9 deletions(-) diff --git a/winsup/doc/ChangeLog b/winsup/doc/ChangeLog index 2bbe05395..0b1a8c688 100644 --- a/winsup/doc/ChangeLog +++ b/winsup/doc/ChangeLog @@ -1,3 +1,17 @@ +2010-08-13 Corinna Vinschen + + * 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 * new-features.sgml (ov-new1.7.6): Document "bind" option. diff --git a/winsup/doc/faq-programming.xml b/winsup/doc/faq-programming.xml index 3936dbc51..331454735 100644 --- a/winsup/doc/faq-programming.xml +++ b/winsup/doc/faq-programming.xml @@ -172,10 +172,10 @@ gcj --main=Hello Hello.java How do I use Win32 API calls? -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). +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). For example, to use graphics functions (GDI) you must link with gdi32 like this: @@ -194,6 +194,12 @@ including user32, gdi32 and, IIRC, comdlg32. 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. + +There are a few restrictions for calls to the Win32 API. +For details, see the User's Guide section +Restricted Win32 environment, +as well as the User's Guide section +Using the Win32 file API in Cygwin applications. diff --git a/winsup/doc/new-features.sgml b/winsup/doc/new-features.sgml index 049183f54..0a1f9ac04 100644 --- a/winsup/doc/new-features.sgml +++ b/winsup/doc/new-features.sgml @@ -47,6 +47,13 @@ New virtual file /proc/filesystems. clock_gettime(3) and clock_getres(3) accept CLOCK_MONOTONIC. + +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 + for details. + + diff --git a/winsup/doc/overview2.sgml b/winsup/doc/overview2.sgml index b0e3635c7..b89799e45 100644 --- a/winsup/doc/overview2.sgml +++ b/winsup/doc/overview2.sgml @@ -55,9 +55,8 @@ an easy way to port many UNIX packages, with only minimal source code changes. -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 . @@ -111,11 +110,15 @@ appropriate. 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. +Some restrictions apply for calls to the Win32 API. +For details, see , +as well as . + 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. diff --git a/winsup/doc/pathnames.sgml b/winsup/doc/pathnames.sgml index 2d0396271..da8e4c1a2 100644 --- a/winsup/doc/pathnames.sgml +++ b/winsup/doc/pathnames.sgml @@ -11,7 +11,8 @@ paths and file access might fail in surprising ways. UNC pathnames The usage of Win32 paths, though possible, is deprecated, since it circumvents important internal path handling mechanisms. -See for more information. +See and + for more information. POSIX operating systems (such as Linux) do not have the concept @@ -363,6 +364,38 @@ permissions. +Using the Win32 file API in Cygwin applications + +Special care must be taken when your application uses Win32 file API +functions like CreateFile to access files using relative +pathnames. + +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, +CreateFile ("foo", ...); will fail, since the Win32 +notion of the CWD is not the same as the Cygwin notion +of the CWD. + +So, in general, don't use the Win32 file API in Cygwin applications. +If you really need to access files using the Win32 API, +and if you really have to use relative pathnames, +you have two choices. + + + + Either you call SetCurrentDirectory before + calling CreateFile. + + + Or you compile your application as native Win32 (mingw) executable, + rather than as Cygwin executable. + + + + + Additional Path-related Information The cygpath program provides the ability to diff --git a/winsup/doc/setup2.sgml b/winsup/doc/setup2.sgml index 6d00aa8ef..692501aa4 100644 --- a/winsup/doc/setup2.sgml +++ b/winsup/doc/setup2.sgml @@ -1,5 +1,7 @@ Environment Variables +Overview + 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 + + +Restricted Win32 environment + +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. + +If you need the full Win32 environment set up in a Cygwin process, +you have to call + + +#include <sys/cygwin.h> + +cygwin_internal (CW_SYNC_WINENV); + + +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 setenv +or putenv calls are not reflected in the Win32 +environment. In these cases, you have to call the aforementioned +cygwin_internal call again. + + + Changing Cygwin's Maximum Memory