diff options
Diffstat (limited to 'winsup/doc/pathnames.sgml')
| -rw-r--r-- | winsup/doc/pathnames.sgml | 361 |
1 files changed, 0 insertions, 361 deletions
diff --git a/winsup/doc/pathnames.sgml b/winsup/doc/pathnames.sgml deleted file mode 100644 index 00b216e92..000000000 --- a/winsup/doc/pathnames.sgml +++ /dev/null @@ -1,361 +0,0 @@ -<sect1 id="using-pathnames"><title>Mapping path names</title> - -<sect2><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 between Win32 and POSIX paths as -necessary.</para> - -</sect2> - -<sect2 id="mount-table"><title>The Cygwin Mount Table</title> - -<para>The <command>mount</command> utility program is used to -to map Win32 drives and network shares into Cygwin's internal POSIX -directory tree. This is a similar concept to the typical UNIX mount -program. For those people coming from a Windows background, the -<command>mount</command> utility is very similar to the old DOS -<command>join</command>, in that it makes your drive letters appear as -subdirectories somewhere else.</para> - -<para>The mapping is stored in the current user's Cygwin -<FirstTerm>mount table</FirstTerm> in the Windows registry so that the -information will be retrieved next time the user logs in. Because it -is sometimes desirable to have system-wide as well as user-specific -mounts, there is also a system-wide mount table that all Cygwin users -inherit. The system-wide table may only be modified by a user with -the appropriate priviledges (Administrator priviledges in Windows -NT).</para> - -<para>The current user's table is located under -"HKEY_CURRENT_USER/Software/Red Hat, Inc./Cygwin/mounts -v<version>" -where <version> is the latest registry version associated with -the Cygwin library (this version is not the same as the release -number). The system-wide table is located under the same subkeys -under HKEY_LOCAL_SYSTEM.</para> - -<para>By default, the POSIX root <filename>/</filename> points to the -system partition but it can be relocated to any directory in the -Windows file system using the <command>mount</command> command. -Whenever Cygwin generates a POSIX path from a Win32 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>.</para> - -<para>Invoking <command>mount</command> without any arguments displays -Cygwin's current set of mount points. -In the following example, the C -drive is the POSIX root and D drive is mapped to -<filename>/d</filename>. Note that in this case, the root mount is a -system-wide mount point that is visible to all users running Cygwin -programs, whereas the <filename>/d</filename> mount is only visible -to the current user.</para> - -<example> -<title>Displaying the current set of mount points</title> -<screen> -<prompt>c:\></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. See <Xref Linkend="mount"> and <Xref Linkend="umount"> for more -information on how to use these utilities to set up your Cygwin POSIX -file system.</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 (see the -<Xref Linkend="mount"> for more information).</para> - -<para>It is possible to assign some special attributes to each mount -point. Automatically mounted partitions are displayed as "auto" -mounts. Mounts can also be marked as either "textmode" or "binmode" --- whether text files are read in the same manner as binary files by -default or not (see <Xref Linkend="using-textbinary"> for more -information on text and binary modes.</para> - -</sect2> - -<sect2><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"> 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> <title>DOS devices</title> - -<para>Windows filenames invalid under Windows are also invalid under -Cygwin. This means that base filenames such as -<filename>AUX</filename>, <filename>COM1</filename>, -<filename>LPT1</filename> or <filename>PRN</filename> (to name a few) -cannot be used in a regular Cygwin Windows or POSIX path, even with an -extension (<filename>prn.txt</filename>). However the special names can be -used as filename extensions (<filename>file.aux</filename>). You can use -the special names as you would under DOS, for example you can print on your -default printer with the command <command>cat filename > PRN</command> -(make sure to end with a Form Feed). -</para> - -</sect2> - -<sect2> <Title>POSIX devices</title> -<para>There is no need to create a POSIX <filename>/dev</filename> -directory as it is simulated within Cygwin automatically. -It supports the following devices: <filename>/dev/null</filename>, -<filename>/dev/zero</filename>, <filename>/dev/tty</filename>, -<filename>/dev/ttyX</filename>, <filename>/dev/ptmx</filename>, -<filename>/dev/comX</filename> (the serial ports), -<filename>/dev/windows</filename> (the windows message queue), -<filename>/dev/random</filename> and <filename>/dev/urandom</filename>. -These devices cannot be seen with the command <command>ls /dev</command> -although commands such as <command>ls /dev/tty</command> work fine. -</para> - -<para>Windows NT/W2K/XP additionally support raw devices like floppies, -disks, partitions and tapes. These are accessed from Cygwin applications -using POSIX device names which are supported in two different ways. -Up to 1.3.3, Cygwin only uses Win32 device names, since 1.3.4 -it additionally uses NT internal device names. -</para> - -<para>Up to Cygwin 1.3.3 the only way to access those devices is -to mount the Win32 device names to a POSIX device name. -</para> - -<para> -The Win32 device name for a partition is the drive letter -with leading <filename>\\.\</filename>, so the floppy would be -<filename>\\.\A:</filename>, the first partition typically -<filename>\\.\C:</filename>. Complete drives (except floppies and CD-ROMS -which are supported as partitions only) are named -<filename>\\.\PHYSICALDRIVEx</filename>. The <literal>x</literal> -is the drive number which you can check in the disk manager. -Each drive line has prepended the text "Disk x". -</para> - -<para>To access tape drives the Win32 file name <filename>\\.\TAPEx</filename> -is used. For example the first installed tape device is named -<filename>\\.\tape0</filename>. -</para> - -<para> -The naming convention is simple: The name of the POSIX device has to begin with -<filename>/dev/</filename> and the rest is as you like. The only -exception are tape devices. To identify if the tape device is -used as a rewind or a no-rewind device the name must not begin with -<literal>n</literal> (rewind) or has to begin with <literal>n</literal> -(no-rewind). -</para> - -<para>Some examples:</para> - -<screen> -mount -b //./A: /dev/fd0 # mount floppy as raw block special -mount -b //./physicaldrive1 /dev/hdb # mount "Disk 1" -mount -b //./tape0 /dev/st0 # mount first tape as the rewind device... -mount -b //./tape0 /dev/nst0 # ...and as the no-rewind device -</screen> - -<para>Note the usage of the <literal>-b</literal> option. It is best to -include the -b option when mounting these devices to ensure that all -file I/O is in "binary mode". -</para> - -<para> -Since Cygwin 1.3.4 raw devices are accessible from inside of Cygwin processes -using fixed POSIX device names. That means, you don't have to mount the devices -anymore which results in a more cleaner mount table. -</para> - -<para> -These new fixed 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. -</para> - -<para>The new fixed POSIX names are mapped to NT internal devices as -follows:</para> - -<screen> -/dev/st0 \device\tape0, rewind -/dev/nst0 \device\tape0, no-rewind -/dev/st1 \device\tape1 -... - -/dev/fd0 \device\floppy0 -/dev/fd1 \device\floppy1 -... - -/dev/scd0 \device\cdrom0 -/dev/scd1 \device\cdrom1 -... - -/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/sdl \device\harddisk11\partition0 -/dev/sdl1 \device\harddisk11\partition1 -... -/dev/sdl15 \device\harddisk11\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/scd0 /dev/cdrom -ln -s /dev/st0 /dev/tape -... -</screen> - -<para> -Note that you can't use the mount table to map from fixed device name -to your own device name or to map from internal NT device name to -your own device name. The following two examples will not work: -</para> - -<screen> -mount -s -f -b /dev/st0 /dev/tape -mount -s -f -b /device/tape0 /dev/tape -</screen> - -</sect2> - -<sect2><title>The .exe extension</title> - -<para> Executable program filenames end with .exe but the .exe need -not be included in the command, so that traditional UNIX names can be -used. However, for programs that end in ".bat" and ".com", 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>C:\></prompt> <userinput>ls * </userinput> -a a.exe b.exe -<prompt>C:\></prompt> <userinput>ls -i a a.exe</userinput> -445885548 a 435996602 a.exe -<prompt>C:\></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 program -has precedence and is selected for execution of -<command>myprog</command>.</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> - -<para>Unfortunately, the <command>install</command> and -<command>strip</command> commands do distinguish between -<filename>filename</filename> and <filename>filename.exe</filename>. They -fail when working on a non-existing <filename>filename</filename> even if -<filename>filename.exe</filename> exists, thus breaking some makefiles. -This problem can be solved by writing <command>install</command> and -<command>strip</command> shell scripts to provide the extension ".exe" -when needed. -</para> -</sect2> - -<sect2><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><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>/bin/echo @mylist</userinput> -This is a long line -<prompt>bash$</prompt> <userinput>rm mylist</userinput> -<prompt>bash$</prompt> <userinput>/bin/echo @mylist</userinput> -@mylist -</screen> -</example> -</sect2> -</sect1> |