HOWTO: Use the C Run-Time

• Microsoft Win32 Software Development Kit (SDK), versions 3.1, 3.5, 3.51, 4.0

SUMMARY

This document contains the following sections:

Section 1: Three Forms of C Run-Time (CRT) Library Are Available
Section 2: Using the CRT Libraries When Building a DLL
Section 3: Using NTWIN32.MAK to Simplify the Build Process
Section 4: Problems Encountered When Using Multiple CRT Libraries
Section 5: Mixing Library Types

MORE INFORMATION

Section 1: Three Forms of C Run-Time (CRT) Libraries Are Available

• LIBC.LIB is a statically linked library for single-threaded programs.



• LIBCMT.LIB is a statically linked library that supports multithreaded programs.



• CRTDLL.LIB is an import library for CRTDLL.DLL that also supports multithreaded programs. CRTDLL.DLL itself is part of Windows NT.

Section 2: Using the CRT Libraries When Building a DLL

1. the initialization function must be named DllMain() and the entry point must be specified with the linker option -entry:_DllMainCRTStartup@12


- or -


2. the DLL's entry point must explicitly call CRT_INIT() on process attach and process detach

1. if there is no entry function which performs initialization code, simply specify CRT_INIT() as the entry point of the DLL. Assuming that you've included NTWIN32.MAK, which defines DLLENTRY as "@12", add the following option to the DLL's link line:

   -entry:_CRT_INIT$(DLLENTRY)



- or -


2. if you *do* have your own DLL entry point, do the following in the entry point:
   
   
   1. Use this prototype for CRT_INIT():

      BOOL WINAPI _CRT_INIT(HINSTANCE hinstDLL, DWORD fdwReason, LPVOID lpReserved);

      For information on CRT_INIT() return values, see the documentation DllEntryPoint; the same values are returned.
   
   
   
   2. On DLL_PROCESS_ATTACH and DLL_THREAD_ATTACH (see "DllEntryPoint" in the Win32 API reference for more information on these flags), call CRT_INIT(), first, before any C Run-time functions are called or any floating-point operations are performed.
   
   
   
   3. Call your own process/thread initialization/termination code.
   
   
   
   4. On DLL_PROCESS_DETACH and DLL_THREAD_DETACH, call CRT_INIT() last, after all C Run-time functions have been called and all floating- point operations are completed.
   
   
   
   Be sure to pass on to CRT_INIT() all of the parameters of the entry point; CRT_INIT() expects those parameters, so things may not work reliably if they are omitted (in particular, fdwReason is required to determine whether process initialization or termination is needed).
   
   Below is a skeleton sample entry point function that shows when and how to make these calls to CRT_INIT() in the DLL entry point:

   
       BOOL WINAPI DllEntryPoint(HINSTANCE hinstDLL, DWORD fdwReason,
           LPVOID lpReserved)
       {
       if (fdwReason == DLL_PROCESS_ATTACH || fdwReason == DLL_THREAD_ATTACH)
           if (!_CRT_INIT(hinstDLL, fdwReason, lpReserved))
               return(FALSE);
   
       if (fdwReason == DLL_PROCESS_DETACH || fdwReason == DLL_THREAD_DETACH)
           if (!_CRT_INIT(hinstDLL, fdwReason, lpReserved))
               return(FALSE);
       return(TRUE);
       } 

   NOTE that this is *not* necessary if you are using DllMain() and -entry:_DllMainCRTStartup@12.

Section 3: Using NTWIN32.MAK to Simplify the Build Process

   $(cvarsdll)          for apps/DLLs using CRT in a DLL 

   $(conlibsdll)        for console apps/DLLs using CRT in a DLL
   $(guilibsdll)        for GUI apps using CRT in a DLL 

Section 4: Problems Encountered When Using Multiple CRT Libraries

• Passing buffered stream handles from the .EXE/DLL to the other module



• Allocating memory with a C Run-time call in the .EXE/DLL and reallocating or freeing it in the other module



• Checking or setting the value of the global errno variable in the .EXE/DLL and expecting it to be the same in the other module. A related problem is calling perror() in the opposite module from where the C Run- time error occurred, since perror() uses errno.

Section 5: Mixing Library Types

• CRT file handles may only be operated on by the CRT module that created them.



• CRT FILE* pointers may only be operated on by the CRT module that created them.



• Memory allocated with the CRT function malloc() may only be freed or reallocated by the CRT module that allocated it.

   - .EXE is linked with MSVCRT.LIB
   - DLL A is linked with LIBCMT.LIB
   - DLL B is linked with CRTDLL.LIB 

If the .EXE creates a CRT file handle using _create() or _open(), this file handle may only be passed to _lseek(), _read(), _write(), _close(), etc. in the .EXE file. Do not pass this CRT file handle to either DLL. Do not pass a CRT file handle obtained from either DLL to the other DLL or to the .EXE.

If DLL A allocates a block of memory with malloc(), only DLL A may call free(), _expand(), or realloc() to operate on that block. You cannot call malloc() from DLL A and try to free that block from the .EXE or from DLL B.

NOTE: If all three modules were linked with CRTDLL.LIB or all three were linked with MSVCRT.LIb, these restrictions would not apply.

Additional query words:

Keywords :
Version : WINDOWS:3.1,3.5,3.51,4.0
Platform : WINDOWS
Issue type :