From 6d383d0fded9d23dfd0cb5e0e21dab45e8863f3d Mon Sep 17 00:00:00 2001 From: Corinna Vinschen Date: Thu, 23 May 2013 14:26:53 +0000 Subject: [PATCH] * 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. --- winsup/doc/ChangeLog | 15 +++++++- winsup/doc/cygwinenv.xml | 33 ++++++++-------- winsup/doc/highlights.xml | 27 ++----------- winsup/doc/new-features.xml | 3 +- winsup/doc/pathnames.xml | 75 +++++++++++++++++++++++++++++++++++++ 5 files changed, 110 insertions(+), 43 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 + + * 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 - * 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 - * 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 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. -winsymlinks:{lnk,native} - if set to just +winsymlinks:{lnk,native,nativestrict} - if set to just winsymlinks or winsymlinks:lnk, Cygwin creates symlinks as Windows shortcuts with a special header and -the R/O attribute set. If set to winsymlinks:native, -Cygwin creates symlinks as native Windows symlinks as supported by NTFS -since Windows Vista/2008. +the R/O attribute set. -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. - +If set to winsymlinks:native or +winsymlinks:nativestrict, 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. -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. +The difference between winsymlinks:native and +winsymlinks:nativestrict 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 winsymlinks:native, while with +winsymlinks:nativestrict the symlink(2) +system call will immediately fail. + +For more information on symbolic links, see +. 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. -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. - -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. - -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 . 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. +Cygwin supports creating and reading symbolic links, even on Windows +filesystems and OS versions which don't support them. +See for details. 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. 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. 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: +Symbolic links + +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 +symlink(2) system call, Cygwin had to find a +workaround for this Windows flaw. + +Cygwin creates symbolic links potentially in multiple different +ways: + + + + +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. + +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 ). 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. + + + +The shortcut style symlinks are Windows .lnk +shortcut files with a special header and the DOS READONLY attribute set. +This symlink type is created if the environment variable +CYGWIN (see ) +is set to contain the string winsymlinks or +winsymlinks:lnk. On the MVFS filesystem, which does +not support the DOS SYSTEM attribute, this is the one and only supported +symlink type, independently from the winsymlinks +setting. + + + +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 CYGWIN to contain the string +winsymlinks:native or +winsymlinks:nativestrict. For the difference between +these two settings, see . +On AFS, native symlinks are the only supported type of symlink due to +AFS lacking support for DOS attributes. This is independent from the +winsymlinks setting. + + + +On the NFS filesystem, Cygwin always creates real NFS symlinks. + + + + +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. + +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 find -xdev. + + + Using native Win32 paths Using native Win32 paths in Cygwin, while possible, is generally