drew
/
acadia-newlib
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

* 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.
This commit is contained in:
Corinna Vinschen 2010-08-19 10:35:25 +00:00
parent e652eb9230
commit f43eed1c08
3 changed files with 126 additions and 46 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

7
winsup/doc/ChangeLog
View File

@ -1,3 +1,10 @@
2010-08-19 Corinna Vinschen <corinna@vinschen.de>
* 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 <corinna@vinschen.de>
* pathnames.sgml (pathnames-win32-api): Try to use a more clear wording.

13
winsup/doc/new-features.sgml
View File

@ -1,5 +1,18 @@
<sect1 id="ov-new1.7"><title>What's new and what changed in Cygwin 1.7</title>
<sect2 id="ov-new1.7.7"><title>What's new and what changed from 1.7.6 to 1.7.7</title>
<itemizedlist mark="bullet">
<listitem><para>
Add a new CW_SYNC_WINCWD command to the <function>cygwin_internal</function>
call, to allow to synchronize the Win32 CWD with the Cygwin CWD.
</para></listitem>
</itemizedlist>
</sect2>
<sect2 id="ov-new1.7.6"><title>What's new and what changed from 1.7.5 to 1.7.6</title>
<itemizedlist mark="bullet">

104
winsup/doc/pathnames.sgml
View File

@ -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 <filename>/etc/fstab</filename>
file is generated from these entries. Note that entries for
<filename>/</filename>, <filename>/usr/bin</filename>, and
<filename>/usr/lib</filename> are <emphasis>never</emphasis> generated.
<filename>/usr/lib</filename> are <emphasis role='bold'>never</emphasis>
generated.
</para>
<para>
@ -366,33 +367,92 @@ permissions.</para>
<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>Special care must be taken if your application uses Win32 file API
functions like <function>CreateFile</function> to access files using
relative pathnames, or if your application uses functions like
<function>CreateProcess</function> or <function>ShellExecute</function>
to start other applications.</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, for instance,
<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>
working directory (CWD) is set to an <emphasis role='bold'>invalid</emphasis>
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, <function>CreateFile ("foo",
...);</function> 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.</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>
If you <emphasis role='bold'>really</emphasis> need to access files using
the Win32 API, or if you <emphasis role='bold'>really</emphasis> have to use
<function>CreateProcess</function> to start applications, rather than
the POSIX <function>exec(3)</function> 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.</para>
<itemizedlist spacing="compact">
<listitem>
<para>Either you call <function>SetCurrentDirectory</function> before
calling the Win32 function which requires a valid Win32 CWD
(<function>CreateFile</function>, <function>CreateProcess</function>,
etc).</para>
<para>The easiest method is to call</para>
<screen>
#include &lt;sys/cygwin.h&gt;
cygwin_internal (CW_SYNC_WINCWD);
</screen>
<para>prior to calling the Win32 functions which require a valid Win32 CWD.
This function synchronizes the Win32 CWD with the Cygwin CWD.</para>
<para>Note that the <function>cygwin_internal (CW_SYNC_WINCWD)</function>
call may fail. In that case, it returns with a non-zero value and
errno is set appropriately:</para>
<segmentedlist>
<?dbhtml list-presentation="table"?>
<seglistitem>
<seg><emphasis role='bold'>ENOTDIR</emphasis></seg>
<seg>The Cygwin CWD is a virtual path, like /proc, or //, which does not
exist as valid directory in the Win32 namespace.</seg>
</seglistitem>
<seglistitem>
<seg><emphasis role='bold'>EACCES</emphasis></seg>
<seg>The Cygwin CWD is a directory with restrictive permissions,
which make it unusable as Win32 directory.</seg>
</seglistitem>
<seglistitem>
<seg><emphasis role='bold'>ENAMETOOLONG</emphasis></seg>
<seg>The Cygwin CWD is too long to be used as Win32 CWD.
The Win32 CWD is restricted to 258 characters.</seg>
</seglistitem>
</segmentedlist>
<para>You should make sure that you test the return value of
<function>cygwin_internal (CW_SYNC_WINCWD)</function>, otherwise
your application will potentially not work correctly. If the call
failed, you can use the Win32 call <function>SetCurrentDirectory</function>
to move to some well-known directory.</para>
<note><para>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.</para></note>
</listitem>
<listitem>
<para>Or you compile your application as native Win32 (mingw) executable,
rather than as Cygwin executable.</para>
<para>If you know where to go to, you can also just call the Win32 function
<function>SetCurrentDirectory</function> immediately.</para>
</listitem>
<listitem>
<para>If you need a valid Win32 CWD only for a child application started
via <function>CreateProcess</function> 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 <function>CreateProcess</function>
function in the MSDN manual pages.</para>
</listitem>
<listitem>
<para>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.</para>
</listitem>
</itemizedlist>
@ -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 <emphasis>look</emphasis> nice, it
<emphasis>is</emphasis> 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 <emphasis role='bold'>look</emphasis> nice, it
<emphasis role='bold'>is</emphasis> 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