diff options
Diffstat (limited to 'winsup/doc/pathnames.xml')
| -rw-r--r-- | winsup/doc/pathnames.xml | 570 |
1 files changed, 0 insertions, 570 deletions
diff --git a/winsup/doc/pathnames.xml b/winsup/doc/pathnames.xml deleted file mode 100644 index 3647253e2..000000000 --- a/winsup/doc/pathnames.xml +++ /dev/null @@ -1,570 +0,0 @@ -<?xml version="1.0" encoding='UTF-8'?> -<!DOCTYPE sect1 PUBLIC "-//OASIS//DTD DocBook V4.5//EN" - "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd"> - -<sect1 id="using-pathnames"><title>Mapping path names</title> - -<sect2 id="pathnames-intro"><title>Introduction</title> - -<para>Cygwin supports both POSIX- and Win32-style paths. Directory -delimiters may be either forward slashes or backslashes. Paths using -backslashes or starting with a drive letter are always handled as -Win32 paths. POSIX paths must only use forward slashes as delimiter, -otherwise they are treated as Win32 paths and file access might fail -in surprising ways.</para> - -<note><para>The usage of Win32 paths, though possible, is deprecated, -since it circumvents important internal path handling mechanisms. -See <xref linkend="pathnames-win32"></xref> and -<xref linkend="pathnames-win32-api"></xref> for more information. -</para></note> - -<para>POSIX operating systems (such as Linux) do not have the concept -of drive letters. Instead, all absolute paths begin with a -slash (instead of a drive letter such as "c:") and all file systems -appear as subdirectories (for example, you might buy a new disk and -make it be the <filename>/disk2</filename> directory).</para> - -<para>Because many programs written to run on UNIX systems assume -the existence of a single unified POSIX file system structure, Cygwin -maintains a special internal POSIX view of the Win32 file system -that allows these programs to successfully run under Windows. Cygwin -uses this mapping to translate from POSIX to Win32 paths as -necessary.</para> - -</sect2> - -<sect2 id="mount-table"><title>The Cygwin Mount Table</title> - -<para>The <filename>/etc/fstab</filename> file is used to map Win32 -drives and network shares into Cygwin's internal POSIX directory tree. -This is a similar concept to the typical UNIX fstab file. The mount -points stored in <filename>/etc/fstab</filename> are globally set for -all users. Sometimes there's a requirement to have user specific -mount points. The Cygwin DLL supports user specific fstab files. -These are stored in the directory <filename>/etc/fstab.d</filename> -and the name of the file is the Cygwin username of the user, as it's -stored in the <filename>/etc/passwd</filename> file. The structure of the -user specific file is identical to the system-wide -<filename>fstab</filename> file.</para> - -<para>The file fstab contains descriptive information about the various file -systems. fstab is only read by programs, and not written; it is the -duty of the system administrator to properly create and maintain this -file. Each filesystem is described on a separate line; fields on each -line are separated by tabs or spaces. Lines starting with '#' are -comments.</para> - -<para>The first field describes the block special device or -remote filesystem to be mounted. On Cygwin, this is the native Windows -path which the mount point links in. As path separator you MUST use a -slash. Usage of a backslash might lead to unexpected results. UNC -paths (using slashes, not backslashes) are allowed. If the path -contains spaces these can be escaped as <literal>'\040'</literal>.</para> - -<para>The second field describes the mount point for the filesystem. -If the name of the mount point contains spaces these can be -escaped as '\040'.</para> - -<para>The third field describes the type of the filesystem. Cygwin supports -any string here, since the file system type is usually not evaluated. So it -doesn't matter if you write <literal>FAT</literal> into this field even if -the filesystem is NTFS. Cygwin figures out the filesystem type and its -capabilities by itself.</para> - -<para>The only exception is the file system type cygdrive. This type is -used to set the cygdrive prefix. For a description of the cygdrive prefix -see <xref linkend="cygdrive"></xref></para> - -<para>The fourth field describes the mount options associated -with the filesystem. It is formatted as a comma separated list of -options. It contains at least the type of mount (binary or text) plus -any additional options appropriate to the filesystem type. Recognized -options are binary, text, nouser, user, exec, notexec, cygexec, nosuid, -posix=[0|1]. The meaning of the options is as follows.</para> - -<screen> - acl - Cygwin uses the filesystem's access control lists (ACLs) to - implement real POSIX permissions (default). This flag only - affects filesystems supporting ACLs (NTFS, for instance) and - is ignored otherwise. - auto - Ignored. - binary - Files default to binary mode (default). - bind - Allows to remount part of the file hierarchy somewhere else. - In contrast to other entries, the first field in the fstab - line specifies an absolute POSIX path. This path is remounted - to the POSIX path specified as the second path. The conversion - to a Win32 path is done on the fly. Only the root path and - paths preceding the bind entry in the fstab file are used to - convert the POSIX path in the first field to an absolute Win32 - path. Note that symlinks are ignored while performing this path - conversion. - cygexec - Treat all files below mount point as cygwin executables. - dos - Always convert leading spaces and trailing dots and spaces to - characters in the UNICODE private use area. This allows to use - broken filesystems which only allow DOS filenames, even if they - are not recognized as such by Cygwin. - exec - Treat all files below mount point as executable. - ihash - Always fake inode numbers rather than using the ones returned - by the filesystem. This allows to use broken filesystems which - don't return unambiguous inode numbers, even if they are not - recognized as such by Cygwin. - noacl - Cygwin ignores filesystem ACLs and only fakes a subset of - permission bits based on the DOS readonly attribute. This - behaviour is the default on FAT and FAT32. The flag is - ignored on NFS filesystems. - nosuid - No suid files are allowed (currently unimplemented). - notexec - Treat all files below mount point as not executable. - nouser - Mount is a system-wide mount. - override - Force the override of an immutable mount point (currently "/"). - posix=0 - Switch off case sensitivity for paths under this mount point - (default for the cygdrive prefix). - posix=1 - Switch on case sensitivity for paths under this mount point - (default for all other mount points). - sparse - Switch on support for sparse files. This option only makes - sense on NTFS and then only if you really need sparse files. - Cygwin does not try to create sparse files by default for - performance reasons. - text - Files default to CRLF text mode line endings. - user - Mount is a user mount. -</screen> - -<para>While normally the execute permission bits are used to evaluate -executability, this is not possible on filesystems which don't support -permissions at all (like FAT/FAT32), or if ACLs are ignored on filesystems -supporting them (see the aforementioned <literal>acl</literal> mount option). -In these cases, the following heuristic is used to evaluate if a file is -executable: Files ending in certain extensions (.exe, .com, .bat, .btm, -.cmd) are assumed to be executable. Files whose first two characters begin -with '#!' are also considered to be executable. -The <literal>exec</literal> option is used to instruct Cygwin that the -mounted file is "executable". If the <literal>exec</literal> option is used -with a directory then all files in the directory are executable. -This option allows other files to be marked as executable and avoids the -overhead of opening each file to check for a '#!'. The -<literal>cygexec</literal> option is very similar to <literal>exec</literal>, -but also prevents Cygwin from setting up commands and environment variables -for a normal Windows program, adding another small performance gain. The -opposite of these options is the <literal>notexec</literal> option, which -means that no files should be marked as executable under that mount point.</para> -<para>A correct root directory is quite essential to the operation of -Cygwin. A default root directory is evaluated at startup so a -<filename>fstab</filename> entry for the root directory is not necessary. -If it's wrong, nothing will work as expected. Therefore, the root directory -evaluated by Cygwin itself is treated as an immutable mount point and can't -be overridden in /etc/fstab... unless you think you really know what you're -doing. In this case, use the <literal>override</literal> flag in the options -field in the <filename>/etc/fstab</filename> file. Since this is a dangerous -thing to do, do so at your own risk.</para> - -<para><filename>/usr/bin</filename> and <filename>/usr/lib</filename> are -by default also automatic mount points generated by the Cygwin DLL similar -to the way the root directory is evaluated. <filename>/usr/bin</filename> -points to the directory the Cygwin DLL is installed in, -<filename>/usr/lib</filename> is supposed to point to the -<filename>/lib</filename> directory. This choice is safe and usually -shouldn't be changed. An fstab entry for them is not required.</para> - -<para><literal>nouser</literal> mount points are not overridable by a later -call to <command>mount</command>. -Mount points given in <filename>/etc/fstab</filename> are by default -<literal>nouser</literal> mount points, unless you specify the option -<literal>user</literal>. This allows the administrator to set certain -paths so that they are not overridable by users. In contrast, all mount -points in the user specific fstab file are <literal>user</literal> mount -points.</para> - -<para>The fifth and sixth field are ignored. They are -so far only specified to keep a Linux-like fstab file layout.</para> - -<para>Note that you don't have to specify an fstab entry for the root dir, -unless you want to have the root dir pointing to somewhere entirely -different (hopefully you know what you're doing), or if you want to -mount the root dir with special options (for instance, as text mount).</para> - -<para>Example entries:</para> - -<itemizedlist spacing="compact"> -<listitem> - <para>Just a normal mount point:</para> - <screen> c:/foo /bar fat32 binary 0 0</screen> -</listitem> -<listitem> - <para>A mount point for a textmode mount with case sensitivity switched off:</para> - <screen> C:/foo /bar/baz ntfs text,posix=0 0 0</screen> -</listitem> -<listitem> - <para>A mount point for a Windows directory with spaces in it:</para> - <screen> C:/Documents\040and\040Settings /docs ext3 binary 0 0</screen> -</listitem> -<listitem> - <para>A mount point for a remote directory, don't store POSIX permissions in ACLs:</para> - <screen> //server/share/subdir /srv/subdir smbfs binary,noacl 0 0</screen> -</listitem> -<listitem> - <para>This is just a comment:</para> - <screen> # This is just a comment</screen> -</listitem> -<listitem> - <para>Set the cygdrive prefix to /mnt:</para> - <screen> none /mnt cygdrive binary 0 0</screen> -</listitem> -<listitem> - <para>Remount /var to /usr/var:</para> - <screen> /var /usr/var none bind</screen> - <para>Assuming <filename>/var</filename> points to - <filename>C:/cygwin/var</filename>, <filename>/usr/var</filename> now - also points to <filename>C:/cygwin/var</filename>. This is equivalent - to the Linux <literal>bind</literal> option available since - Linux 2.4.0.</para> -</listitem> -</itemizedlist> - -<para>Whenever Cygwin generates a Win32 path from a POSIX one, it uses -the longest matching prefix in the mount table. Thus, if -<filename>C:</filename> is mounted as <filename>/c</filename> and also -as <filename>/</filename>, then Cygwin would translate -<filename>C:/foo/bar</filename> to <filename>/c/foo/bar</filename>. -This translation is normally only used when trying to derive the -POSIX equivalent current directory. Otherwise, the handling of MS-DOS -filenames bypasses the mount table. -</para> - -<para>If you want to see the current set of mount points valid in your -session, you can invoke the Cygwin tool <command>mount</command> without -arguments:</para> - -<example id="pathnames-mount-ex"> -<title>Displaying the current set of mount points</title> -<screen> - <prompt>bash$</prompt> <userinput>mount</userinput> - f:/cygwin/bin on /usr/bin type ntfs (binary,auto) - f:/cygwin/lib on /usr/lib type ntfs (binary,auto) - f:/cygwin on / type ntfs (binary,auto) - e:/src on /usr/src type vfat (binary) - c: on /cygdrive/c type ntfs (binary,posix=0,user,noumount,auto) - e: on /cygdrive/e type vfat (binary,posix=0,user,noumount,auto) -</screen> -</example> - -<para>You can also use the <command>mount</command> command to add -new mount points, and the <command>umount</command> to delete -them. However, since they are only stored in memory, these mount -points will disappear as soon as your last Cygwin process ends. -See <xref linkend="mount"></xref> and <xref linkend="umount"></xref> for more -information.</para> - -<note><para> -When you upgrade an existing older Cygwin installation to Cygwin 1.7, -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 role='bold'>never</emphasis> -generated. -</para> - -<para> -The old user mount points in your HKEY_CURRENT_USER branch of the registry -are not used to generate <filename>/etc/fstab</filename>. If you want -to create a user specific <filename>/etc/fstab.d/${USER}</filename> file -from your old entries, there's a script available which does exactly -that for you, <filename>/bin/copy-user-registry-fstab</filename>. Just -start the script and it will create your user specific fstab file. Stop -all your Cygwin processes and restart them, and you can simply use your -old user mount points as before. -</para></note> - -</sect2> - -<sect2 id="unc-paths"><title>UNC paths</title> - -<para>Apart from the unified POSIX tree starting at the <filename>/</filename> -directory, UNC pathnames starting with two slashes and a server name -(<filename>//machine/share/...</filename>) are supported as well. -They are handled as POSIX paths if only containing forward slashes. There's -also a virtual directory <filename>//</filename> which allows to enumerate -the fileservers known to the local machine with <command>ls</command>. -Same goes for the UNC paths of the type <filename>//machine</filename>, -which allow to enumerate the shares provided by the server -<literal>machine</literal>. For often used UNC paths it makes sense to -add them to the mount table (see <xref linkend="mount-table"></xref> so -they are included in the unified POSIX path tree.</para> - -</sect2> - -<sect2 id="cygdrive"><title>The cygdrive path prefix</title> - -<para>As already outlined in <xref linkend="ov-hi-files"></xref>, you can -access arbitary drives on your system by using the cygdrive path prefix. -The default value for this prefix is <filename>/cygdrive</filename>, and -a path to any drive can be constructed by using the cygdrive prefix and -appending the drive letter as subdirectory, like this:</para> - -<screen> - bash$ ls -l /cygdrive/f/somedir -</screen> - -<para>This lists the content of the directory F:\somedir.</para> - -<para>The cygdrive prefix is a virtual directory under which all drives -on a system are subsumed. The mount options of the cygdrive prefix is -used for all file access through the cygdrive prefixed drives. For instance, -assuming the cygdrive mount options are <literal>binary,posix=0</literal>, -then any file <filename>/cygdrive/x/file</filename> will be opened in -binary mode by default (mount option <literal>binary</literal>), and the case -of the filename doesn't matter (mount option <literal>posix=0</literal>). -</para> - -<para>The cygdrive prefix flags are also used for all UNC paths starting with -two slashes, unless they are accessed through a mount point. For instance, -consider these <filename>/etc/fstab</filename> entries:</para> - -<screen> - //server/share /mysrv ntfs posix=1,acl 0 0 - none /cygdrive cygdrive posix=0,noacl 0 0 -</screen> - -<para>Assume there's a file <filename>\\server\share\foo</filename> on the -share. When accessing it as <filename>/mysrv/foo</filename>, then the flags -<literal>posix=1,acl</literal> of the /mysrv mount point are used. When -accessing it as <filename>//server/share/foo</filename>, then the flags -for the cygdrive prefix, <literal>posix=0,noacl</literal> are used.</para> - -<note><para>This only applies to UNC paths using forward slashes. When -using backslashes the flags for native paths are used. See -<xref linkend="pathnames-win32"></xref>.</para></note> - -<para>The cygdrive prefix may be changed in the fstab file as outlined above. -Please note that you must not use the cygdrive prefix for any other mount -point. For instance this:</para> - -<screen> - none /cygdrive cygdrive binary 0 0 - D: /cygdrive/d somefs text 0 0 -</screen> - -<para>will not make file access using the /mnt/d path prefix suddenly using -textmode. If you want to mount any drive explicitly in another mode than -the cygdrive prefix, use a distinct path prefix:</para> - -<screen> - none /cygdrive cygdrive binary 0 0 - D: /mnt/d somefs text 0 0 -</screen> - -</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 -inadvisable. Those paths circumvent all internal integrity checking and -bypass the information given in the Cygwin mount table.</para> - -<para>The following paths are treated as native Win32 paths in Cygwin:</para> - -<itemizedlist spacing="compact"> - <listitem> - <para>All paths starting with a drive specifier</para> -<screen> - C:\foo - C:/foo -</screen> - </listitem> - <listitem> - <para>All paths containing at least one backslash as path component</para> -<screen> - C:/foo/bar<emphasis role='bold'>\</emphasis>baz/... -</screen> - </listitem> - <listitem> - <para>UNC paths using backslashes</para> -<screen> - \\server\share\... -</screen> - </listitem> -</itemizedlist> - -<para>When accessing files using native Win32 paths as above, Cygwin uses a -default setting for the mount flags. All paths using DOS notation will be -treated as case insensitive, and permissions are just faked as if the -underlying drive is a FAT drive. This also applies to NTFS and other -filesystems which usually are capable of case sensitivity and storing -permissions.</para> - -</sect2> - -<sect2 id="pathnames-win32-api"><title>Using the Win32 file API in Cygwin applications</title> - -<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 Windows idea of the current -working directory (CWD) is not necessarily the same as the Cygwin CWD. -There are a couple of restrictions in the Win32 API, which disallow certain -directories as Win32 CWD:</para> - -<itemizedlist spacing="compact"> - <listitem> - <para>The Windows subsystem only supports CWD paths of up to 258 chars. - This restriction doesn't apply for Cygwin processes, at least not as - long as they use the POSIX API (chdir, getcwd). This means, if a Cygwin - process has a CWD using an absolute path longer than 258 characters, the - Cygwin CWD and the Windows CWD differ.</para> - </listitem> - - <listitem> - <para>The Win32 API call to set the current directory, - <function>SetCurrentDirectory</function>, fails for directories for which - the user has no permissions, even if the user is an administrator. This - restriction doesn't apply for Cygwin processes, if they are running under - an administrator account.</para> - </listitem> - - <listitem> - <para><function>SetCurrentDirectory</function> does not support - case-sensitive filenames. - </para> - </listitem> - - <listitem> - <para>Last, but not least, <function>SetCurrentDirectory</function> can't - work on virtual Cygwin paths like /proc or /cygdrive. These paths only - exists in the Cygwin realm so they have no meaning to a native Win32 - process.</para> - </listitem> -</itemizedlist> - -<para>As long as the Cygwin CWD is usable as Windows CWD, the Cygwin and -Windows CWDs are in sync within a process. However, if the Cygwin process -changes its working directory into one of the directories which are -unusable as Windows CWD, we're in trouble. If the process uses the -Win32 API to access a file using a relative pathname, the resulting -absolute path would not match the expectations of the process. In the -worst case, the wrong files are deleted.</para> - -<para>To workaround this problem, Cygwin sets the Windows CWD to a special -directory in this case. This special directory points to a virtual -filesystem within the native NT namespace (<filename>\??\PIPE\</filename>). -Since it's not a real filesystem, the deliberate effect is that a call to, -for instance, <function>CreateFile ("foo", ...);</function> will fail, -as long as the processes CWD doesn't work as Windows CWD.</para> - -<para>So, in general, don't use the Win32 file API in Cygwin applications. -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> family of functions, you have to -make sure that the Cygwin CWD is set to some directory which is valid as -Win32 CWD.</para> - -</sect2> - -<sect2 id="pathnames-additional"><title>Additional Path-related Information</title> - -<para>The <command>cygpath</command> program provides the ability to -translate between Win32 and POSIX pathnames in shell scripts. See -<xref linkend="cygpath"></xref> for the details.</para> - -<para>The <envar>HOME</envar>, <envar>PATH</envar>, and -<envar>LD_LIBRARY_PATH</envar> environment variables are automatically -converted from Win32 format to POSIX format (e.g. from -<filename>c:/cygwin\bin</filename> to <filename>/bin</filename>, if -there was a mount from that Win32 path to that POSIX path) when a Cygwin -process first starts.</para> - -<para>Symbolic links can also be used to map Win32 pathnames to POSIX. -For example, the command -<command>ln -s //pollux/home/joe/data /data</command> would have about -the same effect as creating a mount point from -<filename>//pollux/home/joe/data</filename> to <filename>/data</filename> -using <command>mount</command>, except that symbolic links cannot set -the default file access mode. Other differences are that the mapping is -distributed throughout the file system and proceeds by iteratively -walking the directory tree instead of matching the longest prefix in a -kernel table. Note that symbolic links will only work on network -drives that are properly configured to support the "system" file -attribute. Many do not do so by default (the Unix Samba server does -not by default, for example).</para> - -</sect2> - -</sect1> |