diff --git a/winsup/doc/ChangeLog b/winsup/doc/ChangeLog index 99b465c80..755a6f12c 100644 --- a/winsup/doc/ChangeLog +++ b/winsup/doc/ChangeLog @@ -1,3 +1,9 @@ +2003-07-31 Joshua Daniel Franklin * pathnames.sgml: Use correct registry key. Clarify '@' operation. diff --git a/winsup/doc/effectively.sgml b/winsup/doc/effectively.sgml new file mode 100644 index 000000000..d6c2d9ad9 --- /dev/null +++ b/winsup/doc/effectively.sgml @@ -0,0 +1,207 @@ + +Using Cygwin effectively with Windows + + +Cygwin is not a full operating system, and so must rely on Windows for +accomplishing some tasks. For example, Cygwin provides a POSIX view +of the Windows filesystem, but does not provide filesystem drivers of +its own. Therefore part of using Cygwin effectively is learning to use +Windows effectively. +Many Windows utilities provide a good way to interact with Cygwin's +predominately command-line environment. For example, +ipconfig.exe provides information about network +configuration, and net.exe views and configures +network file and printer resources. Most of these tools +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. +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, +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. + + + Pathnames + + +Windows programs do not understand POSIX pathnames, so any arguments +that reference the filesystem must be in Windows (or DOS) format or +translated. Cygwin provides the cygpath utility for +converting between Windows and POSIX paths. A complete description of its +options and examples of its usage are in , +including a shell script for starting Windows Explorer in any directory. +The same format works for most Windows programs, for example + +notepad.exe "$(cygpath -aw "Desktop/Phone Numbers.txt")" + +A few programs require a Windows-style, semicolon-delimited path list, +which cygpath can translate from a POSIX path with the +-p option. For example, a Java compilation from +bash might look like this: + +javac -cp "$(cygpath -pw "$CLASSPATH")" hello.java + +Since using quoting and subshells is somewhat awkward, it is often +preferable to use cygpath in shell scripts. + + + + + Console Programs + +Another issue is receiving output from or giving input to the console-based +Windows programs. Unfortunately, interacting with Windows console +applications is not a simple matter of using a translation utility. Windows +console applications and designed to run under command.com +or 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 +any way to attach to the backend of the console device. Another +traditional Unix input/output method, ptys (pseudo-terminals), are +supported by Cygwin but not entirely by Windows. The basic problem is +that a Cygwin pty is a pipe and some Windows applications do not like +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 programs, use a DOS prompt, running only the occasional Cygwin +command or script. Next would be to run bash with +the default DOS box. To make Cygwin more Unix compatible in this case, +set CYGWIN=tty (see ). +Alternatively, the optional rxvt package provides +a native-Windows version of the popular X11 terminal emulator (it is not +necessary to set CYGWIN=tty with rxvt). +Using rxvt.exe provides the most Unix-like environment, +but expect some compatibility problems with Windows programs. + + + + + Cygwin and Windows Networking + +Many popular Cygwin packages, such as ncftp, +lynx, and wget, require a +network connection. Since Cygwin relies on Windows for connectivity, +if one of these tools is not working as expected you may need to +troubleshoot using Windows tools. The first test is to see if you +can reach the URL's host with ping.exe, one of the +few utilities included with every Windows version since Windows 95. +If you chose to install the inetutils package, you may have both +Windows and Cygwin versions of utilities such as ftp +and telnet. If you are having problems using one +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. +Users who frequently change their network +configuration can script these changes with netsh.exe +(Windows 2000 and XP). For proxy users, the open source + +NTLM Authorization Proxy Server or the no-charge + +Hummingbird SOCKS Proxy may allow you to use Cygwin network +programs in your environment. + + + + +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. + + + +One of the hassles of Unix-Windows interoperability is the different line +endings on text files. As mentioned in , +Unix tools such as tr can convert between CRLF and LF +endings, but cygutils provides several dedicated programs: +conv, d2u, dos2unix, +u2d, and unix2dos. Use the +--help switch for usage information. + + +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 +file. They seem similar at first glance but, in reality, are fairly +different. By default, Cygwin uses a mechanism that creates symbolic +links that are compatible with standard Microsoft .lnk files. However, +they do not include much of the information that is available in a +standard Microsoft shortcut, such as the working directory, an icon, +etc. The cygutils package includes a mkshortcut +utility for creating standard Microsoft .lnk files. + + + +If Cygwin handled these native shortcuts like any other symlink, +you could not archive Microsoft .lnk files into tar +archives and keep all the information in them. After unpacking, +these shortcuts would have lost all the extra information and would +be no different than standard Cygwin symlinks. Therefore these two types +of links are treated differently. Unfortunately, this means that the +usual Unix way of creating and using symlinks does not work with +Windows shortcuts. + + + +Printing with cygutils + +There are several options for printing from Cygwin, including the +lpr found in cygutils (not to be confused with the +native Windows lpr.exe). The easiest way to use cygutils' +lpr is to specify a default device name in the +PRINTER environment variable. You may also specify a device +on the command line with the -d or -P +options, which will override the environment variable setting. + + + +A device name +may be a UNC path (\\server_name\printer_name), a reserved +DOS device name (prn, lpt1), or a +local port name that is mapped to a printer share. Note that forward slashes +may be used in a UNC path (//server_name/printer_name), +which is helpful when using lpr from a shell that uses +the backslash as an escape character. + + + +lpr sends raw data to the printer; no formatting is done. +Many, but not all, printers accept plain text as input. If your printer +supports PostScript, packages such as +a2ps and enscript can prepare text +files for printing. The ghostscript package also provides some translation +from PostScript to various native printer languages. Additionally, a native +Windows application for printing PostScript, gsprint, is +available from the Ghostscript +website. + + + + + diff --git a/winsup/doc/legal.sgml b/winsup/doc/legal.sgml index 1190ecce1..531128e33 100644 --- a/winsup/doc/legal.sgml +++ b/winsup/doc/legal.sgml @@ -1,6 +1,6 @@ -Copyright © 1998,1999,2000,2001 Red Hat, Inc. +Copyright © 1998, 1999, 2000, 2001, 2002, 2003 Red Hat, Inc.