diff --git a/winsup/doc/ChangeLog b/winsup/doc/ChangeLog index bf45cae35..e290b55b5 100644 --- a/winsup/doc/ChangeLog +++ b/winsup/doc/ChangeLog @@ -1,3 +1,7 @@ +2009-04-03 Kevin Buettner + + * Various syntactical and semantical fixes throughout. + 2009-04-01 Corinna Vinschen * faq-using.xml (faq.using.symlinkstoppedworking): Rename. diff --git a/winsup/doc/cygserver.sgml b/winsup/doc/cygserver.sgml index 9fabf97bd..006a93ed6 100644 --- a/winsup/doc/cygserver.sgml +++ b/winsup/doc/cygserver.sgml @@ -53,7 +53,7 @@ -f, --config-file <file> Use <file> as configuration file instead of the default configuration - line. The default configuration file is /etc/cygserver.conf, typically. + line. The default configuration file is /etc/cygserver.conf. The --help and --version options will print the default configuration pathname. @@ -194,10 +194,10 @@ The Cygserver configuration file - Cygserver has many options, which allow to customize the server + Cygserver has many options, which allow you to customize the server to your needs. Customization is accomplished by editing the configuration - file, which is by default /etc/cygserver.conf. This file is read only - once on startup of Cygserver. There's no option to re-read the file on + file, which is by default /etc/cygserver.conf. This file is only read + once, at startup of Cygserver. There's no option to re-read the file at runtime by, say, sending a signal to Cygserver. diff --git a/winsup/doc/cygwinenv.sgml b/winsup/doc/cygwinenv.sgml index a3d7f52f2..cefecf254 100644 --- a/winsup/doc/cygwinenv.sgml +++ b/winsup/doc/cygwinenv.sgml @@ -44,7 +44,7 @@ There is no default set. -forkchunk:32768 - causes the fork() +forkchunk:32768 - causes fork() to copy memory some number of bytes at a time, in the above example 32768 bytes (32Kb) at a time. The default is to copy as many bytes as possible, which is preferable in most cases but may slow some older systems @@ -53,9 +53,10 @@ 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. +proc_retry:n - causes 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. @@ -103,11 +104,11 @@ other terminals (i.e., rxvt or xterm). (no)upcaseenv - if set, Cygwin converts all environment variables to all-uppercase, when a Cygwin process is started -from a non-Cygwin native Windows process. This is how it has been done -until Cygwin 1.5. If not set, Cygwin does not change the case of environment -variables, except for a restricted set to maintain minimal backward -compatibility and for correct handling of certain essential variables. -The current list of always uppercased variables is: +from a non-Cygwin native Windows process. This was the default behavior in +releases prior to Cygwin 1.7. If not set, Cygwin does not change the case +of environment variables, except for a restricted set to maintain minimal +backward compatibility and for correct handling of certain essential +variables. The current list of always uppercased variables is: ALLUSERSPROFILE COMMONPROGRAMFILES @@ -152,11 +153,12 @@ old symlinks used the current ANSI or OEM charset. -Removed options +Obsolete options -Some CYGWIN options have been removed in Cygwin 1.7 for one reason or another. -These removed options are listed below. +Certain CYGWIN options available in past releases have been removed in +Cygwin 1.7 for one reason or another. These obsolete options are listed +below. @@ -181,7 +183,7 @@ is now doing all character conversion by itself, depending on the application call to the setlocale() function, and in turn by the setting of the environment variables $LANG, $LC_ALL, or $LC_CTYPE, this setting -got useless. +became superfluous. @@ -221,7 +223,8 @@ 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. +it's behaviour has been getting worse with each new OS version. This +complicates its usage so the option has been removed for now. diff --git a/winsup/doc/new-features.sgml b/winsup/doc/new-features.sgml index 47a2d6058..205eadbcd 100644 --- a/winsup/doc/new-features.sgml +++ b/winsup/doc/new-features.sgml @@ -1,9 +1,9 @@ What's new and what changed in Cygwin 1.7 -OS releated changes +OS related changes -- Windows 95, 98 and Me are not supported anymore. The new Cywin 1.7 DLL +- Windows 95, 98 and Me are not supported anymore. The new Cygwin 1.7 DLL will not run on any of these systems. @@ -21,7 +21,7 @@ the character will be converted to a sequence Ctrl-N + UTF-8 representation of the character. This allows to access all files, even those not having a valid representation of their filename in the current character - set (codepage). To have always a valid string, use the UTF-8 charset + set (codepage). To always have a valid string, use the UTF-8 charset by setting the environment variable $LANG, $LC_ALL, or $LC_CTYPE to a valid POSIX value, for instance in Cygwin.bat like this: @@ -48,7 +48,7 @@ - Creating files with special DOS device filename components ("aux", "nul", "prn") is supported. -- File name are case sensitive if the OS and the underlying file system +- File names are case sensitive if the OS and the underlying file system supports it. Works on NTFS and NFS. Does not work on FAT and Samba shares. Requires to change a registry key (see the user's guide). Can be switched off on a per-mount base. @@ -79,7 +79,7 @@ default again when creating symlinks. Only create Windows shortcut style symlinks if CYGWIN=winsymlinks is set in the environment. -- Symlinks are now using UTF-16 encoding for the target filename for +- Symlinks now use UTF-16 encoding for the target filename for better internationalization support. Cygwin 1.7 can read all old style symlinks, but the new style is not compatible with older Cygwin releases. @@ -241,20 +241,20 @@ script. The advantages and disadvantages are noted in http://cygwin.com/ml/cygwin-developers/2006-11/msg00000.html -- Cygwin now allows to store and use user passwords in a hidden area of +- Cygwin now allows storage and use of user passwords in a hidden area of the registry. This is tried first when Cygwin is called by privileged processes to switch the user context. This allows, for instance, ssh public key sessions with full network credentials to access shares on other machines. -- The mkpasswd and mkgroup tools have changed behaviour and a couple of - new options to ease consistent usage in multi-machine or multi-domain - environments. +- New options have been added to the mkpasswd and mkgroup tools to + ease use in multi-machine and multi-domain environments. The existing + options have a slightly changed behaviour. -Miscellanous +Miscellaneous - New ldd utility, similar to Linux. @@ -265,8 +265,8 @@ since they don't understand these paths. - On the first usage of a DOS path (C:\foo, \\foo\bar), the Cygwin DLL - emits a scary warning that DOS paths shouldn't be used. There's also - the new CYGWIN=nodosfilewarning setting to disable that. + emits a scary warning that DOS paths shouldn't be used. This warning + may be disabled via the new CYGWIN=nodosfilewarning setting. - The CYGWIN environment variable option "server" has been removed. Cygwin automatically uses cygserver if it's available. @@ -294,7 +294,7 @@ - Optimized strstr and memmem implementation. -- Remove backwards compatibility with old signal masks (some *very* old +- Remove backwards compatibility with old signal masks. (Some *very* old programs which use signal masks may no longer work correctly). diff --git a/winsup/doc/ntsec.sgml b/winsup/doc/ntsec.sgml index 168e12000..6f8ebee0d 100644 --- a/winsup/doc/ntsec.sgml +++ b/winsup/doc/ntsec.sgml @@ -153,11 +153,11 @@ SIDs. The Cygwin package called "csih" provides a tool, /usr/lib/csih/getAccountName.exe, which can be used to print the (possibly localized) name for the various well-known SIDS. -Naturally well-known SIDs are the same on each machine, so they are +Naturally, well-known SIDs are the same on each machine, so they are not unique to a machine or domain. They have the same meaning across the Windows network. -Additionally there are a couple of well-known builtin groups, +Additionally, there are a couple of well-known builtin groups, which have the same SID on every machine and which have certain user rights by default: @@ -202,7 +202,7 @@ 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. But there's a problem with the definition of a "correct" ACL -which disallows to map certain POSIX permissions cleanly. See +which disallows mapping of certain POSIX permissions cleanly. See . POSIX is able to create only three different permissions? Not quite. @@ -295,8 +295,8 @@ out she's still actually the domain user BAR\corinna... 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: +all is well. This allows you to, for instance, rename the "Administrators" +group to "root" as well: /etc/group, tweaked: @@ -305,26 +305,29 @@ root:S-1-5-32-544:544: -Last but not least you can also change the primary group of a user +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". So, if it's -more feasible in your environment that the user's primary group is +which in turn belongs to the well-known group "Users". So, if it's +more convenient in your environment for the user's primary group to be "Users", just set the user's primary group in /etc/passwd to the Cygwin uid of "Users" (see in /etc/group, default 545) and let the user create files with a default group ownership of "Users". -However, here's a WARNING: If you want to do similar changes to -your files, please do that only if you're feeling comfortable with the -concepts. Otherwise don't be surprised if some stuff doesn't work -anymore. If you screwed up things, revert to /etc/passwd -and /etc/group files created by mkpasswd -and mkgroup. Especially don't change the UID or the name of user -SYSTEM. Even if that works mostly, some Cygwin applications running as -local service under that account could suddenly start behaving -strangely. + +If you wish to make these kind of changes to /etc/passwd and /etc/group, +do so only if you feel comfortable with the concepts. Otherwise, do not +be surprised if things break in either subtle or surprising ways! If you +do screw things up, revert to copies of /etc/passwd +and /etc/group files created by +mkpasswd and mkgroup. (Make +backup copies of these files before modifying them.) Especially, don't +change the UID or the name of the user SYSTEM. It may mostly work, but +some Cygwin applications running as a local service under that account +could suddenly start behaving strangely. + @@ -403,7 +406,7 @@ the possible confusion. The POSIX permission mapping leak As promised earlier, here's the problem when trying to map the -POSIX permission model on the Windows permission model. +POSIX permission model onto the Windows permission model. There's a leak in the definition of a "correct" ACL which disallows a certain POSIX permission setting. The official @@ -447,7 +450,8 @@ rw-r-xrw- Ok, so here's the first try to create a matching ACL, assuming -the Windows permissions only have three bits, as their POSIX pendants: +the Windows permissions only have three bits, as their POSIX counterpart: + UserAllow: 110 @@ -505,7 +509,7 @@ aren't able (or willing) to deal with that order. "Switch User" feature, which switches the entire desktop to another user while leaving the original user's desktop "suspended". Another Windows feature (since Windows 2000) is the "Run as..." context menu entry, -which allows to start an application using another user account when +which allows you to start an application using another user account when right-clicking on applications and shortcuts. On POSIX systems, this operation can be performed by processes @@ -531,7 +535,7 @@ with restricted permissions. Switching the user context with password authentication -To switch the user context the process has to request such an access +To switch the user context, the process has to request such an access token for the new user. This is typically done by calling the Win32 API function LogonUser with the user name and the user's cleartext password as arguments. If the user exists and the password was @@ -549,13 +553,14 @@ these extensions to the original concept are important for this documentation. Back to this logon with password, how can this be used to -implement set(e)uid? Well, it requires to patch the -calling application. Two Cygwin functions have been introduced to support -porting setuid applications which only require login -with passwords. You only give Cygwin the right access token and then -you can call seteuid or setuid as -usual in POSIX applications. Porting such a setuid -application is illustrated by a short example: +implement set(e)uid? Well, it requires modification +of the calling application. Two Cygwin functions have been introduced +to support porting setuid applications which only +require login with passwords. You only give Cygwin the right access +token and then you can call seteuid or +setuid as usual in POSIX applications. Porting such +a setuid application is illustrated by a short +example: Switching the user context without password, Method 1: Create a token from scratch -So far unfortunate for the implementation of a -set(e)uid call is the fact that the calling process -needs the password of the user it wants to switch to. Applications like +An unfortunate aspect of the implementation of +set(e)uid is the fact that the calling process +requires the password of the user to which to switch. Applications such as sshd wishing to switch the user context after a -successful public key authentication, or cron which -has to switch the user without any authentication are stuck here. But -there are other ways to get new user tokens. +successful public key authentication, or the cron +application which, again, wants to switch the user without any authentication +are stuck here. But there are other ways to get new user tokens. One way is just to create a user token from scratch. This is accomplished by using an (officially undocumented) function on the NT -function level. The NT function level is closer to the actual kernel -than the Win32 level. Actually the Win32 functions are implemented -using the NT functions. The function we're interested in is -NtCreateToken. This function allows to specify -user, groups, permissions and almost everything you need to create -a user token, without the need to specify the user password. The +function level. The NT function level is used to implement the Win32 +level, and, as such is closer to the kernel than the Win32 level. The +function of interest, NtCreateToken, allows you to +specify user, groups, permissions and almost everything you need to +create a user token, without the need to specify the user password. The only restriction for using this function is that the calling process -needs the "Create a token object" user right, which only the -SYSTEM user account has by default, and which is considered the most -dangerous right a user can have on Windows systems. +needs the "Create a token object" user right, which only the SYSTEM user +account has by default, and which is considered the most dangerous right +a user can have on Windows systems. That sounds good. We just start the servers which have to switch the user context (sshd, inetd, @@ -639,23 +643,23 @@ has a few drawbacks. First of all, beginning with Windows Server 2003, the permission "Create a token object" gets explicitely removed from the SYSTEM user's access token, when starting services under that -account. That requires to create a new account with this specific +account. That requires us to create a new account with this specific permission just to run this kind of services. But that's a minor problem. A more important problem is that using NtCreateToken is not sufficient to create a new logon session for the new user. What -does that mean? Every logon usually creates also a new logon session. +does that mean? Every logon usually creates a new logon session. A logon session has a couple of attributes which are unique to the session. One of these attributes is the fact, that Windows functions identify the user domain and user name not by the SID of the access token owner, but only by the logon session the process is running under. -What that means is this. Consider a service started under the -SYSTEM account (up to Windows XP) switches the user context to -DOMAIN\my_user using a token created directly by calling the -NtCreateToken function. A process running under this -new access token might want to know under which user account it's +This has the following unfortunate consequence. Consider a +service started under the SYSTEM account (up to Windows XP) switches the +user context to DOMAIN\my_user using a token created directly by calling +the NtCreateToken function. A process running under +this new access token might want to know under which user account it's running. The corresponding SID is returned correctly, for instance S-1-5-21-1234-5678-9012-77777. However, if the same process asks the OS for the user name of this SID something wierd happens. For instance, @@ -703,7 +707,7 @@ bash$ grep foo //server/share/foofile with Windows 2000. Windows NT4 users have to use one of the other methods described in this document. -So we're looking for another way to switch the user context without +We're looking for another way to switch the user context without having to provide the password. Another technique is to create an LSA authentication package. LSA is an acronym for "Local Security Authority" which is a protected part of the operating system which only allows changes @@ -748,8 +752,6 @@ using NtCreateToken, isn't it? - - Switching the user context without password, Method 3: With password Ok, so we have solved almost any problem, except for the network @@ -759,11 +761,11 @@ script is a harsh problem for automated logons for testing purposes and similar stuff. Fortunately there is a solution, but it has its own drawbacks. -But first thing first, how does it work? The title of this section +But, first things first, how does it work? The title of this section says it all. Instead of trying to logon without password, we just logon with password. The password gets stored two-way encrypted in a hidden, obfuscated area of the registry, the LSA private registry area. This -part of the registry contains for instance the passwords of the Windows +part of the registry contains, for instance, the passwords of the Windows services which run under some non-default user account. So what we do is to utilize this registry area for the purpose of @@ -825,7 +827,7 @@ safely use this method. -Switching the user context, how does that all fit together? +Switching the user context, how does it all fit together? Now we learned about four different ways to switch the user context using the set(e)uid system call, but diff --git a/winsup/doc/overview.sgml b/winsup/doc/overview.sgml index 38e421823..975b508dd 100644 --- a/winsup/doc/overview.sgml +++ b/winsup/doc/overview.sgml @@ -66,8 +66,8 @@ url="http://www.usenix.org/publications/library/proceedings/usenix-nt98/technica -Cygwin began development in 1995 at Cygnus Solutions (now part of Red Hat -Software). The first thing done was to enhance the development tools +Cygwin began development in 1995 at Cygnus Solutions (now part of Red Hat, +Inc.). The first thing done was to enhance the development tools (gcc, gdb, gas, etc.) so that they could generate and interpret Win32 native object files. diff --git a/winsup/doc/overview2.sgml b/winsup/doc/overview2.sgml index 453ee142c..c80479cfb 100644 --- a/winsup/doc/overview2.sgml +++ b/winsup/doc/overview2.sgml @@ -193,17 +193,17 @@ 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 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. +Win32 applications handle filenames in a case preserving, but case +insensitive manner. 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 usually the default. 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. +including Windows Server 2003 R2. Native symlinks are available starting +with Windows Vista. Due to their strange implementation, however, +they are not useful in a POSIX emulation layer. Cygwin recognizes +native 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 @@ -240,10 +240,10 @@ 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 +privileged call. Any user may call it. Second, the chroot environment +isn't safe against native windows processes. If you want to use a +chroot environment to, for example, allow anonymous ftp with restricted +access, you must make sure 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 @@ -253,22 +253,24 @@ Win32 paths containing drive letter and/or backslashes as well as UNC paths Text Mode vs. Binary Mode -Interoperability with other Win32 programs such as text editors was -critical to the success in the early days of Cygwin. Most Red Hat -customers upgrading from the older DOS-hosted toolchains expected the new -Win32-hosted ones to continue to work with their old development -sources. +It is often important that files created by native Windows +applications be interoperable with Cygwin applications. For example, a +file created by a native Windows text editor should be readable by a +Cygwin application, and vice versa. -Unfortunately, UNIX and Win32 use different end-of-line terminators in -text files. Consequently, carriage-return newlines have to be translated on -the fly by Cygwin into a single newline when reading in text mode. +Unfortunately, UNIX and Win32 have different end-of-line +conventions in text files. A UNIX text file will have a single newline +character (LF) whereas a Win32 text file will instead use a two +character sequence (CR+LF). Consequently, the two character sequence +must be translated on the fly by Cygwin into a single character newline +when reading in text mode. -This solution addresses the compatibility requirement at the expense of -violating the POSIX standard that states that text and binary mode will be -identical. Consequently, processes that attempt to lseek through text files can -no longer rely on the number of bytes read as an accurate indicator of position -in the file. For this reason, Cygwin allows to choose the mode in which to -read a file in several ways. +This solution addresses the newline interoperability concern at +the expense of violating the POSIX requirement that text and binary mode +be identical. Consequently, processes that attempt to lseek through +text files can no longer rely on the number of bytes read to be an +accurate indicator of position within the file. For this reason, Cygwin +allows you to choose the mode in which a file is read in several ways. ANSI C Library @@ -388,17 +390,17 @@ 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. +supports the getpeereid BSD extension. However, Cygwin does not yet support +descriptor passing. -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. +IPv6 is supported beginning with Cygwin release 1.7.0. This +support is dependent, however, on the availability of the Windows IPv6 +stack. The IPv6 stack was "experimental", i.e. not feature complete in +Windows 2003 and earlier. Full IPv6 support became available starting +with Windows Vista and Windows Server 2008. Cygwin does not depend on +the underlying OS for the (newly implemented) getaddrinfo +and getnameinfo functions. Cygwin 1.7.0 adds +replacement functions which implement the full functionality for IPv4. diff --git a/winsup/doc/pathnames.sgml b/winsup/doc/pathnames.sgml index b9bdd2291..ad1468462 100644 --- a/winsup/doc/pathnames.sgml +++ b/winsup/doc/pathnames.sgml @@ -56,7 +56,7 @@ 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 +not evaluated. The notable exception is the file system type cygdrive. This type is used to set the cygdrive prefix. The fourth field describes the mount options associated @@ -323,7 +323,7 @@ are invalid filenames for native Win32 applications. 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 aqpplications... +to use these files with native Win32 applications. @@ -332,8 +332,8 @@ to use these files with native Win32 aqpplications... 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 +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. Some characters are disallowed in filenames on Windows filesystems: @@ -358,17 +358,17 @@ character set (see ) 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. -For instance, there are no chinese characters in the ISO-8859-1 -character set. So, converting a filename containing a chinese character -to ISO-8859-1 leaves you with a wrongly converted filename, for instance +For instance, there are no Chinese characters in the ISO-8859-1 +character set. So, converting a filename containing a Chinese character +to ISO-8859-1 leaves you with a wrongly converted filename, for instance, containing a question mark '?' as replacement for the unconvertable character. When trying to access the file, Cygwin has to convert the filename back to UTF-16. However, this doesn't result in the original filename because the question mark will not translate back to the original -chinese character, but to a simple question mark instead. This in turn +Chinese character, but to a simple question mark instead. This in turn results in strange "File not found" messages. -To avoid this scenario altogether, just use always UTF-8 as +To avoid this scenario altogether, always use UTF-8 as the character set. If you don't want or can't use UTF-8 as character set for whatever @@ -451,7 +451,7 @@ 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 /cygdrive prefix, your shell might claim that it can't find Windows commands like attrib -or net. To ease the pain the /cygdrive +or net. To ease the pain, the /cygdrive path is case-insensitive by default and you have to use the "posix=1" setting explicitely in /etc/fstab or /etc/fstab.d/$USER to switch it to case-sensitivity, @@ -460,7 +460,7 @@ is using the correct case for all paths throughout. 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 +the subdirectories and filenames under /proc/registry, /proc/registry32 and /proc/registry64. Registry access is always case-insensitive. Read on for more information. @@ -547,16 +547,17 @@ The first floppy in the system is \device\floppy0, the first CD-ROM is 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" (part of the "Computer Management" -console) shoes the mapping "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 to find this information is not very +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. For external disks (USB-drives, CF-cards in a cardreader, etc) you can use -Cygwin to find out the mapping. /proc/partitions +Cygwin to show the mapping. /proc/partitions contains a list of raw drives known to Cygwin. The df command shows a list of drives and their respective sizes. If you match the information between /proc/partitions and the diff --git a/winsup/doc/setup-net.sgml b/winsup/doc/setup-net.sgml index 57c3fb185..a9bc21230 100644 --- a/winsup/doc/setup-net.sgml +++ b/winsup/doc/setup-net.sgml @@ -62,7 +62,7 @@ or Download from Internet, then copy the whole Though this provides some basic mirroring functionality, if you -are managing a wide Cygwin installation, to keep up to date we recommend +are managing a large Cygwin installation, to keep up to date we recommend using a mirroring tool such as wget. A helpful user on the Cygwin mailing list created a simple demonstration script to accomplish this; search the list for mkcygwget for ideas. @@ -152,7 +152,7 @@ The chooser is the most complex part of setup.exe. Packages are grouped into categories, and one package may belong to multiple categories (assigned by the volunteer package maintainer). Each package can be found under any of those categories in the heirarchial chooser view. -By default setup.exe +By default, setup.exe will install only the packages in the Base category and their dependencies, resulting in a minimal Cygwin installation. However, this will not include many commonly used tools such as @@ -177,8 +177,8 @@ Once you have an existing Cygwin installation, the setup.exe chooser is also used to manage your Cygwin installation. Information on installed packages is kept in the /etc/setup/ directory of your Cygwin installation; if -setup.exe cannot find this directory it will act just like -you had no Cygwin installation. If setup.exe +setup.exe cannot find this directory it will act as if +you have no Cygwin installation. If setup.exe finds a newer version of an installed package available, it will automatically mark it to be upgraded. To Uninstall, Reinstall, or get the @@ -208,7 +208,7 @@ to the local directory chosen earlier. Before installing, setup.exe performs a checksum on each package. If the local directory is a slow medium (such as a network drive) this can take a long time. During the download and installation, setup.exe -show progress bars for the current task and total remaining disk space. +shows progress bars for the current task and total remaining disk space. diff --git a/winsup/doc/setup2.sgml b/winsup/doc/setup2.sgml index 02737ff2a..e63ea6f5b 100644 --- a/winsup/doc/setup2.sgml +++ b/winsup/doc/setup2.sgml @@ -1,12 +1,15 @@ Environment Variables -Before starting bash, you may set some environment variables. A .bat -file is provided where the most important ones are set before bash in -launched. This is the safest way to launch bash initially. The .bat -file is installed in the root directory that you specified during setup -and pointed to in the Start Menu under the "Cygwin" option. You can -edit it this file your liking. +You may wish to specify settings of several important environment +variables that affect Cygwin's operation. Some of these settings need +to be in effect prior to launching the initial Cygwin session (before +starting your bash shell, for instance), and are, consequentially, best +placed in a .bat file. An initial file is named Cygwin.bat and is created +in the Cygwin root directory that you specified during setup. Note that +the "Cygwin" option of the Start Menu points to Cygwin.bat. Edit +Cygwin.bat to your liking or create your own .bat files to start +Cygwin processes. The CYGWIN variable is used to configure many global @@ -82,7 +85,7 @@ and set it to the desired memory limit in decimal MB. It is preferred to do this in Cygwin using the regtool program included in the Cygwin package. (For more information about regtool or the other Cygwin -utilities, see or use each the +utilities, see or use the --help option of each util.) You should always be careful when using regtool since damaging your system registry can result in an unusable system. This example sets memory limit to 1024 MB: @@ -201,11 +204,11 @@ internationalization environment variables. -Assuming you set one of the aforementioned environment variables to some -valid POSIX locale value, other than "C" and "POSIX", and assuming you +Assume that you've set one of the aforementioned environment variables to some +valid POSIX locale value, other than "C" and "POSIX", and assume that you call an application which calls setlocale as above. -Assuming further you're living in Japan. So you might want to use +Assume further that you're living in Japan. You might want to use the language code "ja" and the territory "JP", thus setting, say, LANG to "ja_JP". You didn't set a character set, so what will Cygwin use now? Easy! It will use the default Windows ANSI @@ -289,22 +292,21 @@ the UTF-8 charset. This would be especially a problem in variables like consist of valid ASCII characters, and only of uppercase letters, digits, and the underscore for maximum portablilty. -And here's another problem when switching charsets on the fly. -Symbolic links. A symbolic link contains the filename of the target -file the symlink points to. When a symlink had been created with older -versions of Cygwin, the current ANSI or OEM character set had been used -to store the target filename, dependent on the old CYGWIN -environment variable setting codepage -(see . If the target -filename contains non-ASCII characters and you use another -character set than your default ANSI/OEM charset, the target filename of -the symlink is now potentially an invalid character sequence in the new -character set. This behaviour is not different from the behaviour in other -Operating Systems. So, if you suddenly can't access a symlink anymore -which worked all these years before, maybe it's because you switched to +Symbolic links, too, may pose a problem when switching charsets on +the fly. A symbolic link contains the filename of the target file the +symlink points to. When a symlink had been created with older versions +of Cygwin, the current ANSI or OEM character set had been used to store +the target filename, dependent on the old CYGWIN +environment variable setting codepage (see . If the target filename +contains non-ASCII characters and you use another character set than +your default ANSI/OEM charset, the target filename of the symlink is now +potentially an invalid character sequence in the new character set. +This behaviour is not different from the behaviour in other Operating +Systems. So, if you suddenly can't access a symlink anymore which +worked all these years before, maybe it's because you switched to another character set. This doesn't occur with symlinks created with -Cygwin 1.7 or later. - +Cygwin 1.7 or later. @@ -322,8 +324,8 @@ symbols, for a decimalpoint other than '.', no support for native time formats, and no support for native language sorting orders. -However, internationalization is work in progress and we would be glad -for coding help in this area. +Cygwin's internationalization support is work in progress and we would +be glad for coding help in this area. @@ -415,7 +417,7 @@ oif the "CPxxx" style charsets, always use them with the trailing "CP". Customizing bash -To set bash up so that cut and paste work properly, click on the +To set up bash so that cut and paste work properly, click on the "Properties" button of the window, then on the "Misc" tab. Make sure that "QuickEdit mode" and "Insert mode" are checked. These settings will be remembered next time you run bash from that shortcut. Similarly