This chapter describes the Win32/x86-specific features of standard libraries provided with the CodeWarrior® IDE.
A variety of static libraries for use with the CodeWarrior development environment exist. They include ANSI-standard libraries for C and C++, as well as libraries for software development with the Win32 application programming interface and the Microsoft Foundation Classes. This chapter discusses how to use these libraries when targeting the Win32/x86 platform. For more on the common (target-neutral) features of the standard libraries, refer to the MSL C Reference and the MSL C++ Reference.
For additional information on libraries specific to AMD® processors, see "Library Considerations."
The Metrowerks Standard Libraries (MSL) are ANSI-standard C and C++ libraries included with the CodeWarrior product.
Metrowerks standard libraries:
| Library File |
Description |
|---|---|
These libraries, listed in Table 12.1, are fully documented in the MSL C Reference and MSL C++ Reference. In addition, there are Win32/x86 run-time libraries that contain startup code required to initialize applications and dynamic link libraries (DLLs). These are listed in Table 12.2.
| Library File |
Description |
|---|---|
NOTE The DLL versions of the runtime library also include the MSL C library, so if you use those, you do not need to include ANSICx86.LIB in your project.
All of these libraries are provided in both static-library and source-code formats for inclusion in your project. To use them, simply add them to your project by choosing Project > Add Files in the IDE.
NOTE The C++ library depends on the presence of the C library, so if you use it you must include the C library as well. All Win32/x86 applications and DLLs should also include the runtime library.
There can be complications if your final build consists of separate elements, such as an application and a DLL, and you include the MSL libraries in both. If you create both an application and a DLL with the same MSL library, you will end up with two copies of the library in the final code: one in the application and one in the DLL. Files and memory opened or allocated from one cannot be used indiscriminately by the other.
For example, you cannot open a file in one application program or DLL and then use it in another one. All operations on a given file must be performed within the same application or DLL.This is because the two copies of the library each have their own copy of the internal structures associated with a file.
For memory, the restriction is less severe but even more important. Memory allocated by one application or DLL can be used by another, but it must not be freed except in the same application or DLL that allocated it. If you break this rule, you will probably trash the heap and eventually crash.
A related issue concerns C++ exception handling. When you use exception handling, the compiler and linker build tables that direct the action when an exception is thrown. This is no problem if all your code is in one application or DLL. A problem does arise, however, if you throw an exception in one DLL and catch it in another, or catch it in the application, because the thrower's and catcher's copies of the MSL library each have only half the needed information.
The Win32 DLL runtimes mwcrtl.dll and mwcrtld.dll allow you to work around this. These replace the static runtime
and ANSI C libraries. If the C++ standard library is required,
use the ANSICPPX86M.LIB variants. These are the same as the regular ones, except they
import the C standard library code as needed from mwcrtl.lib.
This ensures that there is one shared copy of the exception-handling code. Hence, when you throw an exception, the code is aware of both the thrower and catcher, even if they are in separate applications or DLLs.
These DLL files must be present on the target Win32/x86 system
when your application is run, and must be in the same directory
as the application or in a directory mentioned in the PATH environment variable.
In addition to the MSL libraries, the CodeWarrior IDE also comes with a set of standard Microsoft libraries embodying the Win32 application program interface (API). The libraries in Table 12.3 are required for most Win32 applications.
Libraries for Win32 development:
| Library File |
Description |
|---|---|
Any libraries that you may need to include to resolve (at link time) Win32 API calls made in your code are discussed on the World Wide Web at:
http://msdn.microsoft.com
Depending on what specific Win32 facilities you use, you may also need to include one or more of the libraries in Table 12.4.
Additional libraries for Win32 development:
| Library File |
||
|---|---|---|
The Microsoft Foundation Classes (MFC) are an object-oriented
application framework that implements the key building blocks
in a Win32 application. To start using the MFC library quickly,
create your project from MFC-based stationery as described in
"Creating an Application," or "Creating a Dynamic Link Library." This stationery includes both the static MFC library (MFC.LIB) in the project and the necessary precompiled header file (MFCHeaders) in the project prefix. You can also add the library manually
if you wish.
Any libraries that you need to include to resolve (at link time) Microsoft Foundation Classes (MFC) API calls made in your code are discussed on the web at:
http://msdn.microsoft.com
This site includes complete information on all the libraries you may need, as well as source code examples with using MFC.
A number of functions are included in the Metrowerks Standard C Library for the Win32 target. These functions are most often used in support of the Microsoft Foundation Class (MFC) library, but are open for other use. This section discusses details on each of these additional functions, which you are free to use should the need arise. The functions are listed in Table 12.5.
| Function Name |
||
|---|---|---|
For more information, refer to the Microsoft Win32 Reference.
You can also read the Win32SDK.hlp help file and MSL C Reference, included on the CodeWarrior CD.