diff options
Diffstat (limited to 'winsup/doc/how-using.texinfo')
| -rw-r--r-- | winsup/doc/how-using.texinfo | 426 |
1 files changed, 426 insertions, 0 deletions
diff --git a/winsup/doc/how-using.texinfo b/winsup/doc/how-using.texinfo new file mode 100644 index 000000000..4997c2de9 --- /dev/null +++ b/winsup/doc/how-using.texinfo @@ -0,0 +1,426 @@ +@section Using Cygwin + +@subsection How should I set my PATH? + +If you look at the "Cygwin 1.1.0" (or similar) shortcut created in the +"Cygnus Solutions" programs folder, you'll see that it runs +@code{C:\cygwin\bin\cygwin.bat} (assuming your root is +@code{C:\cygwin}). The contents should look something like this: + +@example + @@echo off + SET MAKE_MODE=unix + SET PATH=C:\cygwin\bin;C:\cygwin\usr\local\bin;%PATH% + bash +@end example + +Effectively, this @strong{prepends} /usr/bin and /usr/local/bin to your +Windows system path. If you choose to reset your PATH, say in +$HOME/.bashrc, then you should follow this rule. You @strong{must} have +@code{/usr/bin} in your PATH @strong{before} any Windows system +directories. (And you must not omit the Windows system directories!) +Otherwise you will likely encounter all sorts of problems +running Cygwin applications. + +If you haven't messed up the default mounts, then @code{/bin} and +@code{/usr/bin} are the same location, so you only need one of them in +your PATH. You should use @code{/usr/local/bin} for installing +additional Cygwin applications that are not part of the core net +release. (That is, anything not found in an ftp mirror of @code{latest} +and installed by @code{setup.exe}.) + +@subsection How do I convert between Windows and UNIX paths? + +Use the 'cygpath' utility. Type '@code{cygpath}' with no arguments to +get usage information. For example (on my installation): +@example + bash$ cygpath --windows ~/.bashrc + D:\starksb\.bashrc + bash$ cygpath --unix C:/cygwin/bin/cygwin.bat + /usr/bin/cygwin.bat + bash$ cygpath --unix C:\\cygwin\\bin\\cygwin.bat + /usr/bin/cygwin.bat +@end example +Note that bash interprets the backslash '\' as an escape character, so +you must type it twice in the bash shell if you want it to be recognised +as such. + +@subsection How do I set /etc up? + +@strong{(Please note: This section has not yet been updated for the latest +net release.)} + +If you want a valid /etc set up (so "ls -l" will display correct +user information for example) and if you are running NT (preferably +with an NTFS file system), you should just need to create the /etc +directory on the filesystem mounted as / and then use mkpasswd and +mkgroup to create /etc/passwd and /etc/group respectively. Since +Windows 95/98's Win32 API is less complete, you're out of luck if +you're running Windows 95/98. + +@subsection Why doesn't bash read my .bashrc file on startup? + +Your .bashrc is read from your home directory specified by the HOME +environment variable. It uses /.bashrc if HOME is not set. So you need +to set HOME correctly, or move your .bashrc to the top of the drive +mounted as / in Cygwin. + +@subsection How can I get bash filename completion to be case insensitive? + +"shopt -s nocaseglob" should do the trick. + +@subsection Can I use paths/filenames containing spaces in them? + +Cygwin does support spaces in filenames and paths. That said, some +utilities that use the library may not, since files don't typically +contain spaces in Unix. If you stumble into problems with this, you +will need to either fix the utilities or stop using spaces in filenames +used by Cygwin tools. + +In particular, bash interprets space as a word separator. You would have +to quote a filename containing spaces, or escape the space character. +For example: +@example + bash-2.03$ cd '/cygdrive/c/Program Files' +@end example +or +@example + bash-2.03$ cd /cygdrive/c/Program\ Files +@end example + +@subsection Why can't I cd into a shortcut to a directory? + +Cygwin does not follow MS Windows Explorer Shortcuts (*.lnk files). It +sees a shortcut as a regular file and this you cannot "cd" into it. + +Some people have suggested replacing the current symbolic link scheme +with shortcuts. The major problem with this is that .LNK files would +then be used to symlink Cygwin paths that may or may not be valid +under native Win32 non-Cygwin applications such as Explorer. + +@subsection I'm having basic problems with find. Why? + +Make sure you are using the find that came with Cygwin and that you +aren't picking up the Win32 find command instead. You can verify that +you are getting the right one by doing a "type find" in bash. + +@subsection Why don't cursor keys work under Win95/Win98? + +@strong{(Please note: This section has not yet been updated for the latest +net release.)} + +Careful examination shows that they not just non-functional, but +rather behave strangely, for example, with NumLock off, keys on numeric +keyboard work, until you press usual cursor keys, when even numeric +stop working, but they start working again after hitting alphanumeric +key, etc. This reported to happen on localized versions of Win98 and +Win95, and not specific to Cygwin (there're known cases of Alt+Enter +(fullscreen/windowed toggle) not working and shifts sticking with +other programs). The cause of this problem is Microsoft keyboard +localizer which by default installed in 'autoexec.bat'. Corresponding +line looks like: + +@example +keyb ru,,C:\WINDOWS\COMMAND\keybrd3.sys +@end example + +(That's for russian locale.) You should comment that line if you want +your keys working properly. Of course, this will deprive you of your +local alphabet keyboard support, so you should think about +another localizer. exUSSR users are of course knowledgable of Keyrus +localizer, and it might work for other locales too, since it has keyboard +layout editor. But it has russian messages and documentation ;-( +Reference URL is http://www.hnet.ru/software/contrib/Utils/KeyRus/ +(note the you may need to turn off Windows logo for Keyrus to operate +properly). + +@subsection Is it OK to have multiple copies of the DLL? + +You should only have one copy of the Cygwin DLL on your system. If you +have multiple versions, they will conflict and cause problems. + +If you get the error "shared region is corrupted" it means you have +multiple versions of cygwin1.dll running at the same time. This could +happen, for example, if you update cygwin1.dll without exiting @emph{all} +Cygwin apps (including inetd) beforehand. + +@subsection Where can I find "more"? + +If you are looking for the "more" pager, you should use the "less" pager +instead. + +@subsection Where can I find "which"? + +There is no "which" command with Cygwin. However, you can use the bash +shell builtin "type" which does something similar. + +@subsection How can I access other drives? + +You have some flexibility here. + +Cygwin has a builtin "cygdrive prefix" for drives that are not mounted. +You can access any drive, say Z:, as '/cygdrive/z/'. + +In some applications (notably bash), you can use the familiar windows +<drive>:/path/, using posix forward-slashes ('/') instead of Windows +backward-slashes ('\'). (But see the warning below!) This maps in the +obvious way to the Windows path, but will be converted internally to use +the Cygwin path, following mounts (default or explicit). For example: +@example + bash-2.03$ cd C:/Windows + bash-2.03$ pwd + /cygdrive/c/Windows +@end example +and +@example + bash-2.03$ cd C:/cygwin + bash-2.03$ pwd + / +@end example +for a default setup. (You could also use backward-slashes in the +Windows path, but these would have to be escaped from the shell.) + +@strong{Warning:} There is some ambiguity in going from a Windows path +to the posix path, because different posix paths, through different +mount points, could map to the same Windows directory. This matters +because different mount points may be binmode or textmode, so the +behaviour of Cygwin apps will vary depending on the posix path used to +get there. + +You can avoid the ambiguity of Windows paths, and avoid typing +"/cygdrive", by explicitly mounting drives to posix paths. For example: +@example + bash$ mkdir /c + bash$ mount c:/ /c + bash$ ls /c +@end example +Note that you only need to mount drives once. The mapping is kept +in the registry so mounts stay valid pretty much indefinitely. +You can only get rid of them with umount (or the registry editor). + +The '-b' option to mount mounts the mountpoint in binary mode +("binmode") where text and binary files are treated equivalently. This +should only be necessary for badly ported Unix programs where binary +flags are missing from open calls. It is also the setting for /, +/usr/bin and /usr/lib in a default Cygwin installation. The default for +new mounts is text mode ("textmode"), which is also the mode for all +"cygdrive" mounts. + +@subsection How can I copy and paste into Cygwin console windows? + +Under Windows NT, open the properties dialog of the console window. +The options contain a toggle button, named "Quick edit mode". It must +be ON. Save the properties. + +Under Windows 9x, open the properties dialog of the console window. +Select the Misc tab. Uncheck Fast Pasting. Check QuickEdit. + +@subsection What does "mount failed: Device or resource busy" mean? + +@strong{(Please note: This section has not yet been updated for the latest +net release.)} + +This usually means that you are trying to mount to a location +already in use by mount. For example, if c: is mounted as '/' +and you try to mount d: there as well, you will get this error +message. First "umount" the old location, then "mount" the new one and +you should have better luck. + +If you are trying to umount '/' and are getting this message, you may +need to run @code{regedit.exe} and change the "native" key for the '/' +mount in one of the mount points kept under +HKEY_CURRENT_USER/Software/Cygnus Solutions/CYGWIN.DLL setup/<version> +where <version> is the latest registry version associated with the +Cygwin library. + +@subsection How can I share files between Unix and Windows? + +During development, we have both Unix boxes running Samba and +NT/Windows 95/98 machines. We often build with cross-compilers +under Unix and copy binaries and source to the Windows system +or just toy with them directly off the Samba-mounted partition. +On dual-boot NT/Windows 9x machines, we usually use the FAT +filesystem so we can also access the files under Windows 9x. + +@subsection Are mixed-case filenames possible with Cygwin? + +Several Unix programs expect to be able to use to filenames +spelled the same way, but with different case. A prime example +of this is perl's configuration script, which wants @code{Makefile} and +@code{makefile}. WIN32 can't tell the difference between files with +just different case, so the configuration fails. + +In releases prior to beta 16, mount had a special mixed case option +which renamed files in such a way as to allow mixed case filenames. We +chose to remove the support when we rewrote the path handling code for +beta 16. The standard Windows apps -- explorer.exe, +cmd.exe/command.com, etc. -- do not distinguish filenames that differed +only in case, resulting in some (very) undesirable behavior. + +Sergey Okhapkin had maintained a mixed-case patch ('coolview') until +about B20.1, but this has not been updated to recent versions of Cygwin. + +@subsection What about DOS special filenames? + +Files cannot be named com1, lpt1, or aux (to name a few); either as +the root filename or as the extension part. If you do, you'll have +trouble. Unix programs don't avoid these names which can make things +interesting. E.g., the perl distribution has a file called +@code{aux.sh}. The perl configuration tries to make sure that +@code{aux.sh} is there, but an operation on a file with the magic +letters 'aux' in it will hang. + +@subsection When it hangs, how do I get it back? + +If something goes wrong and the tools hang on you for some reason (easy +to do if you try and read a file called aux.sh), first try hitting ^C to +return to bash or the cmd prompt. + +If you start up another shell, and applications don't run, it's a good +bet that the hung process is still running somewhere. Use the Task +Manager, pview, or a similar utility to kill the process. + +And, if all else fails, there's always the reset button/power switch. +This should never be necessary under Windows NT. + +@subsection Why the weird directory structure? + +Why do /lib and /usr/lib (and /bin, /usr/bin) point to the same thing? + +Why use mounts instead of symbolic links? + +Can I use a disk root (e.g., C:\) as Cygwin root? Why is this discouraged? + +After a new installation in the default location, your mount points will +look something like this: + +@example +Device Directory Type Flags +C:\cygwin\bin /usr/bin user binmode +C:\cygwin\lib /usr/lib user binmode +C:\cygwin / user binmode +@end example + +Note that /bin and /usr/bin point to the same location, as do /lib and +/usr/lib. This is intentional, and you should not undo these mounts +unless you @emph{really} know what you are doing. + +Various applications and packages may expect to be installed in /lib or +/usr/lib (similarly /bin or /usr/bin). Rather than distinguish between +them and try to keep track of them (possibly requiring the occasional +duplication or symbolic link), it was decided to maintain only one +actual directory, with equivalent ways to access it. + +Symbolic links had been considered for this purpose, but were dismissed +because they do not always work on Samba drives. Also, mounts are +faster to process because no disk access is required to resolve them. + +Note that non-cygwin applications will not observe Cygwin mounts (or +symlinks for that matter). For example, if you use WinZip to unpack the +tar distribution of a Cygwin package, it may not get installed to the +correct Cygwin path. @emph{So don't do this!} + +It is strongly recommended not to make the Cygwin root directory the +same as your drive's root directory, unless you know what you are doing +and are prepared to deal with the consequences. It is generally easier +to maintain the Cygwin hierarchy if it is isolated from, say, C:\. For +one thing, you avoid possible collisions with other (non-cygwin) +applications that may create (for example) \bin and \lib directories. +(Maybe you have nothing like that installed now, but who knows about +things you might add in the future?) + +@subsection How do anti-virus programs like Cygwin? + +Users have reported that McAfee (now NAI) VirusScan for NT (and others?) is +incompatible with Cygwin. This is because it tries to scan the +newly loaded shared memory in the cygwin.dll, which can cause fork()s +to fail, wreaking havoc on many of the tools. + +There are also reports of NAI VirusScan causing the system to hang when +unpacking tar.gz archives. This is surely a bug in VirusScan, and +should be reported to NAI. The only workaround is to disable VirusScan +when accessing these files. This can be an issue during setup, and is +discussed in that FAQ entry. + +@subsection Why can't I run bash as a shell under NT Emacs? + +@strong{(Please note: This section has not yet been updated for the latest +net release.)} + +Place the following code in your startup file and try again: + +@smallexample +(load "comint") +(fset 'original-comint-exec-1 (symbol-function 'comint-exec-1)) +(defun comint-exec-1 (name buffer command switches) + (let ((binary-process-input t) + (binary-process-output nil)) + (original-comint-exec-1 name buffer command switches))) +@end smallexample + +@subsection info error "dir: No such file or directory" + +Cygwin packages install their info documentation in the /usr/info +directory. But you need to create a @code{dir} file there before the +standalone info program (probably @code{/usr/bin/info}) can be used to +read those info files. This is how you do it: +@example + bash$ cd /usr/info + bash$ for f in *.info ; do install-info $f dir ; done +@end example +This may generate warnings: +@example + install-info: warning: no info dir entry in `gzip.info' + install-info: warning: no info dir entry in `time.info' +@end example +The @code{install-info} command cannot parse these files, so you will +have to add their entries to @code{/usr/info/dir} by hand. + +@subsection Why do I get a message saying Out of Queue slots? + +@strong{(Please note: This section has not yet been updated for the latest +net release.)} + +"Out of queue slots!" generally occurs when you're trying to remove +many files that you do not have permission to remove (either because +you don't have permission, they are opened exclusively, etc). What +happens is Cygwin queues up these files with the supposition that it +will be possible to delete these files in the future. Assuming that +the permission of an affected file does change later on, the file will +be deleted as requested. However, if too many requests come in to +delete inaccessible files, the queue overflows and you get the message +you're asking about. Usually you can remedy this with a quick chmod, +close of a file, or other such thing. (Thanks to Larry Hall for +this explanation). + +@subsection Why don't symlinks work on samba-mounted filesystems? + +Symlinks are marked with "system" file attribute. Samba does not +enable this attribute by default. To enable it, consult your Samba +documentation and then add these lines to your samba configuration +file: + +@smallexample + map system = yes + create mask = 0775 +@end smallexample + +Note that the 0775 can be anything as long as the 0010 bit is set. + +@subsection Why does df report sizes incorrectly. + +@strong{(Please note: This section has not yet been updated for the latest +net release.)} + +There is a bug in the Win32 API function GetFreeDiskSpace that +makes it return incorrect values for disks larger than 2 GB in size. +Perhaps that may be your problem? + +@subsection Has the screen program been ported yet? + +@strong{(Please note: This section has not yet been updated for the latest +net release.)} + +Screen requires either unix domain sockets or fifoes. Neither of +them have been implemented in Cygwin yet. + |