1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
|
<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. Directory
delimiters may be either forward slashes or backslashes. Paths using
backslashes 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. UNC pathnames
(starting with two slashes and a network name) are also supported.</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 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 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. The notable 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.
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).
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 without ACL support:</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 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 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="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 <literal>/cygdrive</literal>, 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 <literal>/cygdrive/x/file</literal> 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-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 caseinsensitive, 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 casesensitivity 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>
<sect1 id="using-specialnames"><title>Special filenames</title>
<sect2 id="pathnames-etc"><title>Special files in /etc</title>
<para>Certain files in Cygwin's <filename>/etc</filename> directory are
read by Cygwin before the mount table has been established. The list
of files is</para>
<screen>
/etc/fstab
/etc/fstab.d/$USER
/etc/passwd
/etc/group
</screen>
<para>These file are read using native Windows NT functions which have
no notion of Cygwin symlinks or POSIX paths. For that reason
there are a few requirements as far as <filename>/etc</filename> is
concerned.</para>
<para>To access these files, the Cygwin DLL evaluates it's own full
Windows path, strips off the innermost directory component and adds
"\etc". Let's assume the Cygwin DLL is installed as
<filename>C:\cygwin\bin\cygwin1.dll</filename>. First the DLL name as
well as the innermost directory (<filename>bin</filename>) is stripped
off: <filename>C:\cygwin\</filename>. Then "etc" and the filename to
look for is attached: <filename>C:\cygwin\etc\fstab</filename>. So the
/etc directory must be parallel to the directory in which the cygwin1.dll
exists and <filename>/etc</filename> must not be a Cygwin symlink
pointing to another directory. Consequentially none of the files from
the above list, including the directory <filename>/etc/fstab.d</filename>
is allowed to be a Cygwin symlink either.</para>
<para>However, native NTFS symlinks and reparse points are transparent
when accessing the above files so all these files as well as
<filename>/etc</filename> itself may be NTFS symlinks or reparse
points.</para>
<para>Last but not least, make sure that these files are world-readable.
Every process of any user account has to read these files potentially,
so world-readability is essential. The only exception are the user
specific files <filename>/etc/fstab.d/$USER</filename>, which only have
to be readable by the $USER user account itself.</para>
</sect2>
<sect2 id="pathnames-dosdevices"><title>Invalid filenames</title>
<para>Filenames invalid under Win32 are not necessarily invalid
under Cygwin since release 1.7.0. There are a few rules which
apply to Windows filenames. Most notably, DOS device names like
<filename>AUX</filename>, <filename>COM1</filename>,
<filename>LPT1</filename> or <filename>PRN</filename> (to name a few)
cannot be used as filename or extension in a native Win32 application.
So filenames like <filename>prn.txt</filename> or <filename>foo.aux</filename>
are invalid filenames for native Win32 applications.</para>
<para>This restriction doesn't apply to Cygwin applications. Cygwin
can create and access files with such names just fine. Just don't try
to use these files with native Win32 applications.</para>
</sect2>
<sect2 id="pathnames-specialchars">
<title>Forbidden characters in filenames</title>
<para>Some characters are disallowed in filenames on Windows filesystems.
These forbidden characters are the ASCII control characters from ASCII
value 1 to 31, plus the following characters which have a special meaning
in the Win32 API:</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>
<para>The backslash has to be exempt from this conversion, because Cygwin
accepts Win32 filenames including backslashes as path separators on input.
Converting backslashes using the above method would make this impossible.</para>
<para>Additionally Win32 filenames can't contain trailing dots and spaces
for DOS backward compatibility. When trying to create files with trailing
dots or spaces, all of them are removed before the file is created. This
restriction only affects native Win32 applications. Cygwin applications
can create and access files with trailing dots and spaces without problems.
</para>
<para>An exception from this rule are some network filesystems (NetApp,
NWFS) which choke on these filenames. They return with an error like
"No such file or directory" when trying to create such files. Starting
with Cygwin 1.7.6, Cygwin recognizes these filesystems and works around
this problem by applying the same rule as for the other forbidden characters.
Leading spaces and trailing dots and spaces will be converted to UNICODE
characters in the private use area. This behaviour can be switched on
explicitely for a filesystem or a directory tree by using the mount option
<literal>dos</literal>.</para>
</sect2>
<sect2 id="pathnames-unusual">
<title>Filenames with unusual (foreign) characters</title>
<para> Windows filesystems use Unicode encoded as UTF-16
to store filename information. If you don't use the UTF-8
character set (see <xref linkend="setup-locale"></xref>) then there's a
chance that a filename is using one or more characters which have no
representation in the character set you're using.</para>
<note><para>In the default "C" locale, Cygwin creates filenames using
the UTF-8 charset. This will always result in some valid filename by
default, but again might impose problems when switching to a non-"C"
or non-"UTF-8" charset.</para></note>
<note><para>To avoid this scenario altogether, always use UTF-8 as the
character set.</para></note>
<para>If you don't want or can't use UTF-8 as character set for whatever
reason, you will nevertheless be able to access the file. How does that
work? When Cygwin converts the filename from UTF-16 to your character
set, it recognizes characters which can't be converted. If that occurs,
Cygwin replaces the non-convertible character with a special character
sequence. The sequence starts with an ASCII CAN character (hex code
0x18, equivalent Control-X), followed by the UTF-8 representation of the
character. The result is a filename containing some ugly looking
characters. While it doesn't <emphasis role='bold'>look</emphasis> nice, it
<emphasis role='bold'>is</emphasis> nice, because Cygwin knows how to convert
this filename back to UTF-16. The filename will be converted using your
usual character set. However, when Cygwin recognizes an ASCII CAN
character, it skips over the ASCII CAN and handles the following bytes as
a UTF-8 character. Thus, the filename is symmetrically converted back to
UTF-16 and you can access the file.</para>
<note><para>Please be aware that this method is not entirely foolproof.
In some character set combinations it might not work for certain native
characters.</para>
<para>Only by using the UTF-8 charset you can avoid this problem safely.
</para></note>
</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 can not be 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 2000, which usually doesn't know this
registry key. If you want case-sensitivity on Windows 2000, just create
that registry value and set it to 0. <emphasis role='bold'>Only</emphasis>
on Windows 2000 you don't have to reboot to bring it into effect, rather
stopping all Cygwin processes and then restarting them is sufficient.</para>
<note>
<para>
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. However, there are limitations:
while two <emphasis role='bold'>programs</emphasis> <filename>Abc.exe</filename>
and <filename>aBc.exe</filename> can be created and accessed like other files,
starting applications is still case-insensitive due to Windows limitations
and so the program you try to launch may not be the one actually started. Also,
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
<filename>/etc/fstab</filename>, or your <filename>/etc/fstab.d/$USER</filename>
file.</para>
<para><filename>/cygdrive</filename> paths are case-insensitive by default.
The reason is that the native Windows %PATH% environment variable is not
always using the correct case for all paths in it. As a result, if you use
case-sensitivity on the <filename>/cygdrive</filename> prefix, your shell
might claim that it can't find Windows commands like <command>attrib</command>
or <command>net</command>. To ease the pain, the <filename>/cygdrive</filename>
path is case-insensitive by default and you have to use the "posix=1" setting
explicitly in <filename>/etc/fstab</filename> or
<filename>/etc/fstab.d/$USER</filename> to switch it to case-sensitivity,
or you have to make sure that the native Win32 %PATH% environment variable
is using the correct case for all paths throughout.</para>
<para>Note that mount points as well as device names and virtual
paths like /proc are always case-sensitive! The only exception are
the subdirectories 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 well-known 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. This script does not add the raw disk devices, though. Again,
it's not necessary to see an existing device in /dev to access it. The script
is just for the fun of it.
</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 current console window of a session.
Up to Cygwin 1.7.9, this was the only name for a console.
Different consoles were indistinguishable.
Cygwin's /dev/console is not quite comparable with the console
device on UNIX machines.
/dev/cons0 Starting with Cygwin 1.7.10, Console sessions are numbered from
/dev/cons1 /dev/cons0 upwards. Console device names are pseudo device
... names, only accessible from processes within this very console
session. This is due to a restriction in Windows.
/dev/tty The current controlling tty of a session.
/dev/ptmx Pseudo tty master device.
/dev/pty0 Pseudo ttys are numbered from /dev/pty0 upwards as they are
/dev/pty1 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.</para>
<para>The mapping from physical device to the name of the device in the
internal NT namespace can be found in various places. For hard disks and
CD/DVD drives, the Windows "Disk Management" utility (part of the
"Computer Management" console) shows that the mapping of "Disk 0" is
\device\harddisk0. "CD-ROM 2" is \device\cdrom2. Another place to find
this mapping is the "Device Management" console. Disks have a
"Location" number, tapes have a "Tape Symbolic Name", etc.
Unfortunately, the places where this information is found is not very
well-defined.</para>
<para>
For external disks (USB-drives, CF-cards in a cardreader, etc) you can use
Cygwin to show the mapping. <filename>/proc/partitions</filename>
contains a list of raw drives known to Cygwin. The <command>df</command>
command shows a list of drives and their respective sizes. If you match
the information between <filename>/proc/partitions</filename> and the
<command>df</command> output, you should be able to figure out which
external drive corresponds to which raw disk device name.</para>
<note><para>Apart from tape devices which are not block devices and are
by default accessed directly, accessing mass storage devices raw
is something you should only do if you know what you're doing and know how to
handle the information. <emphasis role='bold'>Writing</emphasis> to a raw
mass storage device you should only do if you
<emphasis role='bold'>really</emphasis> know what you're doing and are aware
of the fact that any mistake can destroy important information, for the
device, and for you. So, please, handle this ability with care.
<emphasis role='bold'>You have been warned.</emphasis></para></note>
<para>
Last but not least, the mapping from POSIX /dev namespace to internal
NT namespace is as follows:
</para>
<screen>
POSIX device name Internal NT device name
/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>
|