diff options
Diffstat (limited to 'winsup/doc/how.texinfo')
| -rw-r--r-- | winsup/doc/how.texinfo | 1140 |
1 files changed, 0 insertions, 1140 deletions
diff --git a/winsup/doc/how.texinfo b/winsup/doc/how.texinfo deleted file mode 100644 index 9d8c405f1..000000000 --- a/winsup/doc/how.texinfo +++ /dev/null @@ -1,1140 +0,0 @@ -@chapter Question and Answers - -@section Where can I get more information? - -@subsection Where's the documentation? - -There are links to quite a lot of it on the main Cygwin project WWW page: -@file{http://sourceware.cygnus.com/cygwin/} -Be sure to at least read the Release Notes on the main WWW page, if -there are any. - -Tool-specific documentation is available at: -@file{http://www.cygnus.com/pubs/gnupro/} - -@subsection What Cygwin mailing lists can I join? - -To subscribe to the main list, send a message to -cygwin-subscribe@@sourceware.cygnus.com. To unsubscribe from the -main list, send a message to cygwin-unsubscribe@@sourceware.cygnus.com. -In both cases, the subject and body of the message is ignored. - -Similarly, to subscribe to the Cygwin annoucements list, send a message -to cygwin-announce-subscribe@@sourceware.cygnus.com. To unsubscribe, -send a message to cygwin-announce-unsubscribe@@sourceware.cygnus.com. - -If you are going to help develop the Cygwin library by volunteering for -the project, you will want to subscribe to the Cygwin developers list, -called cygwin-developers. The same mechanism as described for the first -two lists works for this one as well. - -There's an archive of the main mailing list at - -@file{http://sourceware.cygnus.com/ml/cygwin/} - -@subsection Why won't you/the mailing list answer my questions? - -Perhaps your question has an answer that's already in the FAQ. -Perhaps nobody has time to answer your question. Perhaps nobody -knows the answer... - -@section Installation and Setup - -@subsection Why is the install of the tools failing? - -If you are getting an error message saying "The decompression of -%s failed. There may not be enough free disk space in the TEMP -directory.", read on. - -InstallShield has a bug where it fails with this message if there -are more than a certain number of files in your TEMP directory. -You can also get this message if you have files in your TEMP dir -named the same thing InstallShield wishes to name its files (probably -from past runs of other InstallShield install scripts) which it cannot, -for some reason, write over. Perhaps this will be fixed in a future -release of InstallShield. - -Until then, clearing out your TEMP directory entirely should do it. -That will get rid of any files with conflicting names and solve the -"too many files" problem as well. - -@subsection Help! I haven't created /tmp and tools are behaving strangely! - -Many Unix tools (bash, byacc, etc.) expect that /tmp always exists. -This is not guaranteed in Win32 land. You should create /tmp or "mount" -the directory of your choice to /tmp to avoid this problem. - -@subsection Why does bash spew out "49054596: No such file or directory"? - -Are you sure you created a /tmp? The bash shell will print a -warning if it doesn't find a /tmp directory. - -@subsection How do I set /etc up? - -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 Bash says that it can't vfork (or just hangs). Why? - -Most often this is because it can't find itself in the path. Make sure -that your path includes the directory where bash lives, before you start -it. - -Also make sure you have a valid @code{/bin/sh.exe}. If you get errors -like 'no such file or directory' when you're trying to run a shell -script, which you know is there, then your problem is probably that bash -can't find @code{/bin/sh}. - -@subsection How can I get bash to 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. - -@subsection Why can't I cd into a shortcut to a directory? - -Cygwin does not follow MS Windows Explorer Shortcuts (*.lnk -files) yet. 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 the Cygwin tools -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? - -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? - -It's a bad idea to have multiple versions of the cygwin DLL in -your path. They often conflict in funny ways. If you have -multiple versions, it's usually OK to get rid of (or rename) -all the older versions, keeping only the newest one. - -It should be OK to have multiple copies of the *same* DLL -in your path, though. - -@section Using Cygwin Releases - -@subsection Why aren't man, groff, etc. included in the betas? - -For obvious reasons, it isn't feasible for us to maintain and provide -binary distributions of every tool ported to work with the Cygwin -tools. However, it's likely that a man command will show up in a -distribution soon. - -Many other tools have been ported and are referenced on the Cygwin web -site. man, groff, info, and many many other packages are all -available for download there. - -@subsection Where can I find "less"? - -The less pager binary is available for the first time in the 20.1 -release. You will get it if you upgrade. It is also available from -various ftp locations on the Net. Search the mailing list archives for -the details. - -@subsection Where can I find "more"? - -If you are looking for the "more" pager, you should use the "less" pager -instead. See the last question and answer for more information. - -@subsection Where can I find "which"? - -While we don't include a which command, you can use the bash built -in "type" command which does something fairly similar. - -@subsection How can I access other drives? - -The best way is to use the "mount" command to mount the drive letter so -that you can refer to it with only single slashes: - -@example -bash$ mkdir /c -bash$ mount c:/ /c -bash$ ls /c -.... -@end example - -This is done with textual substitution whenever a file is opened. -So if you're going to do @code{ls /c/bar} on a mount like the above -the guts will turn that into @code{ls c:/bar}. - -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 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. - -Since the beta 16 release, we also support a special means of accessing -other drive letters without using the @code{mount} command. This -support may disappear in a future Cygwin release because of the -collision between this scheme and UNC pathname support (one character -machine names don't work currently). - -To do an "ls" on drive letter f:, do the following: - -@example -bash$ ls //f/ -@end example - -Note that you can also access UNC paths in the standard way. Because of -the drive letter shortcut mentioned above, machine names in UNC paths -must be more than one character long. - -@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? - -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. - -@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 are cpp.exe, cc1.exe, etc., not in the bin directory? - -Why more than one lib and include directory? - -@smallexample -H-i586-cygwin32\lib\gcc-lib\...\egcs-2.91.57\include -x86-cygwin32\include -x86-cygwin32\H-i586-cygwin32\i586-cygwin32\include -@end smallexample - -This way multiple releases for different hosts and targets can all -coexist in the same tree. H-i586-cygwin32 means hosted on -i586-cygwin32, common files shared by all hosts are in the top level -directories, target-specific files are in the -H-i586-cygwin32/i586-cygwin32 -directory, etc... - -If you had a server sharing files to a ppc NT machine and an x86 NT -machine, you could have both an H-i586-cygwin32 and an -H-powerpcle-cygwin32 directory without having to duplicate the top level -files that are the same for both hosts. If you built and installed an -i586-cygwin32 x mips-elf cross-compiler, you would have an -H-i586-cygwin32/mips-elf with its target-specific files and some -mips-elf- prefixed binaries in H-i586-cygwin32/bin. - -Normally we also have another higher level directory that identifies the -release. Then multiple Cygwin releases can coexist with different -dll versions, giving: - -@smallexample -cygnus/b19/H-i586-cygwin32 -cygnus/cygwin-b20/H-i586-cygwin32 -... -@end smallexample - -In any case, this does add complexity to the directory structure but -it's worth it for people with more complex installations. - -@subsection How do anti-virus programs like Cygwin? - -One person reported that McAfee 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. - -@subsection Why can't I run bash as a shell under NT Emacs? - -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 Where did the man/info pages go? - -In order to save space and download times, we have stopped providing -the man/info files for the tools with the binary install since we are -not yet providing a man page or info reader. Both types of -documentation are available in a tar file available from the project ftp -site. Or consult the online documentation over the WWW. - -@subsection Why can't B20's "cygcheck -s" find cpp? - -This is a confusingly worded warning that will be reworded in future -versions. In fact, cygcheck should normally *not* find cpp; if it does, -it may be a problem (e.g. it might pick up Borland's cpp, which would -cause problems). - -@subsection Why do I get a message saying Out of Queue slots? - -"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 - mask 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. - -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? - -Screen requires either unix domain sockets or fifoes. Neither of -them have been implemented in Cygwin yet. - -@section Cygwin API Questions - -@subsection How does everything work? - -There's a C library which provides a Unix-style API. The -applications are linked with it and voila - they run on Windows. - -The aim is to add all the goop necessary to make your apps run on -Windows into the C library. Then your apps should run on Unix and -Windows with no changes at the source level. - -The C library is in a DLL, which makes basic applications quite small. -And it allows relatively easy upgrades to the Win32/Unix translation -layer, providing that dll changes stay backward-compatible. - -For a good overview of Cygwin, you may want to read the paper on Cygwin -published by the Usenix Association in conjunction with the 2d Usenix NT -Symposium in August 1998. It is available in html format on the project -WWW site. - -@subsection Are development snapshots for the Cygwin library available? - -Yes. They're made whenever anything interesting happens inside the -Cygwin library (usually roughly on a nightly basis, depending on how much -is going on). They are only intended for those people who wish to -contribute code to the project. If you aren't going to be happy -debugging problems in a buggy snapshot, avoid these and wait for a real -release. The snapshots are available from -http://sourceware.cygnus.com/cygwin/snapshots/ - - -@subsection How is the DOS/Unix CR/LF thing handled? - -Let's start with some background. - -In UNIX, a file is a file and what the file contains is whatever the -program/programmer/user told it to put into it. In Windows, a file is -also a file and what the file contains depends not only on the -program/programmer/user but also the file processing mode. - -When processing in text mode, certain values of data are treated -specially. A \n (new line) written to the file will prepend a \r -(carriage return) so that if you `printf("Hello\n") you in fact get -"Hello\r\n". Upon reading this combination, the \r is removed and the -number of bytes returned by the read is 1 less than was actually read. -This tends to confuse programs dependant on ftell() and fseek(). A -Ctrl-Z encountered while reading a file sets the End Of File flags even -though it truly isn't the end of file. - -One of Cygwin's goals is to make it possible to easily mix Cygwin-ported -Unix programs with generic Windows programs. As a result, Cygwin opens -files in text mode as is normal under Windows. In the accompanying -tools, tools that deal with binaries (e.g. objdump) operate in unix -binary mode and tools that deal with text files (e.g. bash) operate in -text mode. - -Some people push the notion of globally setting the default processing -mode to binary via mount point options or by setting the CYGWIN32 -environment variable. But that creates a different problem. In -binary mode, the program receives all of the data in the file, including -a \r. Since the programs will no longer deal with these properly for -you, you would have to remove the \r from the relevant text files, -especially scripts and startup resource files. This is a porter "cop -out", forcing the user to deal with the \r for the porter. - -It is rather easy for the porter to fix the source code by supplying the -appropriate file processing mode switches to the open/fopen functions. -Treat all text files as text and treat all binary files as binary. -To be specific, you can select binary mode by adding @code{O_BINARY} to -the second argument of an @code{open} call, or @code{"b"} to second -argument of an @code{fopen} call. You can also call @code{setmode (fd, -O_BINARY)}. - -Note that because the open/fopen switches are defined by ANSI, they -exist under most flavors of Unix; open/fopen will just ignore the switch -since they have no meaning to UNIX. - -Also note that @code{lseek} only works in binary mode. - -Explanation adapted from mailing list email by Earnie Boyd -<earnie_boyd@@yahoo.com>. - -@subsection Is the Cygwin library multi-thread-safe? - -No. - -There is an experimental configure option (--enable-threadsafe), which -allows you to build a DLL with some additional "thread safety" but there -are no guarantees that this is 100% operational. This option also -enables limited "POSIX thread" support. See the file cygwin.din for the -list of POSIX thread functions provided. - -Cygnus does not distribute a DLL with this option enabled, and, -currently, has no plans to do so. - -Cygwin is not multi-thread-safe because: - -1) Newlib (out libc/libm) isn't reentrant (although it almost is). -This would have to be fixed or we would have to switch to a libc/libm -that is reentrant. - -2) Cygwin locks shared memory areas (shared by multiple processes), -but the per-process data is not locked. Thus, different threads in a -multi-threaded application would have access to it and give rise to -nasty race-conditions. - -The Mingw package (what you get when you invoke gcc with -mno-cygwin) is -multi-thread-safe because that configuration doesn't use Cygwin or -newlib. Instead, it uses Microsoft libraries which are -multi-thread-safe for the most part. So as long as the programmer -avoids Microsoft APIs that aren't multi-thread-safe (most are ok), they -should be fine. - -@subsection Why is some functionality only supported in Windows NT? - -Windows 9x: n. -32 bit extensions and a graphical shell for a 16 bit patch to an -8 bit operating system originally coded for a 4 bit microprocessor, -written by a 2 bit company that can't stand 1 bit of competition. - -But seriously, Windows 9x lacks most of the security-related calls and -has several other deficiencies with respect to its version of the Win32 -API. See the calls.texinfo document for more information as to what -is not supported in Win 9x. - -@subsection How is fork() implemented? - -Cygwin fork() essentially works like a non-copy on write version -of fork() (like old Unix versions used to do). Because of this it -can be a little slow. In most cases, you are better off using the -spawn family of calls if possible. - -Here's how fork works as of beta 18: - -Parent initializes a space in the Cygwin process -table for child. Parent creates child suspended using Win32 CreateProcess -call, giving the same path it was invoked with itself. Parent -calls setjmp to save its own context and then sets a pointer to this -in the Cygwin shared memory area (shared among all Cygwin tasks). -Parent fills in the childs .data and .bss subsections by copying from -its own address space into the suspended child's address space. -Parent then starts the child. Parent waits on mutex for child to get -to safe point. Child starts and discovers if has been forked and -then longjumps using the saved jump buffer. Child sets mutex parent -is waiting on and then blocks on another mutex waiting for parent to -fill in its stack and heap. Parent notices child is in safe area, -copies stack and heap from itself into child, releases the mutex -the child is waiting on and returns from the fork call. Child wakes -from blocking on mutex, recreates any mmapped areas passed to it via -shared area and then returns from fork itself. - -@subsection How does wildcarding (globbing) work? - -If an application using CYGWIN.DLL starts up, and can't find the -@code{PID} environment variable, it assumes that it has been started -from the a DOS style command prompt. This is pretty safe, since the -rest of the tools (including bash) set PID so that a new process knows -what PID it has when it starts up. - -If the DLL thinks it has come from a DOS style prompt, it runs a -`globber' over the arguments provided on the command line. This means -that if you type @code{LS *.EXE} from DOS, it will do what you might -expect. - -Beware: globbing uses @code{malloc}. If your application defines -@code{malloc}, that will get used. This may do horrible things to you. - -@subsection How do symbolic links work? - -CYGWIN.DLL generates link files with a magic header. When -you open a file or directory that is a link to somewhere else, it -opens the file or directory listed in the magic header. Because we -don't want to have to open every referenced file to check symlink -status, Cygwin marks symlinks with the system attribute. Files -without the system attribute are not checked. Because remote samba -filesystems do not enable the system attribute by default, symlinks do -not work on network drives unless you explicitly enable this -attribute. - -@subsection Why do some files, which are not executables have the 'x' type. - -When working out the unix-style attribute bits on a file, the library -has to fill out some information not provided by the WIN32 API. - -It guesses that files ending in .exe and .bat are executable, as are -ones which have a "#!" as their first characters. - -@subsection How secure is Cygwin in a multi-user environment? - -Cygwin is not secure in a multi-user environment. For -example if you have a long running daemon such as "inetd" -running as admin while ordinary users are logged in, or if -you have a user logged in remotely while another user is logged -into the console, one cygwin client can trick another into -running code for it. In this way one user may gain the -priveledge of another cygwin program running on the machine. -This is because cygwin has shared state that is accessible by -all processes. - -(Thanks to Tim Newsham (newsham@@lava.net) for this explanation). - -@subsection How do the net-related functions work? - -The network support in Cygwin is supposed to provide the Unix API, not -the Winsock API. - -There are differences between the semantics of functions with the same -name under the API. - -E.g., the select system call on Unix can wait on a standard file handles -and handles to sockets. The select call in winsock can only wait on -sockets. Because of this, cygwin.dll does a lot of nasty stuff behind -the scenes, trying to persuade various winsock/win32 functions to do what -a Unix select would do. - -If you are porting an application which already uses Winsock, then -using the net support in Cygwin is wrong. - -But you can still use native Winsock, and use Cygwin. The functions -which cygwin.dll exports are called 'cygwin_<name>'. There -are a load of defines which map the standard Unix names to the names -exported by the dll -- check out include/netdb.h: - -@example -..etc.. -void cygwin_setprotoent (int); -void cygwin_setservent (int); -void cygwin_setrpcent (int); -..etc.. -#ifndef __INSIDE_CYGWIN_NET__ -#define endprotoent cygwin_endprotoent -#define endservent cygwin_endservent -#define endrpcent cygwin_endrpcent -..etc.. -@end example - -The idea is that you'll get the Unix->Cygwin mapping if you include -the standard Unix header files. If you use this, you won't need to -link with libwinsock.a - all the net stuff is inside the dll. - -The mywinsock.h file is a standard winsock.h which has been hacked to -remove the bits which conflict with the standard Unix API, or are -defined in other headers. E.g., in mywinsock.h, the definition of -struct hostent is removed. This is because on a Unix box, it lives in -netdb. It isn't a good idea to use it in your applications. - -As of the b19 release, this information may be slightly out of date. - -@subsection I don't want Unix sockets, how do I use normal Win32 winsock? - -To use the vanilla Win32 winsock, you just need to #define Win32_Winsock -and #include "windows.h" at the top of your source file(s). You'll also -want to add -lwsock32 to the compiler's command line so you link against -libwsock32.a. - -@subsection What version numbers are associated with Cygwin? - -There is a cygwin.dll major version number that gets incremented -every time we make a new Cygwin release available. This -corresponds to the name of the release (e.g. beta 19's major -number is "19"). There is also a cygwin.dll minor version number. If -we release an update of the library for an existing release, the minor -number would be incremented. - -There are also Cygwin API major and minor numbers. The major number -tracks important non-backward-compatible interface changes to the API. -An executable linked with an earlier major number will not be compatible -with the latest DLL. The minor number tracks significant API additions -or changes that will not break older executables but may be required by -newly compiled ones. - -Then there is a shared memory region compatibity version number. It is -incremented when incompatible changes are made to the shared memory -region or to any named shared mutexes, semaphores, etc. - -Finally there is a mount point registry version number which keeps track -of non-backwards-compatible changes to the registry mount table layout. -This has been "B15.0" since the beta 15 release. - -@subsection Why isn't _timezone set correctly? - -Did you explicitly call tzset() before checking the value of _timezone? -If not, you must do so. - -@section Programming Questions - -@subsection Why is gcc failing? - -If the error is "gcc: installation problem, cannot exec `cpp': -No such file or directory", the GCC_EXEC_PREFIX environment variable -hasn't been set correctly. The current release does not need -GCC_EXEC_PREFIX set -- it should be able to find cpp regardless of the -install location. But if you have it set incorrectly, you may still -see this message. - -@subsection Why can't bison find bison.simple or bison.hairy? - -If you are getting a warning to this effect, you need to set -the BISONLIB environment variable. The value should be the directory -in which bison.simple and bison.hairy are installed. This will be -the path leading up to and including the @code{share} directory of -the top-level of the binary distributions. For example, on some -systems, you would want to set it to @code{C:/cygnus/cygwin-b20/share}. - -@subsection Why is make behaving badly? - -Starting with the beta 19 release, make defaults to a win32 mode in -which backslashes in filenames are permitted and cmd.exe/command.com -is used as the sub-shell. In this mode, escape characters aren't -allowed among other restrictions. For this reason, you must set -the environment variable MAKE_MODE to UNIX to run make on ordinary Unix -Makefiles. Here is the full scoop: - -MAKE_MODE selects between native Win32 make mode (the default) and -a Unix mode where it behaves like a Unix make. The Unix mode does -allow specifying Win32-style paths but only containing forward slashes -as the path separator. The path list separator character is a colon -in Unix mode. - -Win32 mode expects path separators to be either / or \. Thus no -Unix-style \s as escape are allowed. Win32 mode also uses -cmd.exe/command.com as the subshell which means "copy" and "del" -(and other shell builtins) will work. The path list separator -character is semi-colon in Win32 mode. People who want an nmake-like -make might want to use this mode but no one should expect Unix -Makefiles to compile in this mode. That is why the default b19 -install sets MAKE_MODE to UNIX. - -@subsection Why the undefined reference to "WinMain@@16"? - -Try adding an empty main() function to one of your sources. - -@subsection How do I use Win32 API calls? - -It's pretty simple actually. Cygwin tools require that you explicitly -link the import libraries for whatever Win32 API functions that you -are going to use, with the exception of kernel32, which is linked -automatically (because the startup and/or built-in code uses it). - -For example, to use graphics functions (GDI) you must link -with gdi32 like this: - -gcc -o foo.exe foo.o bar.o -lgdi32 - -or (compiling and linking in one step): - -gcc -o foo.exe foo.c bar.c -lgdi32 - -The following libraries are available for use in this way: - -advapi32 largeint ole32 scrnsave vfw32 -cap lz32 oleaut32 shell32 win32spl -comctl32 mapi32 oledlg snmp winmm -comdlg32 mfcuia32 olepro32 svrapi winserve -ctl3d32 mgmtapi opengl32 tapi32 winspool -dlcapi mpr penwin32 th32 winstrm -gdi32 msacm32 pkpd32 thunk32 wow32 -glaux nddeapi rasapi32 url wsock32 -glu32 netapi32 rpcdce4 user32 wst -icmp odbc32 rpcndr uuid -imm32 odbccp32 rpcns4 vdmdbg -kernel32 oldnames rpcrt4 version - -The regular setup allows you to use the option -mwindows on the -command line to include a set of the basic libraries (and also -make your program a GUI program instead of a console program), -including user32, gdi32 and, IIRC, comdlg32. - -Note that you should never include -lkernel32 on your link line -unless you are invoking ld directly. Do not include the same import -library twice on your link line. Finally, it is a good idea to -put import libraries last on your link line, or at least after -all the object files and static libraries that reference them. - -The first two are related to problems the linker has (as of b18 at least) -when import libraries are referenced twice. Tables get messed up and -programs crash randomly. The last point has to do with the fact that -gcc processes the files listed on the command line in sequence and -will only resolve references to libraries if they are given after -the file that makes the reference. - -@subsection How do I compile a Win32 executable that doesn't use Cygwin? - -The -mno-cygwin flag to gcc makes gcc link against standard Microsoft -DLLs instead of Cygwin. This is desirable for native Windows programs -that don't need a UNIX emulation layer. - -@subsection How do I make the console window go away? - -The default during compilation is to produce a console application. -It you are writing a GUI program, you should either compile with --mwindows as explained above, or add the string -"-Wl,--subsystem,windows" to the GCC commandline. - -@subsection Why does make complain about a "missing separator"? - -This problem usually occurs as a result of someone editing a Makefile -with a text editor that replaces tab characters with spaces. Command -lines must start with tabs. - -@subsection Why can't we redistribute Microsoft's Win32 headers? - -Subsection 2.d.f of the `Microsoft Open Tools License agreement' looks like -it says that can not "permit further redistribution of the -Redistributables to their end users". We take this to mean that we can -give them to you, but you can't give them to anyone else, which is -something that Cygnus can't agree to. Fortunately, we have our own -Win32 headers which are pretty complete. - -@subsection How do I link against .lib files? - -1. Build a C file with a function table. Put all functions you intend -to use in that table. This forces the linker to include all the object -files from the .lib. Maybe there is an option to force LINK.EXE to -include an object file. -2. Build a dummy 'LibMain'. -3. Build a .def with all the exports you need. -4. Link with your .lib using link.exe. - -or - -1. Extract all the object files from the .lib using LIB.EXE. -2. Build a dummy C file referencing all the functions you need, either -with a direct call or through an initialized function pointer. -3. Build a dummy LibMain. -4. Link all the objects with this file+LibMain. -5. Write a .def. -6. Link. - -You can use these methods to use MSVC (and many other runtime libs) -with Cygwin development tools. - -Note that this is a lot of work (half a day or so), but much less than -rewriting the runtime library in question from specs... - -(thanks to Jacob Navia (root@@jacob.remcomp.fr) for this explanation) - -@subsection How do I rebuild the tools on my NT box? - -Assuming that you have the src installed as /src, will build in -the directory /obj, and want to install the tools in /install: - -@example -bash -cd /obj -/src/configure --prefix=/install -v > configure.log 2>&1 -make > make.log 2>&1 -make install > install.log 2>&1 -@end example - -@subsection How can I compile a powerpc NT toolchain? - -Unfortunately, this will be difficult. It hasn't been built for -some time (late 1996) since Microsoft has dropped development of -powerpc NT. Exception handling/signals support semantics/args have been -changed for x86 and not updated for ppc so the ppc specific support would -have to be rewritten. We don't know of any other incompatibilities. -Please send us patches if you do this work! - -@subsection How can I compile an Alpha NT toolchain? - -We have not ported the tools to Alpha NT and do not have plans to -do so at the present time. We would be happy to add support -for Alpha NT if someone contributes the changes to us. - -@subsection How can I adjust the heap/stack size of an application? - -Pass heap/stack linker arguments to gcc. To create foo.exe with -a heap size of 1024 and a stack size of 4096, you would invoke -gcc as: - -@code{gcc -Wl,--heap,1024,--stack,4096 -o foo foo.c} - -@subsection How can I find out which dlls are needed by an executable? - -objdump -p provides this information. - -@subsection How do I build a DLL? - -There's documentation that explains the process on the main Cygwin -project web page (http://sourceware.cygnus.com/cygwin/). - -@subsection How can I set a breakpoint at MainCRTStartup? - -Set a breakpoint at *0x401000 in gdb and then run the program in -question. - -@subsection How can I build a relocatable dll? - -You must execute the following sequence of five commands, in this -order: - -@example -$(LD) -s --base-file BASEFILE --dll -o DLLNAME OBJS LIBS -e ENTRY - -$(DLLTOOL) --as=$(AS) --dllname DLLNAME --def DEFFILE \ - --base-file BASEFILE --output-exp EXPFILE - -$(LD) -s --base-file BASEFILE EXPFILE -dll -o DLLNAME OBJS LIBS -e ENTRY - -$(DLLTOOL) --as=$(AS) --dllname DLLNAME --def DEFFILE \ - --base-file BASEFILE --output-exp EXPFILE - -$(LD) EXPFILE --dll -o DLLNAME OBJS LIBS -e ENTRY -@end example - -In this example, $(LD) is the linker, ld. - -$(DLLTOOL) is dlltool. - -$(AS) is the assembler, as. - -DLLNAME is the name of the DLL you want to create, e.g., tcl80.dll. - -OBJS is the list of object files you want to put into the DLL. - -LIBS is the list of libraries you want to link the DLL against. For -example, you may or may not want -lcygwin. You may want -lkernel32. -Tcl links against -lcygwin -ladvapi32 -luser32 -lgdi32 -lcomdlg32 --lkernel32. - -DEFFILE is the name of your definitions file. A simple DEFFILE would -consist of ``EXPORTS'' followed by a list of all symbols which should -be exported from the DLL. Each symbol should be on a line by itself. -Other programs will only be able to access the listed symbols. - -BASEFILE is a temporary file that is used during this five stage -process, e.g., tcl.base. - -EXPFILE is another temporary file, e.g., tcl.exp. - -ENTRY is the name of the function which you want to use as the entry -point. This function should be defined using the WINAPI attribute, -and should take three arguments: - int WINAPI startup (HINSTANCE, DWORD, LPVOID) - -This means that the actual symbol name will have an appended @@12, so if -your entry point really is named @samp{startup}, the string you should -use for ENTRY in the above examples would be @samp{startup@@12}. - -If your DLL calls any Cygwin API functions, the entry function will need -to initialize the Cygwin impure pointer. You can do that by declaring -a global variable @samp{_impure_ptr}, and then initializing it in the -entry function. Be careful not to export the global variable -@samp{_impure_ptr} from your DLL; that is, do not put it in DEFFILE. - -@example -/* This is a global variable. */ -struct _reent *_impure_ptr; -extern struct _reent *__imp_reent_data; - -int entry (HINSTANT hinst, DWORD reason, LPVOID reserved) -@{ - _impure_ptr = __imp_reent_data; - /* Whatever else you want to do. */ -@} -@end example - -You may put an optional `--subsystem windows' on the $(LD) lines. The -Tcl build does this, but I admit that I no longer remember whether -this is important. Note that if you specify a --subsytem <x> flag to ld, -the -e entry must come after the subsystem flag, since the subsystem flag -sets a different default entry point. - -You may put an optional `--image-base BASEADDR' on the $(LD) lines. -This will set the default image base. Programs using this DLL will -start up a bit faster if each DLL occupies a different portion of the -address space. Each DLL starts at the image base, and continues for -whatever size it occupies. - -Now that you've built your DLL, you may want to build a library so -that other programs can link against it. This is not required: you -could always use the DLL via LoadLibrary. However, if you want to be -able to link directly against the DLL, you need to create a library. -Do that like this: - -$(DLLTOOL) --as=$(AS) --dllname DLLNAME --def DEFFILE --output-lib LIBFILE - -$(DLLTOOL), $(AS), DLLNAME, and DEFFILE are the same as above. Make -sure you use the same DLLNAME and DEFFILE, or things won't work right. - -LIBFILE is the name of the library you want to create, e.g., -libtcl80.a. You can then link against that library using something -like -ltcl80 in your linker command. - -@subsection How can I debug what's going on? - -You can debug your application using @code{gdb}. Make sure you -compile it with the -g flag! If your application calls functions in -MS dlls, gdb will complain about not being able to load debug information -for them when you run your program. This is normal since these dlls -don't contain debugging information (and even if they did, that debug -info would not be compatible with gdb). - -@subsection Can I use a system trace mechanism instead? - -Yes. If you have a newer cygwin with the @code{strace.exe} program, -@code{strace} can run other cygwin programs with various debug and -trace messages enabled. For information on using the @code{strace} -program, see the Cygwin User's Guide or the file -@code{winsup/utils/utils/sgml}. - -If you have an older cygwin, you can set the <CODE>STRACE</CODE> -environment variable to <CODE>1</CODE>, and get a whole load of debug -information on your screen whenever a Cygwin app runs. This is an -especially useful tool to use when tracking bugs down inside the -Cygwin library. <CODE>STRACE</CODE> can be set to different values to -achieve different amounts of granularity. You can set it to -<CODE>0x10</CODE> for information about syscalls or <CODE>0x800</CODE> -for signal/process handling-related info, to name two. The strace -mechanism is well documented in the Cygwin library sources in the file -<CODE>winsup/include/sys/strace.h</CODE>. - -@subsection The linker complains that it can't find something. - -A common error is to put the library on the command line before -the thing that needs things from it. - -This is wrong @code{gcc -lstdc++ hello.cc}. -This is right @code{gcc hello.cc -lstdc++}. - -@subsection I use a function I know is in the API, but I still get a link -error. - -The function probably isn't declared in the header files, or -the UNICODE stuff for it isn't filled in. - -@subsection Can you make DLLs that are linked against libc ? - -Yes. - -@subsection Where is malloc.h? - -Include stdlib.h instead of malloc.h. - -@subsection Can I use my own malloc? - -If you define a function called @code{malloc} in your own code, and link -with the DLL, the DLL @emph{will} call your @code{malloc}. Needless to -say, you will run into serious problems if your malloc is buggy. - -If you run any programs from the DOS command prompt, rather than from in -bash, the DLL will try and expand the wildcards on the command line. -This process uses @code{malloc} @emph{before} your main line is started. -If you have written your own @code{malloc} to need some initialization -to occur after @code{main} is called, then this will surely break. - -@subsection Can I mix objects compiled with msvc++ and gcc? - -Yes, but only if you are combining C object files. MSVC C++ uses a -different mangling scheme than GNU C++, so you will have difficulties -combining C++ objects. - -@subsection Can I use the gdb debugger to debug programs built by VC++? - -No, not for full (high level source language) debugging. -The Microsoft compilers generate a different type of debugging -symbol information, which gdb does not understand. - -However, the low-level (assembly-type) symbols generated by -Microsoft compilers are coff, which gdb DOES understand. -Therefore you should at least be able to see all of your -global symbols; you just won't have any information about -data types, line numbers, local variables etc. - -@subsection Where can I find info on x86 assembly? - -CPU reference manuals for Intel's current chips are available in -downloadable PDF form on Intel's web site: - -@file{http://developer.intel.com/design/pro/manuals/} - -@subsection Shell scripts aren't running properly from my makefiles? - -You need to have . (dot) in your $PATH. You should NOT need to add -/bin/sh in front of each and every shell script invoked in your -Makefiles. - -@subsection What preprocessor do I need to know about? - -We use _WIN32 to signify access to the Win32 API and __CYGWIN__ for -access to the Cygwin environment provided by the dll. - -We chose _WIN32 because this is what Microsoft defines in VC++ and -we thought it would be a good idea for compatibility with VC++ code -to follow their example. We use _MFC_VER to indicate code that should -be compiled with VC++. - -@subsection Where can I get f77 and objc components for B20 EGCS 1.1? - -B20-compatible versions of the f77 and objc components are available -from @file{http://www.xraylith.wisc.edu/~khan/software/gnu-win32/}. - -@subsection How should I port my Unix GUI to Windows? - -There are two basic strategies for porting Unix GUIs to Windows. - -The first is to use a portable graphics library such as tcl/tk, X11, or -V (and others?). Typically, you will end up with a GUI on Windows that -requires some runtime support. With tcl/tk, you'll want to include the -necessary library files and the tcl/tk DLLs. In the case of X11, you'll -need everyone using your program to have an X11 server installed. - -The second method is to rewrite your GUI using Win32 API calls (or MFC -with VC++). If your program is written in a fairly modular fashion, you -may still want to use Cygwin if your program contains a lot of shared -(non-GUI-related) code. That way you still gain some of the portability -advantages inherent in using Cygwin. - -@subsection Why not use DJGPP ? - -DJGPP is a similar idea, but for DOS instead of Win32. DJGPP uses a -"DOS extender" to provide a more reasonable operating interface for its -applications. The Cygwin toolset doesn't have to do this since all of -the applications are native WIN32. Applications compiled with the -Cygwin tools can access the Win32 API functions, so you can write -programs which use the Windows GUI. - -You can get more info on DJGPP by following -@file{http://www.delorie.com/}. |