+2009-04-03 Kevin Buettner <kevinb@redhat.com>
+
+ * Various syntactical and semantical fixes throughout.
+
2009-04-01 Corinna Vinschen <corinna@vinschen.de>
* faq-using.xml (faq.using.symlinkstoppedworking): Rename.
<screen>-f, --config-file <file></screen>
<para>
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.
</para>
<sect2 id="cygserver-config"><title>The Cygserver configuration file</title>
<para>
- 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.
</para>
<para>
</listitem>
<listitem>
-<para><envar>forkchunk:32768</envar> - causes the <function>fork()</function>
+<para><envar>forkchunk:32768</envar> - causes <function>fork()</function>
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
</listitem>
<listitem>
-<para><envar>proc_retry:n</envar> - causes the <function>fork()</function> and <function>exec*()</function>
-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.
+<para><envar>proc_retry:n</envar> - causes <function>fork()</function> and
+<function>exec*()</function> 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.
</para>
</listitem>
<listitem>
<para><envar>(no)upcaseenv</envar> - 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:</para>
+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:</para>
<screen>
ALLUSERSPROFILE
COMMONPROGRAMFILES
</sect2>
<sect2 id="cygwinenv-removed-options">
-<title>Removed options</title>
+<title>Obsolete options</title>
<para>
-Some CYGWIN options have been removed in Cygwin 1.7 for one reason or another.
-These removed options are listed below.</para>
+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.</para>
<itemizedlist mark="bullet">
application call to the <function>setlocale()</function> function, and in
turn by the setting of the environment variables <envar>$LANG</envar>,
<envar>$LC_ALL</envar>, or <envar>$LC_CTYPE</envar>, this setting
-got useless.</para>
+became superfluous.</para>
</listitem>
<listitem>
<listitem>
<para><envar>(no)traverse</envar> - 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.</para>
+it's behaviour has been getting worse with each new OS version. This
+complicates its usage so the option has been removed for now.</para>
</listitem>
</itemizedlist>
<sect1 id="ov-new1.7"><title>What's new and what changed in Cygwin 1.7</title>
-<sect2 id="ov-new1.7-os"><title>OS releated changes</title>
+<sect2 id="ov-new1.7-os"><title>OS related changes</title>
<screen>
-- 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.
</screen>
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:
- 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.
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.
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.
</screen>
</sect2>
-<sect2 id="ov-new1.7-misc"><title>Miscellanous</title>
+<sect2 id="ov-new1.7-misc"><title>Miscellaneous</title>
<screen>
- New ldd utility, similar to Linux.
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.
- 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).
</screen>
/usr/lib/csih/getAccountName.exe, which can be used to print the
(possibly localized) name for the various well-known SIDS.</para>
-<para>Naturally well-known SIDs are the same on each machine, so they are
+<para>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.</para>
-<para>Additionally there are a couple of well-known builtin groups,
+<para>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:</para>
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
<xref linkend="ntsec-mapping"></xref>.</para>
<para>POSIX is able to create only three different permissions? Not quite.
<para>Do I have to mention that you can also rename groups in
<filename>/etc/group</filename>? 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:</para>
+all is well. This allows you to, for instance, rename the "Administrators"
+group to "root" as well:</para>
<example id="ntsec-group-tweaked">
<title>/etc/group, tweaked:</title>
</screen>
</example>
-<para>Last but not least you can also change the primary group of a user
+<para>Last but not least, you can also change the primary group of a user
in <filename>/etc/passwd</filename>. 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 <filename>/etc/passwd</filename>
to the Cygwin uid of "Users" (see in <filename>/etc/group</filename>,
default 545) and let the user create files with a default group ownership
of "Users".</para>
-<para>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 <filename>/etc/passwd</filename>
-and <filename>/etc/group</filename> 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.</para>
+<note><para>
+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 <filename>/etc/passwd</filename>
+and <filename>/etc/group</filename> files created by
+<command>mkpasswd</command> and <command>mkgroup</command>. (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.
+</para></note>
</sect2>
<sect2 id="ntsec-mapping"><title id="ntsec-mapping.title">The POSIX permission mapping leak</title>
<para>As promised earlier, here's the problem when trying to map the
-POSIX permission model on the Windows permission model.</para>
+POSIX permission model onto the Windows permission model.</para>
<para>There's a leak in the definition of a "correct" ACL which
disallows a certain POSIX permission setting. The official
</screen>
<para>Ok, so here's the first try to create a matching ACL, assuming
-the Windows permissions only have three bits, as their POSIX pendants:</para>
+the Windows permissions only have three bits, as their POSIX counterpart:
+</para>
<screen>
UserAllow: 110
"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.</para>
<para>On POSIX systems, this operation can be performed by processes
<sect2 id="ntsec-logonuser"><title id="ntsec-logonuser.title">Switching the user context with password authentication</title>
-<para>To switch the user context the process has to request such an access
+<para>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 <command>LogonUser</command> with the user name and the user's
cleartext password as arguments. If the user exists and the password was
documentation.</para>
<para>Back to this logon with password, how can this be used to
-implement <command>set(e)uid</command>? Well, it requires to patch the
-calling application. Two Cygwin functions have been introduced to support
-porting <command>setuid</command> applications which only require login
-with passwords. You only give Cygwin the right access token and then
-you can call <command>seteuid</command> or <command>setuid</command> as
-usual in POSIX applications. Porting such a <command>setuid</command>
-application is illustrated by a short example:</para>
+implement <command>set(e)uid</command>? Well, it requires modification
+of the calling application. Two Cygwin functions have been introduced
+to support porting <command>setuid</command> applications which only
+require login with passwords. You only give Cygwin the right access
+token and then you can call <command>seteuid</command> or
+<command>setuid</command> as usual in POSIX applications. Porting such
+a <command>setuid</command> application is illustrated by a short
+example:</para>
<screen>
<
OSDN Git Service
