From f43eed1c08a8bfbcf8a83546a8cc3b2c9d6115fe Mon Sep 17 00:00:00 2001 From: Corinna Vinschen Date: Thu, 19 Aug 2010 10:35:25 +0000 Subject: [PATCH] * new-features.sgml (ov-new1.7.7): New section. * pathnames.sgml: Throughout, align style of screen elements. Throughout, make all emphasis elements bold. (pathnames-win32-api): Rewrite section. --- winsup/doc/ChangeLog | 7 ++ winsup/doc/new-features.sgml | 13 +++ winsup/doc/pathnames.sgml | 152 ++++++++++++++++++++++++----------- 3 files changed, 126 insertions(+), 46 deletions(-) diff --git a/winsup/doc/ChangeLog b/winsup/doc/ChangeLog index d8f398ac0..48baf45f5 100644 --- a/winsup/doc/ChangeLog +++ b/winsup/doc/ChangeLog @@ -1,3 +1,10 @@ +2010-08-19 Corinna Vinschen + + * new-features.sgml (ov-new1.7.7): New section. + * pathnames.sgml: Throughout, align style of screen elements. + Throughout, make all emphasis elements bold. + (pathnames-win32-api): Rewrite section. + 2010-08-18 Corinna Vinschen * pathnames.sgml (pathnames-win32-api): Try to use a more clear wording. diff --git a/winsup/doc/new-features.sgml b/winsup/doc/new-features.sgml index 0a1f9ac04..9c23000ef 100644 --- a/winsup/doc/new-features.sgml +++ b/winsup/doc/new-features.sgml @@ -1,5 +1,18 @@ What's new and what changed in Cygwin 1.7 +What's new and what changed from 1.7.6 to 1.7.7 + + + + +Add a new CW_SYNC_WINCWD command to the cygwin_internal +call, to allow to synchronize the Win32 CWD with the Cygwin CWD. + + + + + + What's new and what changed from 1.7.5 to 1.7.6 diff --git a/winsup/doc/pathnames.sgml b/winsup/doc/pathnames.sgml index 03c4ba087..492f9cd17 100644 --- a/winsup/doc/pathnames.sgml +++ b/winsup/doc/pathnames.sgml @@ -174,31 +174,31 @@ mount the root dir with special options (for instance, as text mount). Just a normal mount point: - c:/foo /bar fat32 binary 0 0 + c:/foo /bar fat32 binary 0 0 A mount point for a textmode mount with case sensitivity switched off: - C:/foo /bar/baz ntfs text,posix=0 0 0 + C:/foo /bar/baz ntfs text,posix=0 0 0 A mount point for a Windows directory with spaces in it: - C:/Documents\040and\040Settings /docs ext3 binary 0 0 + C:/Documents\040and\040Settings /docs ext3 binary 0 0 A mount point for a remote directory without ACL support: - //server/share/subdir /srv/subdir smbfs binary,noacl 0 0 + //server/share/subdir /srv/subdir smbfs binary,noacl 0 0 This is just a comment: - # This is just a comment + # This is just a comment Set the cygdrive prefix to /mnt: - none /mnt cygdrive binary 0 0 + none /mnt cygdrive binary 0 0 Remount /var to /usr/var: - /var /usr/var none bind + /var /usr/var none bind Assuming /var points to C:/cygwin/var, /usr/var now also points to C:/cygwin/var. This is equivalent @@ -224,13 +224,13 @@ arguments: Displaying the current set of mount points -bash$ mount -f:/cygwin/bin on /usr/bin type system (binary,auto) -f:/cygwin/lib on /usr/lib type system (binary,auto) -f:/cygwin on / type system (binary,auto) -e:/src on /usr/src type system (binary) -c: on /cygdrive/c type user (binary,posix=0,user,noumount,auto) -e: on /cygdrive/e type user (binary,posix=0,user,noumount,auto) + bash$ mount + f:/cygwin/bin on /usr/bin type system (binary,auto) + f:/cygwin/lib on /usr/lib type system (binary,auto) + f:/cygwin on / type system (binary,auto) + e:/src on /usr/src type system (binary) + c: on /cygdrive/c type user (binary,posix=0,user,noumount,auto) + e: on /cygdrive/e type user (binary,posix=0,user,noumount,auto) @@ -247,7 +247,8 @@ your old system mount points (stored in the HKEY_LOCAL_MACHINE branch of your registry) are read by a script and the /etc/fstab file is generated from these entries. Note that entries for /, /usr/bin, and -/usr/lib are never generated. +/usr/lib are never +generated. @@ -336,22 +337,22 @@ bypass the information given in the Cygwin mount table. All paths starting with a drive specifier - - C:\foo - C:/foo - + + C:\foo + C:/foo + All paths containing at least one backslash as path component - - C:/foo/bar\baz/... - + + C:/foo/bar\baz/... + UNC paths using backslashes - - \\server\share\... - + + \\server\share\... + @@ -366,33 +367,92 @@ 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. +Special care must be taken if your application uses Win32 file API +functions like CreateFile to access files using +relative pathnames, or if your application uses functions like +CreateProcess or ShellExecute +to start other applications. 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, for instance, -CreateFile ("foo", ...); will fail, since the Win32 -notion of the CWD is not the same as the Cygwin notion -of the CWD. +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 certain POSIX functionality. However, the side +effect is that a call to, for instance, CreateFile ("foo", +...); will fail, since the Win32 notion of the CWD is +not the same as the Cygwin notion of the CWD, and worse, it's a +directory entirely unsuitable for normal file operations. 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. +If you really need to access files using +the Win32 API, or if you really have to use +CreateProcess to start applications, rather than +the POSIX exec(3) familiy of functions, you have to +make sure that the Win32 CWD is set to some valid directory. To +accomplish that, you can choose from several methods. - Either you call SetCurrentDirectory before - calling the Win32 function which requires a valid Win32 CWD - (CreateFile, CreateProcess, - etc). + The easiest method is to call + + + #include <sys/cygwin.h> + + cygwin_internal (CW_SYNC_WINCWD); + + + prior to calling the Win32 functions which require a valid Win32 CWD. + This function synchronizes the Win32 CWD with the Cygwin CWD. + + Note that the cygwin_internal (CW_SYNC_WINCWD) + call may fail. In that case, it returns with a non-zero value and + errno is set appropriately: + + + + + ENOTDIR + The Cygwin CWD is a virtual path, like /proc, or //, which does not + exist as valid directory in the Win32 namespace. + + + EACCES + The Cygwin CWD is a directory with restrictive permissions, + which make it unusable as Win32 directory. + + + ENAMETOOLONG + The Cygwin CWD is too long to be used as Win32 CWD. + The Win32 CWD is restricted to 258 characters. + + + + You should make sure that you test the return value of + cygwin_internal (CW_SYNC_WINCWD), otherwise + your application will potentially not work correctly. If the call + failed, you can use the Win32 call SetCurrentDirectory + to move to some well-known directory. + + After you've synchronized the Win32 CWD with the Cygwin CWD, + be aware that the directory is locked, until the process exited, or + until the process set the Win32 CWD to some other directory. During that + period it will not be possible to rename or remove the directory from + other Cygwin applications. - Or you compile your application as native Win32 (mingw) executable, - rather than as Cygwin executable. + If you know where to go to, you can also just call the Win32 function + SetCurrentDirectory immediately. + + + If you need a valid Win32 CWD only for a child application started + via CreateProcess and friends, you don't have to + set your own Win32 CWD. In that case, just utilize the lpCurrentDirectory + parameter. See the description of the CreateProcess + function in the MSDN manual pages. + + + Last, but not least, if you don't need any POSIX function from + Cygwin in your specific applciation, consider to compile your application + as native Win32 (mingw) executable, rather than as Cygwin executable. @@ -557,9 +617,9 @@ Cygwin replaces the non-convertible character with a special character sequence. The sequence starts with an ASCII CAN character (hex code 0x18, equivalent Control-X), followed by the UTF-8 representation of the character. The result is a filename containing some ugly looking -characters. While it doesn't look nice, it -is nice, because Cygwin knows how to convert this -filename back to UTF-16. The filename will be converted using your +characters. While it doesn't look nice, it +is nice, because Cygwin knows how to convert +this filename back to UTF-16. The filename will be converted using your usual character set. However, when Cygwin recognizes an ASCII CAN character, it skips over the ASCII CAN and handles the following bytes as a UTF-8 character. Thus, the filename is symmetrically converted back to