From 04360c5005f4f26529e8d429b17fb354f6c011ed Mon Sep 17 00:00:00 2001 From: David Starks-Browning Date: Wed, 13 Sep 2000 15:13:17 +0000 Subject: [PATCH] New files, contents of how.texinfo has been split into these. --- winsup/doc/how-api.texinfo | 284 +++++++++++++++ winsup/doc/how-programming.texinfo | 536 +++++++++++++++++++++++++++++ winsup/doc/how-resources.texinfo | 115 +++++++ winsup/doc/how-using.texinfo | 426 +++++++++++++++++++++++ 4 files changed, 1361 insertions(+) create mode 100644 winsup/doc/how-api.texinfo create mode 100644 winsup/doc/how-programming.texinfo create mode 100644 winsup/doc/how-resources.texinfo create mode 100644 winsup/doc/how-using.texinfo diff --git a/winsup/doc/how-api.texinfo b/winsup/doc/how-api.texinfo new file mode 100644 index 000000000..83fb7ce03 --- /dev/null +++ b/winsup/doc/how-api.texinfo @@ -0,0 +1,284 @@ +@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://sources.redhat.com/cygwin/snapshots/ + + +@subsection How is the DOS/Unix CR/LF thing handled? + +@strong{(Please note: This section has not yet been updated for the latest +net release.)} + +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 +. + +@subsection Is the Cygwin library multi-thread-safe? + +Multi-thread-safe support is turned on by default in 1.1.x releases +(i.e., in the latest net release). That does not mean that it is bug +free! + +There is also limited support for 'POSIX threads', see the file +@code{cygwin.din} for the list of POSIX thread functions provided. + +@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 it works: + +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? + +@strong{(Please note: This section has not yet been updated for the latest +net release.)} + +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 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? + +@strong{(Please note: This section has not yet been updated for the latest +net release.)} + +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_'. 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? + +@strong{(Please note: This section has not yet been updated for the latest +net release.)} + +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? + +@strong{(Please note: This section has not yet been updated for the latest +net release.)} + +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? + +@strong{(Please note: This section has not yet been updated for the latest +net release.)} + +Did you explicitly call tzset() before checking the value of _timezone? +If not, you must do so. + +@subsection Is there a mouse interface? + +There is no way to capture mouse events from Cygwin. There are +currently no plans to add support for this. + diff --git a/winsup/doc/how-programming.texinfo b/winsup/doc/how-programming.texinfo new file mode 100644 index 000000000..7b74b7b8f --- /dev/null +++ b/winsup/doc/how-programming.texinfo @@ -0,0 +1,536 @@ +@section Programming Questions + +@subsection Why are compiled executables so huge?!? + +By default, gcc compiles in all symbols. You'll also find that gcc +creates large executables on UNIX. + +If that bothers you, just use the 'strip' program, part of the binutils +package. + +@subsection Where is glibc? + +Cygwin does not provide glibc. It uses newlib instead, which provides +much (but not all) of the same functionality. Porting glibc to Cygwin +would be difficult. + +@subsection Why is make behaving badly? + +@strong{(Please note: This section has not yet been updated for the latest +net release.)} + +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"? + +@strong{(Please note: This section has not yet been updated for the latest +net release.)} + +Try adding an empty main() function to one of your sources. + +@subsection How do I use Win32 API calls? + +@strong{(Please note: This section has not yet been updated for the latest +net release.)} + +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. + +This is not to be confused with 'MinGW' (Minimalist GNU for Windows), +which is a completely separate effort. That project's home page is +@file{http://www.mingw.org/index.shtml}. + +@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. This is not specific to Cygwin. + +@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 one may 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 (err... Red Hat) can't agree to. Fortunately, we +have our own Win32 headers which are pretty complete. + +@subsection How do I link against .lib files? + +@strong{(Please note: This section has not yet been updated for the latest +net release.)} + +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? + +@strong{Note:} You must build in a directory @emph{outside} the source +tree. + +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 + +Normally, this will also attempt to build the documentation, which +additionally requires db2html, texi2html and possibly others. +These tools are not included in the Cygwin distribution, but are readily +obtainable: + +@table @samp +@item db2html +Part of docbook, from @file{http://sources.redhat.com/docbook-tools/}. +@item texi2html +From @file{http://www.mathematik.uni-kl.de/~obachman/Texi2html/}. +@end table + +To check a cygwin1.dll, run "make check" in the winsup/cygwin directory. +If that works, install everything @emph{except} the dll (if you can). +Then, close down all cygwin programs (including bash windows, inetd, +etc.), save your old dll, and copy the new dll to @emph{all} the +places where the old dll was (if there is more than one on your +machine). Then start up a bash window and see what happens. (Or better, +run a cygwin program from the Windows command prompt.) + +If you get the error "shared region is corrupted" it means that two +different versions of cygwin1.dll are running on your machine at the +same time. + +@subsection How can I compile a powerpc NT toolchain? + +@strong{(Please note: This section has not yet been updated for the latest +net release.)} + +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? + +@strong{(Please note: This section has not yet been updated for the latest +net release.)} + +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? + +@strong{(Please note: This section has not yet been updated for the latest +net release.)} + +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? + +@strong{(Please note: This section has not yet been updated for the latest +net release.)} + +objdump -p provides this information. + +@subsection How do I build a DLL? + +@strong{(Please note: This section has not yet been updated for the latest +net release.)} + +There's documentation that explains the process on the main Cygwin +project web page (http://sources.redhat.com/cygwin/). + +@subsection How can I set a breakpoint at MainCRTStartup? + +@strong{(Please note: This section has not yet been updated for the latest +net release.)} + +Set a breakpoint at *0x401000 in gdb and then run the program in +question. + +@subsection How can I build a relocatable dll? + +@strong{(Please note: This section has not yet been updated for the +latest net release. However, there was a discussion on the cygwin +mailing list recently that addresses this issue. Read +@file{http://sources.redhat.com/ml/cygwin/2000-06/msg00688.html} and +related messages.)} + +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 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. You can use the @code{strace.exe} utility to run other cygwin +programs with various debug and trace messages enabled. For information +on using @code{strace}, see the Cygwin User's Guide or the file +@code{winsup/utils/utils.sgml}. + +Alternatively, you can set the @code{STRACE} environment variable to +@code{1}, 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} can be +set to different values to achieve different amounts of granularity. +You can set it to @code{0x10} for information about syscalls or +@code{0x800} 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/cygwin/include/sys/strace.h}. + +@subsection Why doesn't gdb handle signals? + +Unfortunately, there is only minimal signal handling support in gdb +currently. Signal handling only works with Windows-type signals. +SIGINT may work, SIGFPE may work, SIGSEGV definitely does. You cannot +'stop', 'print' or 'nopass' signals like SIGUSR1 or SIGHUP to the +process being debugged. + +@subsection The linker complains that it can't find something. + +@strong{(Please note: This section has not yet been updated for the latest +net release.)} + +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. + +@strong{(Please note: This section has not yet been updated for the latest +net release.)} + +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 ? + +@strong{(Please note: This section has not yet been updated for the latest +net release.)} + +Yes. + +@subsection Where is malloc.h? + +@strong{(Please note: This section has not yet been updated for the latest +net release.)} + +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. + +Moreover, there is an outstanding issue with @code{_malloc_r} in +@code{newlib}. This re-entrant version of @code{malloc} will be called +directly from within @code{newlib}, by-passing your custom version, and +is probably incompatible with it. But it may not be possible to replace +@code{_malloc_r} too, because @code{cygwin1.dll} does not export it and +Cygwin does not expect your program to replace it. This is really a +newlib issue, but we are open to suggestions on how to deal with it. + +@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? + +@strong{(Please note: This section has not yet been updated for the latest +net release.)} + +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? + +@strong{(Please note: This section has not yet been updated for the latest +net release.)} + +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? + +@strong{(Please note: This section has not yet been updated for the latest +net release.)} + +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? + +@strong{(Please note: This section has not yet been updated for the latest +net release.)} + +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/}. diff --git a/winsup/doc/how-resources.texinfo b/winsup/doc/how-resources.texinfo new file mode 100644 index 000000000..8db4f0d02 --- /dev/null +++ b/winsup/doc/how-resources.texinfo @@ -0,0 +1,115 @@ +@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 web +page: @file{http://sources.redhat.com/cygwin/}. Be sure to at least +read any 'Release Notes' or 'Readme' or 'read this' links on the main +web page, if there are any. + +There is a comprehensive Cygwin User's Guide at +@file{http://sources.redhat.com/cygwin/cygwin-ug-net/cygwin-ug-net.html} +and an API Reference at +@file{http://sources.redhat.com/cygwin/cygwin-api/cygwin-api.html}. + +There is an interesting paper about Cygwin from the 1998 USENIX Windows +NT Workshop Proceedings at +@file{http://sources.redhat.com/cygwin/usenix-98/cygwin.html}. + +You can find documentation for the individual GNU tools at +@file{http://www.fsf.org/manual/}. (You should read GNU manuals from a +local mirror, check @file{http://www.fsf.org/server/list-mirrors.html} +for a list of them.) + +@subsection What Cygwin mailing lists can I join? + +Comprehensive information about the Cygwin mailing lists can be found at +@file{http://sources.redhat.com/cygwin/lists.html}. + +To subscribe to the main list, send a message to +cygwin-subscribe@@sources.redhat.com. To unsubscribe from the +main list, send a message to cygwin-unsubscribe@@sources.redhat.com. +In both cases, the subject and body of the message are ignored. + +Similarly, to subscribe to the Cygwin annoucements list, send a message +to cygwin-announce-subscribe@@sources.redhat.com. To unsubscribe, +send a message to cygwin-announce-unsubscribe@@sources.redhat.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. If you are contributing to Cygwin tools & +applications, rather than the library itself, then you should subscribe +to cygwin-apps. The same mechanism as described for the first two lists +works for these as well. Both cygwin-developers and cygwin-apps are +by-approval lists. + +There is a searchable archive of the main mailing list at +@file{http://sources.redhat.com/ml/cygwin/}. There is an alternate +archive, also searchable, at @file{http://www.delorie.com/archives/}. + +Cygwin mailing lists are not gatewayed to USENET, so anti-spam measures +in your email address are neither required nor appreciated. Also, avoid +sending HTML content to Cygwin mailing lists. + +@subsection Posting Guidelines (Or: Why won't you/the mailing list answer my questions?) + +If you follow these guidelines, you are much more likely to get a +helpful response from the Cygwin developers and/or the Cygwin community at +large: + +@itemize @bullet +@item Read the User's Guide and the FAQ first. +@item Check the mailing list archives. Your topic may have come up +before. (It may even have been answered!) Use the search facilities +at the links above. Try the alternate site if the main archive is not +producing search results. +@item Explain your problem carefully and completely. "I installed Blah +and it doesn't work!" wastes everybody's time. It provides no +information for anyone to help you with your problem. You should +provide: + +@itemize @bullet +@item A problem statement: How does it behave, how do you think it +should behave, and what makes you think it's broken? (Oh yeah, and what +is @emph{"it"}?) +@item Information about your Windows OS ("Win95 OSR2" or "NT4/SP3" or +"Win2K" or "Win98 SE" or ...). +@item Details about your installation process, or attempts at same. (Internet or +Directory install? If the former, exactly when and from what mirror? +If the latter, which packages did you download? Which version of +setup.exe? Any subsequent updates?) +@item Details about your Cygwin setup, accomplished by @emph{pasting} +the output of 'cygcheck -s -v -r' into your message. (Do not send the +output as a file attachment.) +@item A valid return address, so that a reply doesn't require manual editing of +the 'To:' header. +@end itemize + +@item Your message must be relevant to the list. Messages that are +@emph{not} directly related to Cygwin are considered off-topic and are +unwelcome. For example, the following are off-topic: + +@itemize @bullet +@item General programming language questions +@item General Windows programming questions +@item General UNIX shell programming questions +@item General application usage questions +@item How to make millions by working at home +@item Announcements from LaserJet toner cartridge suppliers +@end itemize + +@end itemize + +If you do not follow the above guidelines, you may still elicit a +response, but you may not appreciate it! + +Inquiries about support contracts and commercial licensing should go to +info@@cygnus.com. If you want to purchase the Cygwin 1.0 CD-ROM, visit +@file{http://www.cygnus.com/cygwin/} or write to +cygwin-info@@cygnus.com. While not strictly @emph{unappreciated} in the +main cygwin list, you'll get the information you need more quickly if +you write to the correct address in the first place. + +Beyond that, perhaps nobody has time to answer your question. Perhaps +nobody knows the answer. + 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 +:/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/ +where 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. +