diff options
Diffstat (limited to 'winsup/doc/pathnames.sgml')
| -rw-r--r-- | winsup/doc/pathnames.sgml | 586 |
1 files changed, 0 insertions, 586 deletions
diff --git a/winsup/doc/pathnames.sgml b/winsup/doc/pathnames.sgml deleted file mode 100644 index e2991544e..000000000 --- a/winsup/doc/pathnames.sgml +++ /dev/null @@ -1,586 +0,0 @@ -<sect1 id="using-pathnames"><title>Mapping path names</title> - -<sect2 id="pathnames-intro"><title>Introduction</title> - -<para>Cygwin supports both Win32- and POSIX-style paths, where -directory delimiters may be either forward or back slashes. UNC -pathnames (starting with two slashes and a network name) are also -supported.</para> - -<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 existance 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 content of the -user specifc 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. The noticable exception is the file system type -cygdrive. This type is used to set the cygdrive prefix.</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) and is ignored - otherwise. - 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. - binary - Files default to binary mode (default). - text - Files default to CRLF text mode line endings. - nouser - Mount is a system-wide mount. - user - Mount is a user mount. - exec - Treat all files below mount point as executable. - notexec - Treat all files below mount point as not executable. - cygexec - Treat all files below mount point as cygwin executables. - nosuid - No suid files are allowed (currently unimplemented). - posix=0 - Switch off case sensitivity for paths under this mount point. - posix=1 - Switch on case sensitivity for paths under this mount point - (default). -</screen> - -<para>Normally, 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>Note that nouser mount points are not overridable by a later call -to <command>mount</command>. This is only possible for user mount points. -Mount points given in <filename>/etc/fstab</filename> are by default nouser -mount points, unless you specify the option user. In contrast, all mount -points in the user specific fstab file are user 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 managed, textmode mount:</para> - <screen>C:/foo /bar/baz ntfs text,managed 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:</para> - <screen>//server/share/subdir /srv/subdir smbfs binary 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> -</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 invoking 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 system (binmode) -f:/cygwin/lib on /usr/lib type system (binmode) -f:/cygwin on / type system (binmode) -e:/src on /usr/src type system (binmode) -c: on /cygdrive/c type user (binmode,noumount) -e: on /cygdrive/e type user (binmode,noumount) -</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 noted 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> - -<para>Whenever Cygwin cannot use any of the existing mounts to convert -from a particular Win32 path to a POSIX one, Cygwin will -automatically default to an imaginary mount point under the default POSIX -path <filename>/cygdrive</filename>. For example, if Cygwin accesses -<filename>Z:/foo</filename> and the Z drive is not currently in the -mount table, then <filename>Z:/</filename> would be automatically -converted to <filename>/cygdrive/Z</filename>. The default -prefix of <filename>/cygdrive</filename> may be changed in the fstab file -as outlined above.</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> - -<sect1 id="using-specialnames"><title>Special filenames</title> - -<sect2 id="pathnames-dosdevices"> -<title>DOS devices</title> - -<para>Filenames invalid under Win32 are not necessarily invalid -under Cygwin since release 1.7.0. There are a couple of rules which -apply to Windows filenames. First of all, DOS device names like -<filename>AUX</filename>, <filename>COM1</filename>, -<filename>LPT1</filename> or <filename>PRN</filename> (to name a few) -cannot be used in a native Win32 application, even with an -extension (<filename>prn.txt</filename>). Cygwin can handle files with -these names just fine.</para> - -</sect2> - -<sect2 id="pathnames-specialchars"> -<title>Special characters in filenames</title> - -<para>Win32 filenames can't contain trailing dots and spaces for backward -compatibility. When trying to create files with trailing dots or spaces, -all of them are removed before the file is created. This restriction does -only affect native Win32 applications. Cygwin applications can create and -access files with trailing dots and spaces without problems.</para> - -<para>Some characters are disallowed in filenames on Windows filesystems:</para> - -<screen> - " * : < > ? | \ -</screen> - -<para>Cygwin can't fix this, but it has a method to workaround this -restriction. All of the above characters, except for the backslash, -are converted to special UNICODE characters in the range 0xf000 to 0xf0ff -(the "Private use area") when creating or accessing files.</para> - -</sect2> - -<sect2 id="pathnames-casesensitive"> -<title>Case sensitive filenames</title> - -<para>In the Win32 subsystem filenames are only case-preserved, but not -case-sensitive. You can't access two files in the same directory which -only differ by case, like <filename>Abc</filename> and -<filename>aBc</filename>. While NTFS (and some remote filesystems) -support case-sensitivity, the NT kernel starting with Windows XP does -not support it by default. Rather, you have to tweak a registry setting -and reboot. For that reason, case-sensitivity is not supported by Cygwin, -unless you change that registry value.</para> - -<para>If you really want case-sensitivity in Cygwin, you can switch it -on by setting the registry value</para> - -<screen> -HKLM\SYSTEM\CurrentControlSet\Control\Session Manager\kernel\obcaseinsensitive -</screen> - -<para>to 0 and reboot the machine. For least surprise, Cygwin expects -this registry value also on Windows NT4 and Windows 2000, which usually -both don't know this registry key. If you want case-sensitivity on these -systems, create that registry value and set it to 0. On these systems -(and *only* on these systems) you don't have to reboot to bring it -into effect.</para> - -<note> -<para> -Note that when installing Microsoft's Services For Unix (SFU), you're asked if -you want to use case-sensitive filenames. If you answer "yes" at this point, -the installer will change the aforementioned registry value to 0, too. So, if -you have SFU installed, there's some chance that the registry value is already -set to case sensitivity. -</para> -</note> - -<para>After you set this registry value to 0, Cygwin will be case-sensitive -by default on NTFS and NFS filesystems. Be aware that using two filenames -which only differ by case might result in some weird interoperability -issues with native Win32 applications. You're using case-sensitivity -at your own risk. You have been warned!</para> - -<para>Even if you use case-sensitivity, it might be feasible to switch to -case-insensitivity for certain paths for better interoperability with -native Win32 applications (even if it's just Windows Explorer). You can do -this on a per-mount point base, by using the "posix=0" mount option in -/etc/fstab, or your /etc/fstab.d/$USER file.</para> - -<para>For a start, it might be best to switch the cygdrive path to -case-insensitivity, because the default Windows $PATH variable is not -always using the correct case by default. As a result, your shell will -claim that it can't find Windows commands like <command>attrib</command> -or <command>net</command>. Here's an example how you can switch the -cygdrive prefix to case-insensitivity:</para> - -<example id="mount-caseinsensitive"> -<title>Example mount point to enforce case-insensitivity on cygdrive paths</title> -<screen> -none /cygdrive cygdrive binary,posix=0 0 0 -</screen> -</example> - -<para>Note that mount points as well as device names and virtual -paths like /proc are always case-sensitive! The only exception are -the subdirs and filenames under /proc/registry, /proc/registry32 -and /proc/registry64. Registry access is always case-insensitive. -Read on for more information.</para> - -</sect2> - -<sect2 id="pathnames-posixdevices"> <title>POSIX devices</title> -<para>There is no need to create a POSIX <filename>/dev</filename> -directory as Cygwin automatically simulates it internally. -These devices cannot be seen with the command <command>ls /dev/</command> -although commands such as <command>ls /dev/tty</command> work fine. -If you want to be able to see all devices in -<filename>/dev/</filename>, you can use Igor Pechtchanski's -<ulink -url="http://cygwin.com/ml/cygwin/2004-03/txt00028.txt">create_devices.sh</ulink> -script. -</para> - -<para> -Cygwin supports the following character devices commonly found on POSIX systems: -</para> - -<screen> -/dev/null -/dev/zero -/dev/full - -/dev/console Pseudo device name for the standard console window created - by Windows. Same as the one used for cmd.exe. Every one - of them has this name. It's not quite comparable with the - console device on UNIX machines. - -/dev/tty The current tty of a session running in a pseudo tty. -/dev/ptmx Pseudo tty master device. -/dev/ttym - -/dev/tty0 Pseudo ttys are numbered from /dev/tty0 upwards as they are -/dev/tty1 requested. -... - -/dev/ttyS0 Serial communication devices. ttyS0 == Win32 COM1, -/dev/ttyS1 ttyS1 == COM2, etc. -... - -/dev/pipe -/dev/fifo - -/dev/mem The physical memory of the machine. Note that access to the -/dev/port physical memory has been restricted with Windows Server 2003. -/dev/kmem Since this OS, you can't access physical memory from user space. - -/dev/kmsg Kernel message pipe, for usage with sys logger services. - -/dev/random Random number generator. -/dev/urandom - -/dev/dsp Default sound device of the system. -</screen> - -<para> -Cygwin also has several Windows-specific devices: -</para> - -<screen> -/dev/com1 The serial ports, starting with COM1 which is the same as ttyS0. -/dev/com2 Please use /dev/ttySx instead. -... - -/dev/conin Same as Windows CONIN$. -/dev/conout Same as Windows CONOUT$. -/dev/clipboard The Windows clipboard, text only -/dev/windows The Windows message queue. -</screen> - -<para> -Block devices are accessible by Cygwin processes using fixed POSIX device -names. These POSIX device names are generated using a direct conversion -from the POSIX namespace to the internal NT namespace. -E.g. the first harddisk is the NT internal device \device\harddisk0\partition0 -or the first partition on the third harddisk is \device\harddisk2\partition1. -The first floppy in the system is \device\floppy0, the first CD-ROM is -\device\cdrom0 and the first tape drive is \device\tape0. The mapping -to the POSIX /dev namespace is as follows: -</para> - -<screen> -/dev/st0 \device\tape0, rewind -/dev/nst0 \device\tape0, no-rewind -/dev/st1 \device\tape1 -/dev/nst1 \device\tape1 -... -/dev/st15 -/dev/nst15 - -/dev/fd0 \device\floppy0 -/dev/fd1 \device\floppy1 -... -/dev/fd15 - -/dev/sr0 \device\cdrom0 -/dev/sr1 \device\cdrom1 -... -/dev/sr15 - -/dev/scd0 \device\cdrom0 -/dev/scd1 \device\cdrom1 -... -/dev/scd15 - -/dev/sda \device\harddisk0\partition0 (whole disk) -/dev/sda1 \device\harddisk0\partition1 (first partition) -... -/dev/sda15 \device\harddisk0\partition15 (fifteenth partition) - -/dev/sdb \device\harddisk1\partition0 -/dev/sdb1 \device\harddisk1\partition1 - -[up to] - -/dev/sddx \device\harddisk127\partition0 -/dev/sddx1 \device\harddisk127\partition1 -... -/dev/sddx15 \device\harddisk127\partition15 -</screen> - -<para> -if you don't like these device names, feel free to create symbolic -links as they are created on Linux systems for convenience: -</para> - -<screen> -ln -s /dev/sr0 /dev/cdrom -ln -s /dev/nst0 /dev/tape -... -</screen> - -</sect2> - -<sect2 id="pathnames-exe"><title>The .exe extension</title> - -<para>Win32 executable filenames end with <filename>.exe</filename> -but the <filename>.exe</filename> need not be included in the command, -so that traditional UNIX names can be used. However, for programs that -end in <filename>.bat</filename> and <filename>.com</filename>, you -cannot omit the extension. </para> - -<para>As a side effect, the <command> ls filename</command> gives -information about <filename>filename.exe</filename> if -<filename>filename.exe</filename> exists and <filename>filename</filename> -does not. In the same situation the function call -<function>stat("filename",..)</function> gives information about -<filename>filename.exe</filename>. The two files can be distinguished -by examining their inodes, as demonstrated below. -<screen> -<prompt>bash$</prompt> <userinput>ls * </userinput> -a a.exe b.exe -<prompt>bash$</prompt> <userinput>ls -i a a.exe</userinput> -445885548 a 435996602 a.exe -<prompt>bash$</prompt> <userinput>ls -i b b.exe</userinput> -432961010 b 432961010 b.exe -</screen> -If a shell script <filename>myprog</filename> and a program -<filename>myprog.exe</filename> coexist in a directory, the shell -script has precedence and is selected for execution of -<command>myprog</command>. Note that this was quite the reverse up to -Cygwin 1.5.19. It has been changed for consistency with the rest of Cygwin. -</para> - -<para>The <command>gcc</command> compiler produces an executable named -<filename>filename.exe</filename> when asked to produce -<filename>filename</filename>. This allows many makefiles written -for UNIX systems to work well under Cygwin.</para> - -</sect2> - -<sect2 id="pathnames-proc"><title>The /proc filesystem</title> -<para> -Cygwin, like Linux and other similar operating systems, supports the -<filename>/proc</filename> virtual filesystem. The files in this -directory are representations of various aspects of your system, -for example the command <userinput>cat /proc/cpuinfo</userinput> -displays information such as what model and speed processor you have. -</para> -<para> -One unique aspect of the Cygwin <filename>/proc</filename> filesystem -is <filename>/proc/registry</filename>, see next section. -</para> -<para> -The Cygwin <filename>/proc</filename> is not as complete as the -one in Linux, but it provides significant capabilities. The -<systemitem>procps</systemitem> package contains several utilities -that use it. -</para> -</sect2> - -<sect2 id="pathnames-proc-registry"><title>The /proc/registry filesystem</title> -<para> -The <filename>/proc/registry</filename> filesystem provides read-only -access to the Windows registry. It displays each <literal>KEY</literal> -as a directory and each <literal>VALUE</literal> as a file. As anytime -you deal with the Windows registry, use caution since changes may result -in an unstable or broken system. There are additionally subdirectories called -<filename>/proc/registry32</filename> and <filename>/proc/registry64</filename>. -They are identical to <filename>/proc/registry</filename> on 32 bit -host OSes. On 64 bit host OSes, <filename>/proc/registry32</filename> -opens the 32 bit processes view on the registry, while -<filename>/proc/registry64</filename> opens the 64 bit processes view. -</para> -<para> -Reserved characters ('/', '\', ':', and '%') or reserved names -(<filename>.</filename> and <filename>..</filename>) are converted by -percent-encoding: -<screen> -<prompt>bash$</prompt> <userinput>regtool list -v '\HKEY_LOCAL_MACHINE\SYSTEM\MountedDevices'</userinput> -... -\DosDevices\C: (REG_BINARY) = cf a8 97 e8 00 08 fe f7 -... -<prompt>bash$</prompt> <userinput>cd /proc/registry/HKEY_LOCAL_MACHINE/SYSTEM</userinput> -<prompt>bash$</prompt> <userinput>ls -l MountedDevices</userinput> -... --r--r----- 1 Admin SYSTEM 12 Dec 10 11:20 %5CDosDevices%5CC%3A -... -<prompt>bash$</prompt> <userinput>od -t x1 MountedDevices/%5CDosDevices%5CC%3A</userinput> -0000000 cf a8 97 e8 00 08 fe f7 01 00 00 00 -</screen> -The unnamed (default) value of a key can be accessed using the filename -<filename>@</filename>. -</para> -<para> -If a registry key contains a subkey and a value with the same name -<filename>foo</filename>, Cygwin displays the subkey as -<filename>foo</filename> and the value as <filename>foo%val</filename>. -</para> -</sect2> - -<sect2 id="pathnames-at"><title>The @pathnames</title> -<para>To circumvent the limitations on shell line length in the native -Windows command shells, Cygwin programs expand their arguments -starting with "@" in a special way. If a file -<filename>pathname</filename> exists, the argument -<filename>@pathname</filename> expands recursively to the content of -<filename>pathname</filename>. Double quotes can be used inside the -file to delimit strings containing blank space. -Embedded double quotes must be repeated. -In the following example compare the behaviors of the bash built-in -<command>echo</command> and of the program <command>/bin/echo</command>.</para> - -<example id="pathnames-at-ex"><title> Using @pathname</title> -<screen> -<prompt>bash$</prompt> <userinput>echo 'This is "a long" line' > mylist</userinput> -<prompt>bash$</prompt> <userinput>echo @mylist</userinput> -@mylist -<prompt>bash$</prompt> <userinput>cmd</userinput> -<prompt>c:\></prompt> <userinput>c:\cygwin\bin\echo @mylist</userinput> -This is a long line -</screen> -</example> -</sect2> -</sect1> |