diff options
| -rw-r--r-- | winsup/doc/ChangeLog | 15 | ||||
| -rw-r--r-- | winsup/doc/cygwinenv.xml | 37 | ||||
| -rw-r--r-- | winsup/doc/highlights.xml | 27 | ||||
| -rw-r--r-- | winsup/doc/new-features.xml | 3 | ||||
| -rw-r--r-- | winsup/doc/pathnames.xml | 75 |
5 files changed, 112 insertions, 45 deletions
diff --git a/winsup/doc/ChangeLog b/winsup/doc/ChangeLog index f22391f3f..e930a0d01 100644 --- a/winsup/doc/ChangeLog +++ b/winsup/doc/ChangeLog @@ -1,12 +1,23 @@ +2013-05-23 Corinna Vinschen <corinna@vinschen.de> + + * cygwinenv.xml (cygwinenv-implemented-options): Explain new + winsymliks:nativestrict option. Strip out description of symlink types + and refer to new pathnames-symlinks section. + * highlights.xml (ov-hi-files): Rip out most of symlink description and + refer to new pathnames-symlinks section instead. + * new-features.xml (ov-new1.7.19): Add CYGWIN=winsymlinks:nativestrict. + * pathnames.xml (pathnames-symlinks): New section describing symbolic + link handling. + 2013-05-21 Corinna Vinschen <corinna@vinschen.de> - * new-features.sgml (ov-new1.7.19): Add arc4random, + * new-features.xml (ov-new1.7.19): Add arc4random, arc4random_addrandom, arc4random_buf, arc4random_stir and arc4random_uniform. 2013-05-21 Corinna Vinschen <corinna@vinschen.de> - * new-features.sgml (ov-new1.7.19): Add __b64_ntop and __b64_pton. + * new-features.xml (ov-new1.7.19): Add __b64_ntop and __b64_pton. 2013-05-13 Warren Young <warren@etr-usa.com> diff --git a/winsup/doc/cygwinenv.xml b/winsup/doc/cygwinenv.xml index 0ba5def35..a6d0eaac9 100644 --- a/winsup/doc/cygwinenv.xml +++ b/winsup/doc/cygwinenv.xml @@ -82,26 +82,27 @@ time and when handles are inherited. Defaults to set.</para> </listitem> <listitem> -<para><envar>winsymlinks:{lnk,native}</envar> - if set to just +<para><envar>winsymlinks:{lnk,native,nativestrict}</envar> - if set to just <literal>winsymlinks</literal> or <literal>winsymlinks:lnk</literal>, Cygwin creates symlinks as Windows shortcuts with a special header and -the R/O attribute set. If set to <literal>winsymlinks:native</literal>, -Cygwin creates symlinks as native Windows symlinks as supported by NTFS -since Windows Vista/2008. - -If not set, Cygwin creates symlinks as plain files with a magic number, -a path and the DOS SYSTEM attribute set by default, unless this is not -supported by the underlying filesystem. For instance, on MVFS symlinks -are always created as Windows shortcuts, because it doesn't support the -DOS SYSTEM attribute, on AFS always as native symlink because it doesn't -support DOS attributes. On NFS, symlinks are always created as native -symlinks of the underlying filesystem. -</para> - -<para>Please note that symlinks created under Cygwin 1.7 or later are -not readable by older Cygwin releases because the new symlinks use UTF-16 -to encode the target filename, while the old symlinks used the current -ANSI or OEM charset.</para> +the R/O attribute set.</para> + +<para>If set to <literal>winsymlinks:native</literal> or +<literal>winsymlinks:nativestrict</literal>, Cygwin creates symlinks as +native Windows symlinks on filesystems and OS versions supporting them. +If the OS is known not to support native symlinks (Windows XP, Windows +Server 2003), a warning message is produced once per session.</para> + +<para>The difference between <literal>winsymlinks:native</literal> and +<literal>winsymlinks:nativestrict</literal> is this: If the filesystem +supports native symlinks and Cygwin fails to create a native symlink for +some reason, it will fall back to creating Cygwin default symlinks +with <literal>winsymlinks:native</literal>, while with +<literal>winsymlinks:nativestrict</literal> the <literal>symlink(2)</literal> +system call will immediately fail.</para> + +<para>For more information on symbolic links, see +<xref linkend="pathnames-symlinks"></xref>.</para> </listitem> </itemizedlist> diff --git a/winsup/doc/highlights.xml b/winsup/doc/highlights.xml index 6b0a736ee..694a6b3de 100644 --- a/winsup/doc/highlights.xml +++ b/winsup/doc/highlights.xml @@ -113,30 +113,9 @@ supporting that. Since Windows XP, the OS only supports case sensitivity when a specific registry value is changed. Therefore, case sensitivity is not usually the default.</para> -<para>Symbolic links are not present and supported on Windows up to and -including Windows Server 2003 R2. Native symlinks are available starting -with Windows Vista. Due to their strange implementation, however, -they are not useful in a POSIX emulation layer. Cygwin recognizes -native symlinks, but does not create them.</para> - -<para>Symbolic links are potentially created in two different ways. -The file style symlinks are files containing a magic cookie followed by -the path to which the link points. They are marked with the System DOS -attribute so that only files with that attribute have to be read to -determine whether or not the file is a symbolic link. The shortcut style -symlinks are Windows shortcut files with a special header and the -Readonly DOS attribute set. The advantage of file symlinks is speed, -the advantage of shortcut symlinks is the fact that they can be utilized -by non-Cygwin Win32 tools as well.</para> - -<para>Starting with Cygwin 1.7, symbolic links are using UTF-16 to encode -the filename of the target file, to better support internationalization. -Symlinks created by older Cygwin releases can be read just fine. However, -you could run into problems with them if you're now using another character -set than the one you used when creating these symlinks -(see <xref linkend="setup-locale-problems"></xref>. Please note that this -new UTF-16 style of symlinks is not compatible with older Cygwin release, -which can't read the target filename correctly.</para> +<para>Cygwin supports creating and reading symbolic links, even on Windows +filesystems and OS versions which don't support them. +See <xref linkend="pathnames-symlinks"></xref> for details.</para> <para>Hard links are fully supported on NTFS and NFS file systems. On FAT and other file systems which don't support hardlinks, the call returns with diff --git a/winsup/doc/new-features.xml b/winsup/doc/new-features.xml index b867fef68..db8efc7de 100644 --- a/winsup/doc/new-features.xml +++ b/winsup/doc/new-features.xml @@ -18,7 +18,8 @@ Add support for building a 64 bit version of Cygwin on x86_64 natively. <listitem><para> Add support for creating native NTFS symlinks starting with Windows Vista -by setting the CYGWIN=winsymlinks:native option. +by setting the CYGWIN=winsymlinks:native or CYGWIN=winsymlinks:nativestrict +option. </para></listitem> <listitem><para> diff --git a/winsup/doc/pathnames.xml b/winsup/doc/pathnames.xml index 3a85f00ff..3647253e2 100644 --- a/winsup/doc/pathnames.xml +++ b/winsup/doc/pathnames.xml @@ -355,6 +355,81 @@ the cygdrive prefix, use a distinct path prefix:</para> </sect2> +<sect2 id="pathnames-symlinks"><title>Symbolic links</title> + +<para>Symbolic links are not present and supported on Windows until Windows +Vista/Server 2008, and then only on some filesystems. Since POSIX applications +are rightfully expecting to use symlinks and the +<literal>symlink(2)</literal> system call, Cygwin had to find a +workaround for this Windows flaw.</para> + +<para>Cygwin creates symbolic links potentially in multiple different +ways:</para> + +<itemizedlist mark="bullet"> + +<listitem> +<para>The default symlinks are plain files containing a magic cookie +followed by the path to which the link points. They are marked with the +DOS SYSTEM attribute so that only files with that attribute have to be +read to determine whether or not the file is a symbolic link.</para> + +<note><para>Starting with Cygwin 1.7, symbolic links are using UTF-16 to encode +the filename of the target file, to better support internationalization. +Symlinks created by older Cygwin releases can be read just fine. However, +you could run into problems with them if you're now using another character +set than the one you used when creating these symlinks +(see <xref linkend="setup-locale-problems"></xref>). Please note that this +new UTF-16 style of symlinks is not compatible with older Cygwin release, +which can't read the target filename correctly.</para></note> +</listitem> + +<listitem> +<para>The shortcut style symlinks are Windows <literal>.lnk</literal> +shortcut files with a special header and the DOS READONLY attribute set. +This symlink type is created if the environment variable +<literal>CYGWIN</literal> (see <xref linkend="using-cygwinenv"></xref>) +is set to contain the string <literal>winsymlinks</literal> or +<literal>winsymlinks:lnk</literal>. On the MVFS filesystem, which does +not support the DOS SYSTEM attribute, this is the one and only supported +symlink type, independently from the <literal>winsymlinks</literal> +setting.</para> +</listitem> + +<listitem> +<para>Native Windows symlinks are only created on Windows Vista/2008 and later, +and only on filesystems supporting reparse points. Due to to their weird +restrictions and behaviour, they are only created if the user +explicitely requests creating them. This is done by setting the +environment variable <literal>CYGWIN</literal> to contain the string +<literal>winsymlinks:native</literal> or +<literal>winsymlinks:nativestrict</literal>. For the difference between +these two settings, see <xref linkend="using-cygwinenv"></xref>. +On AFS, native symlinks are the only supported type of symlink due to +AFS lacking support for DOS attributes. This is independent from the +<literal>winsymlinks</literal> setting.</para> +</listitem> + +<listitem> +<para>On the NFS filesystem, Cygwin always creates real NFS symlinks.</para> +</listitem> + +</itemizedlist> + +<para>All of the above four symlink types are recognized and used as symlinks +under all circumstances. However, if the default plain file symlink type +is lacking its DOS SYSTEM bit, or if the shortcut file is lacking the DOS +READONLY attribute, they are not recognized as symlink.</para> + +<para>Apart from these four types, there's also a fifth type, which is +recognized as symlink but never generated by Cygwin, directory +junctions. This is an older reparse point type, supported by Windows +since Windows 2000. Filesystem junctions on the other hand are not +handled as symlinks, since otherwise they would not be recognized as +filesystem borders by commands like <command>find -xdev</command>.</para> + +</sect2> + <sect2 id="pathnames-win32"><title>Using native Win32 paths</title> <para>Using native Win32 paths in Cygwin, while possible, is generally |