From 85f1119b7b81b9661d3f7e47d6f42d9939bcaad1 Mon Sep 17 00:00:00 2001 From: Corinna Vinschen Date: Thu, 17 Jul 2008 11:49:45 +0000 Subject: [PATCH] * Revamp documentation for Cygwin 1.7, part 1. --- winsup/doc/ChangeLog | 4 + winsup/doc/cygserver.sgml | 31 +-- winsup/doc/cygwin-ug.in.sgml | 6 +- winsup/doc/cygwinenv.sgml | 174 +++++++------ winsup/doc/effectively.sgml | 64 ++--- winsup/doc/filemodes.sgml | 45 ++-- winsup/doc/gcc.sgml | 2 +- winsup/doc/gdb.sgml | 6 +- winsup/doc/legal.sgml | 2 +- winsup/doc/ntsec.sgml | 489 ++++++++++++++++------------------- winsup/doc/overview.sgml | 36 +-- winsup/doc/overview2.sgml | 293 +++++++++++---------- winsup/doc/pathnames.sgml | 442 +++++++++++++++++++++---------- winsup/doc/setup-net.sgml | 20 +- winsup/doc/setup2.sgml | 30 ++- winsup/doc/textbinary.sgml | 28 +- 16 files changed, 917 insertions(+), 755 deletions(-) diff --git a/winsup/doc/ChangeLog b/winsup/doc/ChangeLog index e3b2f23e1..aa0f1800b 100644 --- a/winsup/doc/ChangeLog +++ b/winsup/doc/ChangeLog @@ -1,3 +1,7 @@ +2008-07-17 Corinna Vinschen + + * Revamp documentation for Cygwin 1.7, part 1. + 2008-07-01 Christopher Faylor * Makefile.in: Temporarily add ability to generate pdfs. diff --git a/winsup/doc/cygserver.sgml b/winsup/doc/cygserver.sgml index 27e538b2a..2f34bbbd7 100644 --- a/winsup/doc/cygserver.sgml +++ b/winsup/doc/cygserver.sgml @@ -41,6 +41,7 @@ + -f, --config-file <file> Use <file> as configuration file instead of the default configuration @@ -52,6 +53,7 @@ This option has no counterpart in the configuration file, for obvious reasons. + -c, --cleanup-threads <num> @@ -96,8 +98,7 @@ -y, --syslog Force logging to the system log. This is the default, if stderr is not - connected to a tty, e. g. redirected to a file. Note, that on 9x/Me - systems the syslog is faked by a file C:\CYGWIN_SYSLOG.TXT. + connected to a tty, e. g. redirected to a file. Configuration file option: kern.log.syslog @@ -143,8 +144,8 @@ -S, --shutdown Shutdown a running daemon and exit. Other methods are sending a SIGHUP - to the Cygserver PID or, if running as service under NT, calling - `net stop cygserver' or `cygrunsrv -E cygserver'. + to the Cygserver PID or, if running as service, calling `net stop + cygserver' or `cygrunsrv -E cygserver'. @@ -168,22 +169,16 @@ Before you run Cygserver for the first time, you should run the /usr/bin/cygserver-config script once. It creates the default - configuration file and, upon request, installs Cygserver as service - when running under NT. The script only performs a default install, - with no further options given to Cygserver when running as service. - Due to the wide configurability by changing the configuration file, - that's typically not necessary. - - - On Windows 9x/Me, just start Cygserver in any console window. It's - advisable to redirect stderr to a file of choice (e. g. - /var/log/cygserver.log) and to use the -e and -Y options or the - set the appropriate settings in the configuration file (see below). + configuration file and, upon request, installs Cygserver as service. + The script only performs a default install, with no further options + given to Cygserver when running as service. Due to the wide + configurability by changing the configuration file, that's typically + not necessary. - On Windows NT/2000/XP or 2003, you should always run Cygserver as a - service under LocalSystem account. This is the way it is installed - for you by the /usr/bin/cygserver-config script. + You should always run Cygserver as a service under LocalSystem account. + This is the way it is installed for you by the /usr/bin/cygserver-config + script. diff --git a/winsup/doc/cygwin-ug.in.sgml b/winsup/doc/cygwin-ug.in.sgml index 64869fdce..65902e903 100644 --- a/winsup/doc/cygwin-ug.in.sgml +++ b/winsup/doc/cygwin-ug.in.sgml @@ -1,10 +1,12 @@ 1999,2000,2001 + 1999,2000,2001,2002,2003,2004,2005,2006,2007,2008 Red Hat, Inc."> The <envar>CYGWIN</envar> environment variable + +Implemented options + The CYGWIN environment variable is used to configure many global settings for the Cygwin runtime system. It contains the options listed below, separated by blank characters. Many options can be turned off -by prefixing with no . +by prefixing with no. @@ -12,7 +15,8 @@ by prefixing with no . (e.g. pipe and COM ports) file opens default to binary mode (no CRLF translation) instead of text mode. Defaults to set (binary mode). By default, devices are opened in binary mode, so this option -has little effect on normal cygwin operations. +has little effect on normal cygwin operations. Sockets are always +in binary mode. It does affect two things, however. For non-NTFS filesystems, this option will control the line endings for standard output/input/error @@ -21,52 +25,28 @@ the default translation mode of a pipe, although most shells set the pipe to binary by default. - -check_case:level - THIS OPTION IS DEPRECATED. -Don't use it unless you know what you're doing and don't see any way -around it. And even then, this option is error prone, slows down Cygwin -and not well maintained. This option controls the behavior of -Cygwin when a user tries to open or create a file using a case different from -the case of the path as saved on the disk. -level is one of relaxed, -adjust and strict. - - -relaxed which is the default behaviour simply -ignores case. That's the default for native Windows applications as well. - - -adjust behaves mostly invisible. The POSIX input -path is internally adjusted in case, so that the resulting DOS path uses the -correct case throughout. You can see the result when changing the directory -using a wrong case and calling /bin/pwd afterwards. - - -strict results in a error message if the case -isn't correct. Trying to open a file Foo while a file -fOo exists results in a "no such file or directory" -error. Trying to create a file BAR while a file -Bar exists results in a "Filename exists with different -case" error. - - - -codepage:[ansi|oem] - Windows console -applications can use different character sets (codepages) for drawing -characters. The first setting, called "ansi", is the default. -This character set contains various forms of latin characters used -in European languages. The name originates from the ANSI Latin1 -(ISO 8859-1) standard, used in Windows 1.0, though the character -sets have since diverged from any standard. The second setting -selects an older, DOS-based character set, containing various line -drawing and special characters. It is called "oem" since it was -originally encoded in the firmware of IBM PCs by original -equipment manufacturers (OEMs). If you find that some characters -(especially non-US or 'graphical' ones) do not display correctly in -Cygwin, you can use this option to select an appropriate codepage. - +codepage:[ansi|oem|utf8] - This option controls +which single- or multibyte character set is used for file and console +operations. Windows is using UTF-16 characters internally and this +option specifies how 8-byte character sets are converted to UTF-16 and +vice versa. The default setting is ansi which means, +conversion is based on the current ANSI codepage, typically 1252 in +many Western language versions of Windows. The name originates from the +ANSI Latin1 (ISO 8859-1) standard, used in Windows 1.0, though the +character sets have since diverged from any standard. The second +setting selects an older, DOS-based character set, containing various +line drawing and special characters. It is called oem +since it was originally encoded in the firmware of IBM PCs by original +equipment manufacturers (OEMs). +If you find that some characters (especially non-US or 'graphical' ones) +do not display correctly in Cygwin, you can use this option to select an +appropriate codepage. Finally, utf8 treats all file names +and console characters as UTF-8 chars. Please note that, for correct +operation, you have to set the environment variable LC_CTYPE to "C-UTF-8" +for the time being. The reason is that newlib's multibyte conversion +functions require this setting. @@ -77,16 +57,18 @@ path name. Defaults to set. (no)envcache - If set, environment variable -conversions (between Win32 and POSIX) are cached. Note that this is may +conversions (between Win32 and POSIX) are cached. Note that this may cause problems if the mount table changes, as the cache is not invalidated and may contain values that depend on the previous mount table contents. Defaults to set. + (no)export - If set, the final values of these settings are re-exported to the environment as CYGWIN again. Defaults to off. + error_start:Win32filepath - if set, runs @@ -98,6 +80,7 @@ usually set to the path to gdb or There is no default set. + forkchunk:32768 - causes the fork() to copy memory some number of bytes at a time, in the above example @@ -106,12 +89,14 @@ possible, which is preferable in most cases but may slow some older systems down. + proc_retry:n - causes the fork() and exec*() to retry n times when a child process fails due to certain windows-specific errors. These errors usually occur when processes are being started while a user is logging off. + (no)glob[:ignorecase] - if set, command line arguments containing UNIX-style file wildcard characters (brackets, question mark, @@ -122,40 +107,13 @@ Default is set. This option also accepts an optional [no]ignorecase modifer. If supplied, wildcard matching is case insensitive. The default is noignorecase - -(no)ntea - if set, use NT Extended Attributes to -store UNIX-like inode information. -This option only operates under Windows NT. Defaults to not set. -Only FAT and NTFS support Extended Attributes, not FAT32, so it's -of no use there. Furthermore, on NTFS partitions ntsec, which provides -real permissions, overrides ntea, which only provides faked permissions. -So setting ntea only makes sense if you either have FAT partitions, -or if you switch off ntsec explicitely. -Warning! This may create additional -large files on FAT partitions. - - -(no)ntsec - if set, use the NT security -model to set UNIX-like permissions on files and processes. The -file permissions can only be set on NTFS partitions. FAT/FAT32 don't -support the NT file security. Defaults to set. For more information, read -the documentation in . - - -(no)smbntsec - if set, use ntsec on remote -drives as well (default is "nosmbntesc"). When setting "smbntsec" there's -a chance that you get problems with Samba shares so you should use this -option with care. One reason for a non working ntsec on -remote drives could be insufficient permissions of the users. The requires -user rights are somewhat dangerous (SeRestorePrivilege), so it's not always -an option to grant that rights to users. However, this shouldn't be a -problem in NT domain environments. - + (no)reset_com - if set, serial ports are reset to 9600-8-N-1 with no flow control when used. This is done at open time and when handles are inherited. Defaults to set. + (no)server - if set, allows client applications to use the Cygserver facilities. This option must be enabled explicitely @@ -166,18 +124,18 @@ successfully. These function calls will return with ENOSYS, "Bad system call". + (no)strip_title - if set, strips the directory part off the window title, if any. Default is not set. + (no)title - if set, the title bar reflects the name of the program currently running. Default is not -set. Note that under Win9x the title bar is always enabled and it is -stripped by default, but this is because of the way Win9x works. In -order not to strip, specify title or title -nostrip_title. +set. + (no)tty - if set, Cygwin enables extra support (i.e., termios) for UNIX-like ttys in the Windows console. @@ -190,11 +148,65 @@ and it cannot be changed in the shell. It should not be set when using other terminals (i.e., rxvt or xterm). + (no)winsymlinks - if set, Cygwin creates symlinks as Windows shortcuts with a special header and the R/O attribute set. If not set, Cygwin creates symlinks as plain files with a magic number, -a path and the system attribute set. Defaults to set. +a path and the system attribute set. Defaults to not set since plain +file symlinks are faster to write and faster to read. + + + + +Removed options + + +Some CYGWIN options have been removed in Cygwin 1.7 for one reason or another. +These removed options are listed below. + + + +check_case - This option has been removed in favor of +real case sensitivity and the per-mount option "posix=[0|1]". For more +information, read the documentation in and +. + + + +(no)ntea - This option has been removed since it +only fakes security which is considered dangerous and useless. It also +created an uncontrollably large file on FAT and was entirely useless +on FAT32. + + + +(no)ntsec - This option has been removed in favor of +the per-mount option "acl"/"noacl". For more information, read the +documentation in . + + + +(no)smbntsec - This option has been removed in favor of +the per-mount option "acl"/"noacl". For more information, read the +documentation in . + + + +(no)transparent_exe - This option has been removed +because the behaviour it switched on is now the standard behaviour in +Cygwin. + + + +(no)traverse - This option has been removed because +traverse checking is not quite correctly implemented by Microsoft and +it's behaviour is getting worse with each new OS version. + + + + + diff --git a/winsup/doc/effectively.sgml b/winsup/doc/effectively.sgml index 6a9e95263..b1e38c35c 100644 --- a/winsup/doc/effectively.sgml +++ b/winsup/doc/effectively.sgml @@ -18,23 +18,27 @@ support the /? switch to display usage information. Unfortunately, no standard set of tools included with all versions of Windows exists. If you are unfamiliar with the tools available -on your system, here is a general guide. Windows 95, 98, and ME have -very limited command-line configuration tools. Windows NT 4.0 has much -better coverage, which Windows 2000 and XP expanded. +on your system, here is a general guide. Windows NT 4.0 has only a basic +set of tools, which later versions of Windows expanded. Microsoft also provides free downloads for Windows NT 4.0 (the Resource Kit Support Tools), Windows 2000 (the Resource Kit Tools), and XP (the -Windows Support Tools). Additionally, many independent sites such as -download.com, +Windows Support Tools). Generally, the younger the Windows version, the +more complete are the on-board tools. Additionally, many independent sites +such as +download.com, simtel.net, -and sysinternals.com -provide command-line utilities. A few Windows tools, such as -find.exe and sort.exe, -may conflict with the Cygwin versions; make sure that you use the full -path (/usr/bin/find) or that your Cygwin -bin directory comes first in your PATH. +and Microsoft's own +Sysinternals +provide quite useful command-line utilities, as far as they are not +already provided by Cygwin. A few Windows tools, such as +find.exe, link.exe and +sort.exe, may conflict with the Cygwin versions +make sure that you use the full path (/usr/bin/find) +or that your Cygwin bin directory comes first in your +PATH. - Pathnames + Pathnames Windows programs do not understand POSIX pathnames, so any arguments @@ -60,15 +64,15 @@ preferable to use cygpath in shell scripts. - Console Programs + Console Programs Another issue is receiving output from or giving input to console-based Windows programs. Unfortunately, interacting with Windows console applications is not a simple matter of using a translation utility. Windows -console applications are designed to run under command.com -or cmd.exe, and some do not deal gracefully with other +console applications are designed to run under +cmd.exe, and some do not deal gracefully with other situations. Cygwin can receive console input only if it -is also running in a console (DOS box) since Windows does not provide +is also running in a console window since Windows does not provide any way to attach to the backend of the console device. Another traditional Unix input/output method, ptys (pseudo-terminals), is supported by Cygwin but not entirely by Windows. The basic problem is @@ -78,7 +82,7 @@ having their input or output redirected to pipes. To help deal with these issues, Cygwin supports customizable levels of -Windows verses Unix compatibility behavior. To be most compatible with +Windows versus Unix compatibility behavior. To be most compatible with Windows programs, use a DOS prompt, running only the occasional Cygwin command or script. Next would be to run bash within a default DOS box. To make Cygwin more Unix compatible in this case, @@ -92,7 +96,7 @@ but expect some compatibility problems with Windows programs. - Cygwin and Windows Networking + Cygwin and Windows Networking Many popular Cygwin packages, such as ncftp, lynx, and wget, require a @@ -111,11 +115,11 @@ of these programs, see if the alternate one works as expected. There are a variety of other programs available for specific situations. If your system does not have an always-on network connection, you -may be interested in rasdial.exe (or alternatives for -Windows 95, 98, and ME) for automating dialup connections. +may be interested in rasdial.exe for automating dialup +connections. Users who frequently change their network configuration can script these changes with netsh.exe -(Windows 2000 and XP). For proxy users, the open source +(Windows 2000 and later). For proxy users, the open source NTLM Authorization Proxy Server or the no-charge @@ -125,15 +129,15 @@ programs in your environment. -The cygutils package +The cygutils package -The optional cygutils package contains miscellaneous tools that are -small enough to not require their own package. It is not included in a -default Cygwin install; select it from the Utils category in -setup.exe. Several of the cygutils tools are useful -for interacting with Windows. - +The optional cygutils package contains +miscellaneous tools that are small enough to not require their own package. +It is not included in a default Cygwin install; select it from the Utils +category in setup.exe. Several of the +cygutils tools are useful for interacting with +Windows. One of the hassles of Unix-Windows interoperability is the different line @@ -146,7 +150,7 @@ endings, but cygutils provides several dedicated progra -Creating shortcuts with cygutils +Creating shortcuts with cygutils Another problem area is between Unix-style links, which link one file to another, and Microsoft .lnk files, which provide a shortcut to a @@ -172,7 +176,7 @@ Windows shortcuts. -Printing with cygutils +Printing with cygutils There are several options for printing from Cygwin, including the lpr found in cygutils (not to be confused with the diff --git a/winsup/doc/filemodes.sgml b/winsup/doc/filemodes.sgml index 5f34aac84..2a644db51 100644 --- a/winsup/doc/filemodes.sgml +++ b/winsup/doc/filemodes.sgml @@ -1,34 +1,33 @@ File permissions -On Windows 9x systems, files are always readable, and Cygwin uses the -native read-only mode to determine if they are writable. Files are +On FAT or FAT32 filesystems, files are always readable, and Cygwin +uses the DOS read-only attribute to determine if they are writable. Files are considered to be executable if the filename ends with .bat, .com or .exe, or if its content starts with #!. Consequently chmod can only affect the "w" mode, it silently ignores actions involving the other modes. This means that ls -l needs to open and read files. It can thus be relatively slow. -Under NT, file permissions default to the same behavior as Windows -9x but there is optional functionality in Cygwin that can make file -systems behave more like on UNIX systems. This is turned on by adding -the "ntea" option to the CYGWIN environment variable. - -When the "ntea" feature is activated, Cygwin will start with basic -permissions as determined above, but can store POSIX file permissions in NT -Extended Attributes. This feature works quite well on NTFS partitions -because the attributes can be stored sensibly inside the normal NTFS -filesystem structure. However, on a FAT partition, NT stores extended -attributes in a flat file at the root of the partition called EA -DATA. SF. This file can grow to extremely large sizes if you -have a large number of files on the partition in question, slowing the -system to a crawl. In addition, the EA DATA. SF file -can only be deleted outside of Windows because of its "in use" status. For -these reasons, the use of NT Extended Attributes is off by default in -Cygwin. Finally, note that specifying "ntea" in CYGWIN has no -effect under Windows 9x. - -Under NT, the test "[ -w filename]" is only true if filename is -writable across the board, e.g. chmod +w filename. +On NTFS, file permissions are evaluated using the Access Control +Lists (ACLs) attached to a file. This can be switched off by using the +"noacl" option to the respective mount point in the +/etc/fstab or /etc/fstab.d/$USER +file. For more information on file permissions, see + + + +. + + + + +On NFS shares, file permissions are exactly the POSIX permissions +transmitted from the server using the NFSv3 protocol, if the NFS client +is the one from Microsoft's "Services For Unix", or the one built into +Windows Vista or later. + + +Only the user and group ownership is not necessarily correct. diff --git a/winsup/doc/gcc.sgml b/winsup/doc/gcc.sgml index f1d5431b7..60202d949 100644 --- a/winsup/doc/gcc.sgml +++ b/winsup/doc/gcc.sgml @@ -6,7 +6,7 @@ Refer to the GCC User's Guide for information on standard usage and options. Here's a simple example: - + Building Hello World with GCC C:\> gcc hello.c -o hello.exe diff --git a/winsup/doc/gdb.sgml b/winsup/doc/gdb.sgml index 732004f49..1b26599c7 100644 --- a/winsup/doc/gdb.sgml +++ b/winsup/doc/gdb.sgml @@ -18,7 +18,7 @@ program for debugging. What you need to do is add -g to all the other flags you use when compiling your sources to objects. -Compiling with -g +Compiling with -g $ gcc -g -O2 -c myapp.c $ gcc -g myapp.c -o myapp @@ -57,7 +57,7 @@ at individual variables or what pointers point to. break command to tell gdb to stop your program when it gets to a specific function or line number: -"break" in gdb +"break" in gdb (gdb) break my_function (gdb) break 47 @@ -75,7 +75,7 @@ time. your program. These two cases are the same as far as your program is concerned: -Debugging with command line arguments +Debugging with command line arguments $ myprog -t foo --queue 47 diff --git a/winsup/doc/legal.sgml b/winsup/doc/legal.sgml index aad3edf7c..80f404670 100644 --- a/winsup/doc/legal.sgml +++ b/winsup/doc/legal.sgml @@ -1,6 +1,6 @@ -Copyright © 1998, 1999, 2000, 2001, 2002, 2003, 2004, 2005, 2006, 2007 Red Hat, Inc. +Copyright © 1998, 1999, 2000, 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008 Red Hat, Inc. -The two important types of ACEs are the `access allowed ACE' and the -`access denied ACE'. The ntsec functionality only used `access allowed ACEs' up -to Cygwin version 1.1.0. Later versions also use `access denied ACEs' -to reflect the UNIX permissions as well as possible. +The two (for us) important types of ACEs are the "access allowed +ACE" and the "access denied ACE". As the names imply, the allow ACE +tells the system to allow the given permissions to the SID, the deny ACE +results in denying the specific permission bits. The possible permissions on objects are more detailed than in -UNIX. For example, the permission to delete an object is different -from the write permission. - -With the aforementioned method NT is able to grant or revoke permissions -to objects in a far more specific way. But what about cygwin? In a POSIX -environment it would be fine to have the security behavior of a POSIX -system. The NT security model is MOSTLY able to reproduce the POSIX model. -The ntsec method tries to do this in cygwin. - -You ask "Mostly? Why mostly???" Because there's a leak in the NT model. -I will describe that in detail in chapter 5. - -Creating explicit object security is not that easy so you will often -see only two simple variations in use: - - -default permissions, computed by the operating system -each permission to everyone - - -For parameters to functions that create or open securable objects another -data structure is used, the `security attributes' (SA). This structure -contains an SD and a flag that specifies whether the returned handle -to the object is inherited to child processes or not. -This property is not important for ntsec so in -this document the difference between SDs and SAs is ignored. - - - -Process privileges - -Any process started under control of Cygwin has a semaphore attached -to it, that is used for signaling purposes. The creation of this semaphore -can be found in sigproc.cc, function `getsem'. The first parameter to the -function call `CreateSemaphore' is an SA. Without ntsec this SA -assigns default security to the semaphore. There is a simple disadvantage: -Only the owner of the process may send signals to it. Or, in other words, -if the owner of the process is not a member of the administrators' group, -no administrator may kill the process! This is especially annoying, if -processes are started via service manager. - -Ntsec now assigns an SA to the process control semaphore, that -has each permission set for the user of the process, for the -administrators' group and for `system', which is a synonym for the -operating system itself. The creation of this SA is done by the function -`sec_user', that can be found in `shared.cc'. Each member of the -administrators' group is now allowed to send signals to any process -created in Cygwin, regardless of the process owner. - -Moreover, each process now has the appropriate security settings, when -it is started via `CreateProcess'. You will find this in function -`spawn_guts' in module `spawn.cc'. The security settings for starting a -process in another user context have to add the SID of the new user, too. -In the case of the `CreateProcessAsUser' call, sec_user creates an SA with -an additional entry for the sid of the new user. +POSIX. For example, the permission to delete an object is different +from the permission to change object data, and even changing object data +can be separated into different permission bits for different kind of +data. File permissions -If ntsec is turned on, file permissions are set as in UNIX. An SD is -assigned to the file containing the owner and group and ACEs for the -owner, the group and `Everyone'. +On NTFS and if the noacl mount option is not +specified for a mount point, Cygwin sets file permissions as in POSIX. +Basically this is done by defining a SD with the matching owner and group +SIDs, and a DACL which contains ACEs for the owner, the group and for +"Everyone", which represents what POSIX calls "others". -The complete settings of UNIX like permissions can be found in the file -`security.cc'. The two functions `get_nt_attribute' and `set_nt_attribute' -are the main code. The reading and writing of the SDs is done by the -functions `read_sd' and `write_sd'. `write_sd' uses the function `BackupRead' -instead of the simpler function `SetFileSecurity' because the latter is -unable to set owners different from the caller. +To use NT security correctly, Cygwin depends on the files +/etc/passwd and /etc/group. +These files define the traslation between the Cygwin uid/gid and the +Windows SID. The SID is stored in the pw_gecos field in +/etc/passwd, and in the gr_passwd field in +/etc/group. Since the pw_gecos field can contain +more information than just a SID, there are some rules for the layout. +It's required that the SID is the last entry of the pw_gecos field, +assuming that the entries in pw_gecos are comma-separated. The +commands mkpasswd and mkgroup +usually do this for you. + +Another interesting entry in the pw_gecos field (which is also +usually created by running mkpasswd) is the Windows user +name entry. It takes the form "U-domain\username" and is typically used +by services to authenticate a user. Logging in through ssh +or telnet are two typical scenarios. + -If you are creating a file `foo' outside of Cygwin, you will see something -like the following on ls -ln: +A typical snippet from /etc/passwd: -If your login is member of the administrators' group: - - rwxrwxrwx 1 544 513 ... foo - -if not: + +/etc/passwd: - rwxrwxrwx 1 1000 513 ... foo +SYSTEM:*:18:544:,S-1-5-18:: +Administrators:*:544:544:,S-1-5-32-544:: +Administrator:unused:500:513:U-FOO\Administrator,S-1-5-21-790525478-115176313-839522115-500:/home/Administrator:/bin/bash +corinna:unused:11001:11125:U-BAR\corinna,S-1-5-21-2913048732-1697188782-3448811101-1001:/home/corinna:/bin/tcsh + -Note the user and group IDs. 544 is the UID of the administrators' group. -This is a `feature' :-P of WinNT. If you are a member of -the administrators' group, every file that you create is owned by the -administrators' group, instead of by you. - -The second example shows the UID of the first user, that has been -created with NT's the user administration tool. The users and groups are -sequentially numbered, starting with 1000. Users and groups are using the -same numbering scheme, so a user and a group don't share the same ID. - -In both examples the GID 513 is of special interest. This GID is a -well known group with different naming in local systems and domains. -Outside of domains the group is named 'None' (`Kein' in German, `Aucun' -in French, etc.), in domains it is named 'Domain Users'. Unfortunately, -the group `None' is never shown in the user admin tool outside of domains! -This is very confusing but this seems to have no negative consequences. - -To work correctly, ntsec depends on the files -/etc/passwd and /etc/group. -In Cygwin release 1.0 the names and the IDs must correspond to the -appropriate NT IDs! The IDs used in Cygwin are the RID of the NT SID, as -mentioned earlier. -A SID of e.g. the user `corinna' on my NT workstation: - - - S-1-5-21-165875785-1005667432-441284377-1000 +The SYSTEM entry is usually needed by services. The Administrators +entry (Huh? A group in /etc/passwd?) is only here to allow +ls to print some file ownerships correctly. Windows +doesn't care if the owner of a file is a user or a group. In older +versions of Windows NT the default ownership for files created by an +administrator account was set to the group Administrators instead of to +the creating user account. This has changed, but for those older +systems it's convenient to have the Administrators group in +/etc/passwd. + +The really interesting entries are the next two. The Administrator +entry is for the local administrator, the corinna entry matches the corinna +account in the domain BAR. The information given in the pw_gecos field +are all we need to exactly identify an account, and to have a two way +translation, from Windows account name/SID to Cygwin account name uid and +vice versa. Having this complete information allows us to choose a Cygwin +name and uid which doesn't have to match the Windows account at all. As +long as the pw_gecos information is available, we're on the safe side: + + +/etc/passwd, tweaked: + +root:unused:0:513:U-FOO\Administrator,S-1-5-21-790525478-115176313-839522115-500:/home/Administrator:/bin/bash +thursday_next:unused:11001:11125:U-BAR\corinna,S-1-5-21-2913048732-1697188782-3448811101-1001:/home/corinna:/bin/tcsh + -Note the last number: It's the RID 1000, Cygwin's UID. - -Unfortunately, workstations and servers outside of domains are not -able to set primary groups! In these cases, where there is no correlation -of users to primary groups, NT returns 513 (None) as primary group, -regardless of the membership to existing local groups. - -When using mkpasswd -l -g on such systems, you -have to change the primary group by hand if `None' as primary group is -not what you want (and I'm sure, it's not what you want!) + The above /etc/passwd will still work fine. +You can now login via ssh as the user "root", and +Cygwin dutyfully translates "root" into the Windows user +"FOO\Administrators" and files owned by FOO\Administrators are shown to +have the uid 0 when calling ls -ln. All you do you're +actually doing as Administrator. Files created as root will be owned by +FOO\Administrator. And the domain user BAR\corinna can now happily +pretend to be Thursday Next, but will wake up sooner or later finding +out she's still actually the domain user BAR\corinna... -Look at the following examples, which were parts of my files before -storing SIDs in /etc/passwd and /etc/group had been introduced (See next -chapter for details). With the exception of my personal user entry, all -entries are well known entries. +Do I have to mention that you can also rename groups in +/etc/group? As long as the SID is present and correct, +all is well. This allows for instance to rename the "Administrators" group +to "root" as well: - -/etc/passwd + +/etc/group, tweaked: -everyone:*:0:0::: -system:*:18:18::: -administrator::500:544::/home/root:/bin/bash -guest:*:501:546::: -administrators:*:544:544::/home/root: -corinna::1000:547:Corinna Vinschen:/home/corinna:/bin/tcsh +root:S-1-5-32-544:544: - -/etc/group - -everyone::0: -system::18: -none::513: -administrators::544: -users::545: -guests::546: -powerusers::547: - - +Last but not least you can also change the primary group of a user +in /etc/passwd. The only requirement is that the user +is actually a member of the new primary group in Windows. For instance, +normal users in a domain environment are members in the group "Domain Users", +which in turn is member of the well-known group "Users". Additionally let's +assume the user is also a member of the newly created group . The default +primary group for users is + + + + As you can see, I changed my primary group membership from 513 (None) to 547 (powerusers). So all files I created inside of Cygwin were now owned @@ -330,14 +309,6 @@ processes, which are started through service manager. NT SIDs in Cygwin -In Cygwin release 1.1 a new technique of using the -/etc/passwd and /etc/group - was introduced. - -Both files may now contain SIDs of users and groups. They -are saved in the last field of pw_gecos in /etc/passwd -and in the gr_passwd field in /etc/group. - This has the following advantages: ntsec works better in domain environments. @@ -378,14 +349,14 @@ root::500:513::/home/root:/bin/sh As in U*X systems UIDs and GIDs numbering scheme now don't influence each other. So it's possible to have same Id's for a user and a group: - + /etc/passwd: root::0:0:S-1-5-21-54355234-56236534-345635656-500:/home/root:/bin/sh - + /etc/group: root:S-1-5-32-544:0: @@ -402,14 +373,6 @@ not to do this since ntsec works better when having the SIDs available. Please note that the pw_gecos field in /etc/passwd is defined as a comma separated list. The SID has to be the last field! -As aforementioned you are able to use Cygwin account names different -from the NT account names. If you want to login through `telnet' or something -else you have to use the special login. You may then -add another field to pw_gecos which contains the NT user name including -it's domain. So you are able to login as each domain user. The syntax -is easy: Just add an entry of the form U-ntdomain\ntusername to the pw_gecos -field. Note that the SID must still remain the last field in pw_gecos! - the_king::1:1:Elvis Presley,U-STILLHERE\elvis,S-1-5-21-1234-5678-9012-1000:/bin/sh @@ -429,7 +392,7 @@ examples. Please note that I've changed these files heavily! There's no need to change them that way, it's just for testing purposes and... for fun. - + /etc/passwd root:*:0:0:Administrators group,S-1-5-32-544:: @@ -440,7 +403,7 @@ Guest:*:501:546:,S-1-5-21-1844237615-436374069-1060284298-501:/home/Guest:/bin/b - + /etc/group root:S-1-5-32-544:0: @@ -593,7 +556,7 @@ found on http://docs.sun.com New setuid concept -UNIX applications which have to switch the user context are using +POSIX applications which have to switch the user context are using the setuid and seteuid calls which are not part of the Windows API. Nevertheless these calls are supported under Windows NT/W2K since Cygwin diff --git a/winsup/doc/overview.sgml b/winsup/doc/overview.sgml index 6e38832e8..b0b80b549 100644 --- a/winsup/doc/overview.sgml +++ b/winsup/doc/overview.sgml @@ -5,17 +5,15 @@ Cygwin is a Linux-like environment for Windows. It consists of a DLL (cygwin1.dll), which acts as an emulation layer -providing substantial POSIX (Portable Operating -System Interface) system call functionality, and a collection of tools, -which provide a Linux look and feel. The Cygwin DLL works with all x86 -versions of Windows since Windows 95. The API follows the Single +providing substantial POSIX +(Portable Operating System Interface) system call functionality, and a +collection of tools, which provide a Linux look and feel. The Cygwin DLL +works with all x86 and AMD64 versions of Windows NT since Windows NT 4. +The API follows the +Single Unix Specification as much as possible, and then Linux practice. -Two other major differences between Cygwin and Linux are the C library -(newlib instead of glibc) and -default /bin/sh, which is ash on -Cygwin but bash on most Linux distributions. +The major differences between Cygwin and Linux is the C library +(newlib instead of glibc). With Cygwin installed, users have access to many standard UNIX @@ -48,8 +46,8 @@ information on how the GNU GPL may affect your use of these tools. If you intend to port a proprietary application using the Cygwin library, you may want the Cygwin proprietary-use license. For more information about the proprietary-use license, please go to -http://www.redhat.com/software/tools/cygwin/ -. Customers of the native Win32 GNUPro should feel free to submit bug +http://www.redhat.com/software/tools/cygwin/. +Customers of the native Win32 GNUPro should feel free to submit bug reports and ask questions through the normal channels. All other questions should be sent to the project mailing list cygwin@cygwin.com. @@ -60,9 +58,9 @@ questions should be sent to the project mailing list -A more complete historical look Cygwin is Geoffrey J. Noer's 1998 paper, -"Cygwin32: A Free Win32 Porting Layer for UNIX® Applications" which can be -found at the 2nd USENIX Windows NT Symposium Online Proceedings. @@ -108,6 +106,14 @@ New Cygwin Net Release which provided the native Win32 program separately. Since then, the Cygwin DLL and setup.exe have seen continuous development. + + +The latest major improvement in this development is the 1.7 release in +2008, which dropped Windows 95/98/Me support in favor of using Windows +NT features more extensively. It adds a lot of new features like +case-sensitive filenames, NFS interoperability, IPv6 support and much +more. + DOCTOOL-INSERT-highlights diff --git a/winsup/doc/overview2.sgml b/winsup/doc/overview2.sgml index 0d7be896b..7cdc3e889 100644 --- a/winsup/doc/overview2.sgml +++ b/winsup/doc/overview2.sgml @@ -33,11 +33,11 @@ After installation, you can find Cygwin-specific documentation in the /usr/share/doc/Cygwin/ directory. -Developers coming from a Windows background will find a set of tools capable of -writing console or GUI executables that rely on the Microsoft Win32 API. The -dlltool utility may be used to write Windows Dynamically -Linked Libraries (DLLs). The resource compiler windres is -also provided. +Developers coming from a Windows background will be able to write +console or GUI executables that rely on the Microsoft Win32 API instead +of Cygwin using the -mno-cygwin option to GCC. The -shared +option allows to write Windows Dynamically Linked Libraries (DLLs). The +resource compiler windres is also provided. @@ -75,7 +75,7 @@ Developers coming from a UNIX background will find a set of utilities they are already comfortable using, including a working UNIX shell. The compiler tools are the standard GNU compilers most people will have previously used under UNIX, only ported to the Windows host. Programmers wishing to port -UNIX software to Windows NT or 9x will find that the Cygwin library provides +UNIX software to Windows NT will find that the Cygwin library provides an easy way to port many UNIX packages, with only minimal source code changes. @@ -88,138 +88,148 @@ changes. against the library is executed, the Cygwin DLL is loaded into the application's text segment. Because we are trying to emulate a UNIX kernel which needs access to all processes running under it, the first Cygwin DLL to -run creates shared memory areas that other processes using separate instances -of the DLL can access. This is used to keep track of open file descriptors and -assist fork and exec, among other purposes. In addition to the shared memory -regions, every process also has a per_process structure that contains +run creates shared memory areas and global synchronization objects that other +processes using separate instances of the DLL can access. This is used to keep track of open file descriptors and to assist fork and exec, among other +purposes. Every process also has a per_process structure that contains information such as process id, user id, signal masks, and other similar process-specific information. -The DLL is implemented using the Win32 API, which allows it to run on all -Win32 hosts. Because processes run under the standard Win32 subsystem, they +The DLL is implemented as a standard DLL in the Win32 subsystem. Under +the hood it's using the Win32 API, as well as the native NT API, where +appropriate. + +Because processes run under the standard Win32 subsystem, they can access both the UNIX compatibility calls provided by Cygwin as well as any of the Win32 API calls. This gives the programmer complete flexibility in designing the structure of their program in terms of the APIs used. For example, they could write a Win32-specific GUI using Win32 API calls on top of a UNIX back-end that uses Cygwin. -Early on in the development process, we made the important design -decision that it would not be necessary to strictly adhere to existing UNIX -standards like POSIX.1 if it was not possible or if it would significantly -diminish the usability of the tools on the Win32 platform. In many cases, an -environment variable can be set to override the default behavior and force -standards compliance. - +The native NT API is used mainly for speed, as well as to access +NT capabilities which are useful to implement certain POSIX features, but +are hidden to the Win32 API. + -Supporting both Windows NT and 9x -While Windows 95 and Windows 98 are similar enough to each other that we -can safely ignore the distinction when implementing Cygwin, Windows NT is an -extremely different operating system. For this reason, whenever the DLL is -loaded, the library checks which operating system is active so that it can act -accordingly. - -In some cases, the Win32 API is only different for -historical reasons. In this situation, the same basic functionality is -available under Windows 9x and NT but the method used to gain this -functionality differs. A trivial example: in our implementation of -uname, the library examines the sysinfo.dwProcessorType structure -member to figure out the processor type under Windows 9x. This field -is not supported in NT, which has its own operating system-specific -structure member called sysinfo.wProcessorLevel. - -Other differences between NT and 9x are much more fundamental in -nature. The best example is that only NT provides a security model. +Due to some restrictions in Windows, it's not always possible +to strictly adhere to existing UNIX standards like POSIX.1. Fortunately +these are mostely border cases. Permissions and Security Windows NT includes a sophisticated security model based on Access -Control Lists (ACLs). Cygwin maps Win32 file ownership and permissions to the -more standard, older UNIX model by default. Cygwin version 1.1 introduces -support for ACLs according to the system calls used on newer versions of -Solaris. This ability is used when the `ntsec' feature is switched on which -is described in . -The chmod call maps UNIX-style permissions -back to the Win32 equivalents. Because many programs expect to be able to find -the /etc/passwd and /etc/group files, we provide utilities +Control Lists (ACLs). Cygwin maps Win32 file ownership and permissions to +ACLs by default, on file systems supporting them (usually NTFS). Solaris +style ACLs and accompanying function calls are also supported. +The chmod call maps UNIX-style permissions back to the Win32 equivalents. +Because many programs expect to be able to find the +/etc/passwd and +/etc/group files, we provide utilities that can be used to construct them from the user and group information provided by the operating system. -Under Windows NT, users with Administrator rights are permitted to -chown files. With version 1.1.3 Cygwin introduced a mechanism for setting real -and effective UIDs under Windows NT/W2K. This is described in -. As of version 1.5.13, the Cygwin developers -are not aware of any feature in the Cygwin DLL that would allow users to gain -privileges or to access objects to which they have no rights under Windows. -However there is no guarantee that Cygwin is as secure as the Windows it runs -on. Cygwin processes share some variables and are thus easier targets of -denial of service type of attacks. +Users with Administrator rights are permitted to chown files. +With version 1.1.3 Cygwin introduced a mechanism for setting real and +effective UIDs. This is described in . As +of version 1.5.13, the Cygwin developers are not aware of any feature in +the Cygwin DLL that would allow users to gain privileges or to access +objects to which they have no rights under Windows. However there is no +guarantee that Cygwin is as secure as the Windows it runs on. Cygwin +processes share some variables and are thus easier targets of denial of +service type of attacks. -Under Windows 9x, the situation is considerably different. Since a -security model is not provided, Cygwin fakes file ownership by making all -files look like they are owned by a default user and group id. As under NT, -file permissions can still be determined by examining their read/write/execute -status. Rather than return an unimplemented error, under Windows 9x, the -chown call succeeds immediately without actually performing any action -whatsoever. This is appropriate since essentially all users jointly own the -files when no concept of file ownership exists. - File Access Cygwin supports -both Win32- and POSIX-style paths, using either forward or back slashes as the -directory delimiter. Paths coming into the DLL are translated from Win32 to -POSIX as needed. As a result, the library believes that the file system is a -POSIX-compliant one, translating paths back to Win32 paths whenever it calls a -Win32 API function. UNC pathnames (starting with two slashes) are -supported. - -The layout of this POSIX view of the Windows file system space is stored -in the Windows registry. While the slash ('/') directory points to the system -partition by default, this is easy to change with the Cygwin mount utility. -In addition to selecting the slash partition, it allows mounting arbitrary -Win32 paths into the POSIX file system space. Many people use the utility to -mount each drive letter under the slash partition (e.g. C:\ to /c, D:\ to /d, -etc...). +both POSIX- and Win32-style paths, using either forward or back slashes as the +directory delimiter. Paths coming into the DLL are translated from POSIX to +native NT as needed. From the application perspective, the file system is +a POSIX-compliant one. The implementation details are safely hidden in the +Cygwin DLL. UNC pathnames (starting with two slashes) are supported for +network paths. + +Since version 1.7.0, the layout of this POSIX view of the Windows file +system space is stored in the /etc/fstab file. Actually, +there is a system-wide /etc/fstab file as well as a +user-specific fstab file /etc/fstab.d/${USER}. + +At startup the DLL has to find out where it can find the +/etc/fstab file. The mechanism used for this is simple. +First it retrieves it's own path, for instance +C:\Cygwin\bin\cygwin1.dll. From there it deduces +that the root path is C:\Cygwin. So it looks for the +fstab file in C:\Cygwin\etc\fstab. +The layout of this file is very similar to the layout of the +fstab file on Linux. Just instead of block devices, +the mount points point to Win32 paths. An installation with +setup.exe installs a fstab file by +default, which can easily be changed using the editor of your choice. + +In addition to selecting the root partition, the +fstab file allows mounting arbitrary Win32 paths into +the POSIX file system space. A special case is the so-called cygdrive prefix. +It's the path under which every available drive in the system is mounted +under its drive letter. The default value is /cygdrive, +so you can access the drives as /cygdrive/c, +/cygdrive/d, etc... The cygdrive prefix can be set to +some other value (/mnt for instance) in the +fstab file(s). The library exports several Cygwin-specific functions that can be used by external programs to convert a path or path list from Win32 to POSIX or vice versa. Shell scripts and Makefiles cannot call these functions directly. -Instead, they can do the same path translations by executing the cygpath -utility program that we provide with Cygwin. - -Win32 file systems are case preserving but case insensitive. Cygwin -does not currently support case distinction because, in practice, few UNIX -programs actually rely on it. While we could mangle file names to support case -distinction, this would add unnecessary overhead to the library and make it -more difficult for non-Cygwin applications to access those files. - -Symbolic links are emulated by files containing a magic cookie followed -by the path to which the link points. They are marked with the System -attribute so that only files with that attribute have to be read to determine -whether or not the file is a symbolic link. Hard links are fully supported -under Windows NT on NTFS file systems. On a FAT file system, the call falls -back to simply copying the file, a strategy that works in many cases. - -The inode number for a file is calculated by hashing its full Win32 path. -The inode number generated by the stat call always matches the one returned in -d_ino of the dirent structure. It is worth noting that the number produced by -this method is not guaranteed to be unique. However, we have not found this to -be a significant problem because of the low probability of generating a -duplicate inode number. - -Chroot is supported since release 1.1.3. Note that chroot isn't -supported native by Windows. This implies some restrictions. First of all, -the chroot call isn't a privileged call. Each user may call it. Second, the -chroot environment isn't safe against native windows processes. If you -want to support a chroot environment as, for example, by allowing an -anonymous ftp with restricted access, you'll have to care that only -native Cygwin applications are accessible inside of the chroot environment. -Since that applications are only using the Cygwin POSIX API to access the -file system their access can be restricted as it is intended. This includes -not only POSIX paths but Win32 paths (containing drive letter and/or -backslashes) and CIFS paths (//server/share or \\server\share) as well. +Instead, they can do the same path translations by executing the +cygpath utility program that we provide with Cygwin. + +Win32 applications handle filenames case preserving but case +insensitive. Cygwin supports case sensitivity on file systems supporting +that. Since Windows XP, the OS only supports case sensitivity when a +specific registry value is changed. Therefore case sensitivity is not +the default usually. + +Symbolic links are not present and supported on Windows up to and +including Windows Server 2003 R2. Only starting with Windows Vista, +native symlinks are available. Unfortunately they are strangly implemented +and so not very useful for a POSIX emulation layer. Consequentially +Cygwin recognizes them as symlinks but does not create them. + +Symbolic links are potentially created in two different ways. +The file style symlinks are files containing a magic cookie followed by +the path to which the link points. They are marked with the System DOS +attribute so that only files with that attribute have to be read to +determine whether or not the file is a symbolic link. The shortcut style +symlinks are Windows shortcut files with a special header and the +Readonly DOS attribute set. The advantage of file symlinks is speed, +the advantage of shortcut symlinks is the fact that they can be utilized +by non-Cygwin Win32 tools as well. + +Hard links are fully supported on NTFS and NFS file systems. On FAT +and some other file systems, the call falls back to simply copying the file, +a strategy that works in many cases. + +On file systems which don't support unique persistent file IDs (FAT, +older Samba shares) the inode number for a file is calculated by hashing its +full Win32 path. The inode number generated by the stat call always matches +the one returned in d_ino of the dirent +structure. It is worth noting that the number produced by this method is not +guaranteed to be unique. However, we have not found this to be a significant +problem because of the low probability of generating a duplicate inode number. + + +chroot(2) is supported since Cygwin 1.1.3. +However, chroot is not a concept known by Windows. This implies some +restrictions. First of all, the chroot call isn't a +privileged call. Each user may call it. Second, the chroot environment +isn't safe against native windows processes. If you want to support a +chroot environment as, for example, by allowing an anonymous ftp with +restricted access, you'll have to care that only native Cygwin applications +are accessible inside of the chroot environment. Since those applications +are only using the Cygwin POSIX API to access the file system their access +can be restricted as it is intended. This includes not only POSIX paths but +Win32 paths containing drive letter and/or backslashes as well as UNC paths +(//server/share or \\server\share). + Text Mode vs. Binary Mode @@ -246,7 +256,9 @@ set to override this behavior. "newlib" as part of the library, rather than write all of the lib C and math calls from scratch. Newlib is a BSD-derived ANSI C library, previously only used by cross-compilers for embedded systems -development. +development. Other functions, which are not supported by newlib have +been added to the Cygwin sources using BSD implementations as much as +possible. The reuse of existing free implementations of such things as the glob, regexp, and getopt libraries saved us considerable @@ -258,8 +270,8 @@ malloc if it so desires. Process Creation -The fork call in Cygwin is particularly interesting because it -does not map well on top of the Win32 API. This makes it very +The fork call in Cygwin is particularly interesting +because it does not map well on top of the Win32 API. This makes it very difficult to implement correctly. Currently, the Cygwin fork is a non-copy-on-write implementation similar to what was present in early flavors of UNIX. @@ -335,26 +347,43 @@ it. Sockets -Socket-related calls in Cygwin simply -call the functions by the same name in Winsock, Microsoft's -implementation of Berkeley sockets. Only a few changes were needed to -match the expected UNIX semantics - one of the most troublesome -differences was that Winsock must be initialized before the first -socket function is called. As a result, Cygwin has to perform this -initialization when appropriate. In order to support sockets across -fork calls, child processes initialize Winsock if any inherited file -descriptor is a socket. - -Unfortunately, implicitly loading DLLs -at process startup is usually a slow affair. Because many processes -do not use sockets, Cygwin explicitly loads the Winsock DLL the -first time it calls the Winsock initialization routine. This single -change sped up GNU configure times by thirty -percent. +Socket-related calls in Cygwin basically call the functions by the +same name in Winsock, Microsoft's implementation of Berkeley sockets, but +with lots of tweaks. All sockets are non-blocking under the hood to allow +to interrupt blocking calls by POSIX signals. Additional bookkeeping is +necessary to implement correct socket sharing POSIX semantics and especially +for the select call. Some socket-related functions are not implemented at +all in Winsock, as, for example, socketpair. Starting with Windows Vista, +Microsoft removed the legacy calls rcmd(3), +rexec(3) and rresvport(3). +Recent versions of Cygwin now implement all these calls internally. + +An especially troublesome feature of Winsock is that it must be +initialized before the first socket function is called. As a result, Cygwin +has to perform this initialization on the fly, as soon as the first +socket-related function is called by the application. In order to support +sockets across fork calls, child processes initialize Winsock if any +inherited file descriptor is a socket. + +AF_UNIX (AF_LOCAL) sockets are not available in Winsock. They are +implemented in Cygwin by using local AF_INET sockets instead. This is +completely transparent to the application. Cygwin's implementation also +supports the getpeereid BSD extension. A yet missing feature is +descriptor passing, though. + +Starting with release 1.7.0, Cygwin gets IPv6 support. However, this +depends on the availability of the Windows IPv6 stack. Up to Windows 2003, +the IPv6 stack is treated as "experimental" and it's not feature complete. +Full support is only available starting with Windows Vista and Windows Server +2008. The newly implemented getaddrinfo and +getnameinfo functions are not dependent on the OS, +though. Cygwin 1.7.0 adds replacement functions which implement the full +functionality for IPv4. + Select -The UNIX select function is another +The UNIX select function is another call that does not map cleanly on top of the Win32 API. Much to our dismay, we discovered that the Win32 select in Winsock only worked on socket handles. Our implementation allows select to function normally diff --git a/winsup/doc/pathnames.sgml b/winsup/doc/pathnames.sgml index 8dc55d7c2..403505295 100644 --- a/winsup/doc/pathnames.sgml +++ b/winsup/doc/pathnames.sgml @@ -1,6 +1,6 @@ Mapping path names -Introduction +Introduction Cygwin supports both Win32- and POSIX-style paths, where directory delimiters may be either forward or back slashes. UNC @@ -24,41 +24,112 @@ necessary. The Cygwin Mount Table -The mount 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 -mount utility is very similar to the old DOS -join, in that it makes your drive letters appear as -subdirectories somewhere else. - -The mapping is stored in the current user's Cygwin -mount table 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 privileges (Administrator privileges in Windows -NT). - -The current user's table is located under -"HKEY_CURRENT_USER/Software/Cygnus Solutions/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. The user mount table takes precedence over -the system-wide table if a path is mounted in both. This includes the -setting of the cygdrive prefix. - -The mount command can set the POSIX root -/ to any directory in the Windows file system. -In absence of such a mount, Cygwin maps / to the -root of the current Windows working directory (for example, -H:\ or \\computer\share). -Normally Cygwin's setup.exe creates the initial -mount point for the POSIX root. - +The /etc/fstab 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 /etc/fstab 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 /etc/fstab.d +and the name of the file is the Cygwin username of the user, as it's +stored in the /etc/passwd file. The content of the +user specifc file is identical to the system-wide +fstab file. + +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. + +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 '\040'. + +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'. + +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. + +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. + + + 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). + + +Note that nouser mount points are not overridable by a later call +to mount(2). This is only possible for user mount points. Mount points +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. + +The fifth and sixth field are ignored. They are +so far only specified to keep a Linux-like fstab file layout. + +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). + +Example entries: + + + + Just a normal mount point: + c:/foo /bar fat32 binary 0 0 + + + A mount point for a managed, textmode mount: + C:/foo /bar/baz ntfs text,managed 0 0 + + + A mount point for a Windows directory with spaces in it: + C:/Documents\040and\040Settings /docs ext3 binary 0 0 + + + A mount point for a remote directory: + //server/share/subdir /srv/subdir smbfs binary 0 0 + + + This is just a comment: + # This is just a comment + + + Set the cygdrive prefix to /mnt: + none /mnt cygdrive binary 0 0 + + Whenever Cygwin generates a Win32 path from a POSIX one, it uses the longest matching prefix in the mount table. Thus, if @@ -70,19 +141,14 @@ POSIX equivalent current directory. Otherwise, the handling of MS-DOS filenames bypasses the mount table. -Invoking mount 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 -/d. 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 /d mount is only visible -to the current user. +If you want to see the current set of mount points valid in your +session, you can invoking the Cygwin tool mount without +arguments: - + Displaying the current set of mount points -c:\> mount +bash-3.2$ mount f:\cygwin\bin on /usr/bin type system (binmode) f:\cygwin\lib on /usr/lib type system (binmode) f:\cygwin on / type system (binmode) @@ -94,9 +160,10 @@ e: on /cygdrive/e type user (binmode,noumount) You can also use the mount command to add new mount points, and the umount to delete -them. See and for more -information on how to use these utilities to set up your Cygwin POSIX -file system. +them. However, since they are only noted in memory, these mount +points will disappear as soon as your last Cygwin process ends. +See and for more +information. Whenever Cygwin cannot use any of the existing mounts to convert from a particular Win32 path to a POSIX one, Cygwin will @@ -105,19 +172,12 @@ path /cygdrive. For example, if Cygwin accesses Z:\foo and the Z drive is not currently in the mount table, then Z:\ would be automatically converted to /cygdrive/Z. The default -prefix of /cygdrive may be changed (see the - for more information). - -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 for more -information on text and binary modes. +prefix of /cygdrive may be changed in the fstab file +as outlined above. -Additional Path-related Information +Additional Path-related Information The cygpath program provides the ability to translate between Win32 and POSIX pathnames in shell scripts. See @@ -150,23 +210,113 @@ not by default, for example). Special filenames - DOS devices + +DOS devices -Windows filenames invalid under Windows are also invalid under -Cygwin. This means that base filenames such as +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 AUX, COM1, LPT1 or PRN (to name a few) -cannot be used in a regular Cygwin Windows or POSIX path, even with an -extension (prn.txt). However the special names can be -used as filename extensions (file.aux). You can use -the special names as you would under DOS, for example you can print on your -default printer with the command cat filename > PRN -(make sure to end with a Form Feed). +cannot be used in a native Win32 application, even with an +extension (prn.txt). Cygwin can handle files with +these names just fine. + + + + +Special characters in filenames + +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. + +Some characters are disallowed in filenames on Windows filesystems: + + + " * : < > ? | \ + + +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. + + + + +Case sensitive filenames + +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 Abc and +aBc. 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. + +If you really want case-sensitivity in Cygwin, you can switch it +on by setting the registry value + + +HKLM\SYSTEM\CurrentControlSet\Control\Session Manager\kernel\obcaseinsensitive + + +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. + + + +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. + + +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! + +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. + +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 attrib +or net. Here's an example how you can switch the +cygdrive prefix to case-insensitivity: + + +Example mount point to enforce case-insensitivity on cygdrive paths + +none /cygdrive cygdrive binary,posix=0 0 0 + + + +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. - POSIX devices + POSIX devices There is no need to create a POSIX /dev directory as Cygwin automatically simulates it internally. These devices cannot be seen with the command ls /dev/ @@ -177,67 +327,97 @@ If you want to be able to see all devices in url="http://cygwin.com/ml/cygwin/2004-03/txt00028.txt">create_devices.sh script. + -Cygwin supports the following devices commonly found on POSIX systems: -/dev/dsp, /dev/null, -/dev/zero, /dev/console, -/dev/tty, /dev/ttym, -/dev/ttyX, /dev/ttySX, -/dev/pipe, /dev/port, -/dev/ptmx, /dev/mem, -/dev/random, and /dev/urandom. -Some other POSIX devices, such as -/dev/kmem, are planned for development. -Cygwin also has several Windows-specific devices: -/dev/comX (the serial ports, starting with -COM1 which is the same as ttyS0), -/dev/conin (Windows CONIN$), -/dev/conout (Windows CONOUT$), -/dev/clipboard (the Windows clipboard, currently -text only), and /dev/windows (the Windows message -queue). +Cygwin supports the following character devices commonly found on POSIX systems: -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. - + +/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. -Up to Cygwin 1.3.3 the only way to access those devices was -to mount the Win32 device names to a POSIX device name but this usage -is discouraged since Cygwin 1.3.4 and only kept for backward compatibility. +/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. + + + +Cygwin also has several Windows-specific devices: + +/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. + + -Beginning with Cygwin 1.3.4, raw devices are accessible by Cygwin processes -using fixed POSIX device names. These fixed POSIX device names are generated -using a direct conversion from the POSIX namespace to the internal NT namespace. +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. +\device\cdrom0 and the first tape drive is \device\tape0. The mapping +to the POSIX /dev namespace is as follows: -The new fixed POSIX names are mapped to NT internal devices as -follows: - /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/scd0 \device\cdrom0 -/dev/scd1 \device\cdrom1 -... +/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) @@ -249,10 +429,10 @@ follows: [up to] -/dev/sdl \device\harddisk11\partition0 -/dev/sdl1 \device\harddisk11\partition1 +/dev/sddx \device\harddisk127\partition0 +/dev/sddx1 \device\harddisk127\partition1 ... -/dev/sdl15 \device\harddisk11\partition15 +/dev/sddx15 \device\harddisk127\partition15 @@ -261,32 +441,16 @@ links as they are created on Linux systems for convenience: -ln -s /dev/scd0 /dev/cdrom -ln -s /dev/nst0 /dev/tape +ln -s /dev/sr0 /dev/cdrom +ln -s /dev/nst0 /dev/tape ... - - -Note that you can't use the mount table to map from a fixed device name -to your own device name or to map from internal NT device name to -your own device name. Also using symbolic links to map from the internal -NT device name to your own device name will not do what you want. -The following three examples will not work as expected: - - - -mount -f -b /dev/nst0 /dev/tape # DOES NOT WORK -mount -f -b /device/tape0 /dev/tape # DOES NOT WORK -ln -s /device/tape0 /dev/tape # DOES NOT WORK - - - -The .exe extension +The .exe extension - Executable program filenames end with .exe +Win32 executable 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 @@ -319,18 +483,9 @@ Cygwin 1.5.19. It has been changed for consistency with the rest of Cygwin. filename. This allows many makefiles written for UNIX systems to work well under Cygwin. -Unfortunately, the install and -strip commands do distinguish between -filename and filename.exe. They -fail when working on a non-existing filename even if -filename.exe exists, thus breaking some makefiles. -This problem can be solved by writing install and -strip shell scripts to provide the extension ".exe" -when needed. - -The /proc filesystem +The /proc filesystem Cygwin, like Linux and other similar operating systems, supports the /proc virtual filesystem. The files in this @@ -344,7 +499,12 @@ is /proc/registry, which displays the Windows registry with each KEY as a directory and each VALUE as a file. As anytime you deal with the Windows registry, use caution since changes may result in an unstable -or broken system. +or broken system. There are additionally subdirectories called +/proc/registry32 and /proc/registry64. +They are identical to /proc/registry on 32 bit +host OSes. On 64 bit host OSes, /proc/registry32 +opens the 32 bit processes view on the registry, while +/proc/registry64 opens the 64 bit processes view. The Cygwin /proc is not as complete as the @@ -354,7 +514,7 @@ that use it. -The @pathnames +The @pathnames 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 @@ -366,7 +526,7 @@ Embedded double quotes must be repeated. In the following example compare the behaviors of the bash built-in echo and of the program /bin/echo. - Using @pathname + Using @pathname bash$ echo 'This is "a long" line' > mylist bash$ echo @mylist diff --git a/winsup/doc/setup-net.sgml b/winsup/doc/setup-net.sgml index c098c32ea..165924d07 100644 --- a/winsup/doc/setup-net.sgml +++ b/winsup/doc/setup-net.sgml @@ -35,7 +35,7 @@ to make use of other resources. -Download Source +Download Source Cygwin uses packages to manage installing various software. When the default Install from Internet option is chosen, @@ -69,7 +69,7 @@ this; search the list for mkcygwget for ideas. -Selecting an Install Directory +Selecting an Install Directory The Root Directory for Cygwin (default C:\cygwin) will become / @@ -97,7 +97,7 @@ have a very good reason to switch it to -Local Package Directory +Local Package Directory The Local Package Directory is the cache where setup.exe stores the packages before they are @@ -111,7 +111,7 @@ or in case you need to reinstall a package. -Connection Method +Connection Method The Direct Connection method of downloading will directly download the packages, while the IE5 method will leverage your @@ -124,7 +124,7 @@ authorization for proxy servers. -Choosing Mirrors +Choosing Mirrors Since there is no way of knowing from where you will be downloading Cygwin, you need to choose at least one mirror site. Cygwin mirrors @@ -137,7 +137,7 @@ mirror) you can add it. -Choosing Packages +Choosing Packages For each selected mirror site, setup.exe downloads a small text file called setup.bz2 that contains a list @@ -201,7 +201,7 @@ stable version. -Download and Installation Progress +Download and Installation Progress First, setup.exe will download all selected packages to the local directory chosen earlier. Before installing, @@ -212,7 +212,7 @@ show progress bars for the current task and total remaining disk space. -Icons +Icons You may choose to install shortcuts on the Desktop and/or Start Menu to start a bash shell. If you prefer to use a different @@ -221,7 +221,7 @@ use these shortcuts as a guide to creating your own. -Post-Install Scripts +Post-Install Scripts Last of all, setup.exe will run any post-install scripts to finish correctly setting up installed packages. Since each @@ -236,7 +236,7 @@ Relevant documentation can be found in the /usr/doc/Cygwin/ or /usr/share/doc/Cygwin/ directory. -Troubleshooting +Troubleshooting Unfortunately, the complex setup process means that odd problems can occur. If you're having trouble downloading packages, it may be network diff --git a/winsup/doc/setup2.sgml b/winsup/doc/setup2.sgml index bd1e8dec0..5bdfef989 100644 --- a/winsup/doc/setup2.sgml +++ b/winsup/doc/setup2.sgml @@ -23,20 +23,21 @@ DOS shell, before launching bash. The PATH environment variable is used by Cygwin applications as a list of directories to search for executable files to run. This environment variable is converted from Windows format -(e.g. C:\WinNT\system32;C:\WinNT) to UNIX format -(e.g., /WinNT/system32:/WinNT) when a Cygwin -process first starts. +(e.g. C:\Windows\system32;C:\Windows) to UNIX format +(e.g., /cygdrive/c/Windows/system32:/cygdrive/c/Windows) +when a Cygwin process first starts. Set it so that it contains at least the x:\cygwin\bin directory where "x:\cygwin is the "root" of your cygwin installation if you wish to use cygwin tools outside of bash. +This is usually done by the batch file you're starting your shell with. The HOME environment variable is used by many programs to determine the location of your home directory and we recommend that it be defined. This environment variable is also converted from Windows format -when a Cygwin process first starts. Set it to point to your home directory -before launching bash. +when a Cygwin process first starts. It's usually set in the shell +profile scripts in the /etc directory. @@ -79,8 +80,8 @@ when using regtool since damaging your system registry can result in an unusable system. This example sets memory limit to 1024 MB: -regtool -i set /HKLM/Software/Cygnus\ Solutions/Cygwin/heap_chunk_in_mb 1024 -regtool -v list /HKLM/Software/Cygnus\ Solutions/Cygwin +regtool -i set /HKLM/Software/Cygwin/heap_chunk_in_mb 1024 +regtool -v list /HKLM/Software/Cygwin @@ -121,6 +122,7 @@ gcc max_memory.c -o max_memory.exe Run the program and it will output the maximum amount of allocatable memory. + Customizing bash @@ -128,19 +130,19 @@ Run the program and it will output the maximum amount of allocatable memory. To set bash up so that cut and paste work properly, click on the "Properties" button of the window, then on the "Misc" tab. Make sure -that "Quick Edit" is checked and "Fast Pasting" isn't. These settings -will be remembered next time you run bash from that -shortcut. Similarly you can set the working directory inside the -"Program" tab. The entry "%HOME%" is valid. +that "QuickEdit mode" and "Insert mode" are checked. These settings +will be remembered next time you run bash from that shortcut. Similarly +you can set the working directory inside the "Program" tab. The entry +"%HOME%" is valid, but requires that you set HOME in +the Windows environment. Your home directory should contain three initialization files that control the behavior of bash. They are .profile, .bashrc and -.inputrc. These initialization files will only -be read if HOME is defined before starting bash. - +.inputrc. The Cygwin base installation creates +stub files when you start bash for the first time. .profile (other names are also valid, see the bash man diff --git a/winsup/doc/textbinary.sgml b/winsup/doc/textbinary.sgml index 1e74c5861..674c39ef2 100644 --- a/winsup/doc/textbinary.sgml +++ b/winsup/doc/textbinary.sgml @@ -1,6 +1,6 @@ Text and Binary modes - The Issue + The Issue On a UNIX system, when an application reads from a file it gets exactly what's in the file on disk and the converse is true for writing. @@ -28,7 +28,7 @@ other programs (such as cat, cmp, -The default Cygwin behavior +The default Cygwin behavior The Cygwin system gives us some flexibility in deciding how files are to be opened when the mode is not specified explicitly. @@ -49,22 +49,8 @@ backslash or a colon), the default is binary. Pipes and non-file devices are opened in binary mode, except if the CYGWIN environment variable contains -nobinmode. -Warning!In b20.1 of 12/98, a file will be opened -in binary mode if any of the following conditions hold: - -binary mode is specified in the open call - -the filename is a MS-DOS filename - -the file resides on a binary mounted partition - -CYGWIN contains binmode - -the file is not a disk file - - - +nobinmode. Sockets are always opened in binary +mode. @@ -79,7 +65,7 @@ and program < filename are not equivalent when -Example +Example To illustrate the various rules, we provide scripts to delete CRs from files by using the tr program, which can only write to standard output. @@ -115,7 +101,7 @@ In the second case we rely on the DOS shell to redirect in binary mode. -Binary or text? +Binary or text? UNIX programs that have been written for maximum portability will know the difference between text and binary files and act @@ -150,7 +136,7 @@ in binary mode. -Programming +Programming In the open() function call, binary mode can be specified with the flag O_BINARY and text mode with -- 2.43.5