Contributed by Dave Korn How the C runtime handles startup and termination. -------------------------------------------------- This file documents the processes involved in starting up and shutting down a Cygwin executable. The responsibility is divided between code that is statically linked into each Cygwin-based DLL or executable as part of the C runtime, and code in the Cygwin DLL itself that co-operates with it. The runtime library code lives in the winsup/cygwin/lib directory, and a little of it is in winsup/cygwin/include/cygwin/cygwin_dll.h Process overall startup sequence. ================================= Overall process startup (and indeed termination) is under the control of the underlying Windows OS. The details of the Win32 CreateProcess API and the underlying NT Native API ZwCreateProcess calls are far more complex (and unknown, since proprietary) than we need go into here; the important details are that the process address space is first created, then an initial thread is spawned that performs DLL initialisation, calling the DllMain functions of all statically-linked DLLs in load order. This thread is also serialised under the Windows OS global loader lock, and DllMain functions are very limited in what they can do as a consequence; to help deal with this, cygwin wraps the user's DllMain function and defers calling it until runtime. Once the DLLs have been initialised, the initial thread then performs C runtime setup and calls into the executable's main() function. Entry sequence for Cygwin-based DLLs. ===================================== In the compiler's LINK_SPEC, a -e option sets the entry point (what Windows regards as DllMain) to __cygwin_dll_entry@12. This is defined in include/cygwin/cygwin_dll.h. The user's DllMain function, if any, is called from within this function - directly in the case of thread attach/detach notifications and process detach, but indirectly at process attach time via cygwin_attach_dll in lib/cygwin_attach_dll.c, which calls the CRT common code _cygwin_crt0_common and then hands off to the Cygwin DLL at dll_dllcrt0. The CRT common code doesn't call the user DllMain at once; it caches a pointer to it in the 'main' member of the DLL's per_process struct. __cygwin_dll_entry@12 -> cygwin_attach_dll -> (_cygwin_crt0_common) -> dll_dllcrt0 -> (DllMain?maybe?) dll_dllcrt0 is in dll_init.cc sets up exception handler, ensures cygwin DLL is at least partially initialised, allocates a new entry for the DLL chain, and either calls the 'main' function (via dll::init) before returning to the OS loader, or defers doing so until dll_crt0_1 runs dlls.dll_list::init() during the application's startup sequence, depending on whether Cygwin DLL was fully initialised yet or not. In general statically linked DLLs will defer, while dlopen'd DLLs will run at once. The Cygwin DLL runs the dependent DLL's ctors immediately prior to making the call, whether immediate or deferred. Entry sequence for Cygwin-based executables. ============================================ The entry point is the windows standard entrypoint, WinMainCRTStartup, aliased to mainCRTStartup, defined in crt0.c. It aligns the stack, sets the x87 fpu cw, and hands off to cygwin_crt0 in lib/cygwin_crt0.c, which calls the CRT common init code in _cygwin_crt0_common and heads off into the DLL, never to return from _dll_crt0. mainCRTStartup -> cygwin_crt0 -> (_cygwin_crt0_common) -> _dll_crt0 -> dll_crt0_1 -> (n*DllMain?maybe?) -> main -> (__main) -> cygwin_exit This is a wrapper that does some fork-related stack sorting out then hands off to dll_crt0_1, which completes all Cygwin DLL initialisation, runs any deferred DllMain calls, and jumps into the application, returning via the termination routines. Post-entry construction. ======================== The compiler automatically inserts a hidden call to __main at the start of the user's main() function. During startup, DLL constructors are run in dll:init() immediately prior to calling that DLL's DllMain function (not in a forkee, though; once is enough). In __main, all statically-loaded DLL ctors are now complete, so we queue an atexit call to dll_global_dtors, then run the application's ctors and queue an atexit call to do_global_dtors. Process overall termination sequence. ===================================== The program termination sequence can begin in one of the following ways: - by returning from main() - by calling exit(), _Exit() or _exit() - by calling abort() (this can be implicit, such as when an unhandled C++ exception is thrown, or when an SEH exception is raised and not trapped, or an unhandled signal terminates the program). Unload sequence for Cygwin-based DLLS. ====================================== _cygwin_dll_entry@12 -> (DllMain) -> cygwin_detach_dll -> dll_list::detach -> (remove_dll_atexit) -> (dll::run_dtors) When a DLL is unloaded, whether as a result of dlclose() calling FreeLibrary(), or when then entire process is terminating, the OS arranges to call the DLL's DllMain function with a DLL_PROCESS_DETACH notification. As during the entry sequence, this is also wrapped by _cygwin_dll_entry(), although there is in this case no need to defer calling the user's DllMain hook; it is called at once. If no error is indicated, the dll is then detached from Cygwin's internal tracking list, and any atexit functions it has registered are run and cancelled from the atexit list. Finally any static destructors are run. Exit sequence for Cygwin-based executables. ============================================ This diagram illustrates the code paths, listed above, by which the main executable can terminate: +-------------->-- exception handling --->----------------------------+ | | +-------------->--------- abort --------->--- stdio cleanup ----------+ | | +-------------->-- direct or via _Exit -->-------------------+ | | | | +-------------->----------+ | | | V stdio cleanup, V V main -> dll_crt0_1 -> cygwin_exit -> exit -> atexit funcs -> _exit -> do_exit -> pinfo::exit -> ExitProcess -> END. Returning from main() transfers control back to dll_crt0_1(), which passes the return value to cygwin_exit(); this is the same as calling exit(), which is an export name alias for cygwin_exit() anyway. cygwin_exit() calls the real exit() function in newlib, which runs the atexit functions and shuts down stdio before exiting via _exit(), which immediately passes the exit status through to do_exit(). If exiting via abort(), stdio is cleaned up, but no atexit functions are run. All the termination sequences end up in do_exit(), which takes care of POSIXy stuff like process group and child signalling, tty disconnection, etc. This finally passes control to pinfo::exit(), which takes care of indicating the correct overall exit status and then gives control to the OS process shutdown routine, ExitProcess(). During ExitProcess(), all the statically-linked DLLs in the application are terminated, by calling their DllMain functions with the DLL_PROCESS_DETACH notification. Static object destruction. ========================== Static object destruction for any statically-linked DLLs, or any dlopen()ed DLLs that have still not been dlclose()d by termination time, is handled in dll_global_dtors(). As the description above makes clear, this relies on the atexit functions being run, and so only takes place during a graceful exit, and not in the case of termination via _exit(), _Exit(), abort() or through an unhandled signal or exception. The destructors are run before stdio has been terminated, and in reverse of DLL load order.