Black Box 4

home *** CD-ROM | disk | FTP | other *** search

/ Black Box 4 / BlackBox.cdr / progc / dmldoc.arj / DMALOC09.DOC next >

Wrap

Text File | 1992-04-12 | 114.8 KB | 2,564 lines

******************************************************** DDDDD MM MM (TM) DD DD MMM MMM DD DD MMMMMMMM DD DD MMMMMMMM AA LLLL LLLL OOO CCCC DD DD MM MM MM AAAA LL LL OO OO CC CC DD DD MM MM AA AA LL LL OO OO CC DD DD MM MM AA AA LL LL OO OO CC DD DD MM MM AAAAAA LL L LL L OO OO CC DD DD MM MM AA AA LL LL LL LL OO OO CC CC DDDDD MM MM AA AA LLLLLLL LLLLLLL OOO CCCC ******************************************************** v 0.9 A malloc memory debugger for MS-C 5.1 and 6.+ by Ernest E. Vogelsinger ***************** WARRANTY DISCLAIMER **************** DMalloc v0.9 PLEASE READ THIS INFORMATION CAREFULLY ______________________________________ Users of DMalloc must accept the following disclaimer of war- ranty: TRIAL USE (SHAREWARE EVALUATION VERSION) WARRANTY DISCLAIMER THIS COPYRIGHTED SOFTWARE AND ITS DOCUMENTATION IS PROVIDED ON AN "AS IS" BASIS. THE AUTHOR MAKES NO WARRANTY OF ANY KIND, EXPRESSED OR IMPLIED, INCLUDING WITHOUT LIMITATION, ANY WARRAN- TIES OF MERCHANTABILITY AND/OR FITNESS FOR A PARTICULAR PUR- POSE. THE USER ASSUMES ALL RISKS OF THE USE OF THIS SOFTWARE. THE AUTHOR ASSUMES NO LIABILITY FOR DAMAGES, DIRECT OR CONSEQUEN- TIAL, WHICH MAY RESULT FROM THE USE OR MISUSE OF DMALLOC. As it cannot be guaranteed that loss of data will not occur, DMalloc should be tested with non-critical data. As always, judicious backups are a wise and necessary continuing precaution. ***************** WARRANTY DISCLAIMER **************** DMalloc is a trademark of Ernest Vogelsinger. Soft-ICE and Bounds-Checker are registered trademarks of Nu- Mega Technologies, Inc. Microsoft, MS-DOS, and CodeView are registered trademarks of Microsoft Corp. Any other product names used herein are for identification purposes only and may be trademarks or registered trademarks of their respective companies. 1991-1992 Ernest Vogelsinger, Vienna, Austria Table of Contents DMalloc ------------------------------------------------------------------------ 1. Introduction 1.1. What is DMalloc? 1.2. Requirements 1.3. Why DMalloc Instead of a BRAND X Heap Checker 1.4. Summary of Features 1.5. What is Shareware 1.6. DMalloc Unregistered Evaluation Version 1.7. Registration 1.8. Distribution Policies 2. Installation 2.1. Documentation 2.2. A Quick Start 2.3. Where to from here? 2.4. Support & Thanks 3. Demonstration Program 3.1. DMalloc Startup 3.2. Heap Overview 3.3. Total Heap Status 3.4. Detecting Heap Problems 3.5. Invalid Pointer Warning 3.6. Determining Action, Setting Breakpoints 3.7. Null Pointer Assignments 3.8. Fatal Heap Errors 4. Dynamic Memory and DMalloc 4.1. Dynamic Memory Layout 4.2. DMalloc and Dynamic Memory 4.3. Tracking the Functions 4.4. Checking the Heap 4.5. Types of Heap Corruption 4.5.1. Lead Corruption 4.5.2. Trail Corruption 4.5.3. Odd/Even Problem 4.5.4. Mavericks 4.6. Null Pointer Assignments 4.7. Far Null Pointer Assignments 4.8. Watchpoints 4.9. Savepoints 5. DMalloc In Detail 5.1. About DMalloc Windows 5.2. Function Keys 5.3. Information Window 5.3.1. "You can" - Select the Next Action 5.3.2. "Breakpoint:" 5.4. Setup Window 5.4.1. Alert on problem 5.4.2. Popup on saved 5.4.3. Cycles for popup 5.4.4. Heap check cycles Table of Contents DMalloc ------------------------------------------------------------------------ 5.4.5. Popup for file/line 5.4.6. Startup screen 5.4.7. Shutdown screen 5.4.8. Alternate monitor 5.4.9. Number of handles 5.5. Colors Window 5.6. Heap Entries Window 5.6.1. Detecting Corrupted Entries 5.6.2. "Repairing" Corrupted Entries 5.6.3. Watchpoints ("Tags") 5.6.4. Savepoints 5.7. Selection Window 5.8. Dump Window 5.8.1. Editing Data 5.9. Heap Status Window 5.10. The Configuration File 6. How to use DMalloc for Debugging 6.1. Linking DMalloc to the Program 6.2. Recompiling 6.3. Calling the DMalloc API 6.4. DMalloc and Spawn 6.5. DMalloc and Video 6.5.1. Calling RLSI 6.6. DMalloc and Debuggers 6.6.1. Soft-ICE 6.6.2. CodeView 6.6.3. Other Debuggers 6.7. DMalloc and Bounds-Checker 7. Programming API 7.1. Removing DMalloc API Calls 8. Problem Solving Appendix A - The Legal Department (License Agreement) Appendix B - How to Send Email to Compuserve B.1 How to obtain a CompuServe Account B.2 MCI B.3 Internet B.4 Telex, Twx B.5 X.400 B.6 MHS Page 1 DMalloc ------------------------------------------------------------------------ 1. Introduction 1.1. What is DMalloc? DMalloc is a full-featured, convenient, windowed pop-up dynamic memory debugger for C language applications. It monitors heap integrity and the dynamic memory re- quirements of an application. From a technical point of view DMalloc is a library that is linked with the program's object files. 1.2. Requirements DMalloc can be used with C programs compiled with MicroSoft C versions 5.1 and 6.x. DMalloc is currently available for use with the "large" memory model (far code, far data). DOS version should be 3.30 or above(1). DMalloc will add about 49kB to the code, and - depending on the setup - 28 to 168 kB of data. 1.3. Why DMalloc Instead of a BRAND X Heap Checker DMalloc checks the integrity of dynamic memory. Unlike other packages, it monitors the allocated memory units themselves, instead of tracking out-of-bounds segment accesses. Thus it is an ideal companion to 386-based bound checking utilities such as Bounds-Checker. For more in- formation on segments and allocation units refer to sec- tion 4. No need to recompile a source module. DMalloc tracks all calls to memory allocation/deallocation, even in third-party code. Null pointer assignments are detected much earlier than by the runtime library (which detects them at the end of the program). And, as a special feature for the large memory model, even assignments to far null pointers are detected and repaired (if possible) to keep the interrupt table intact. DMalloc can cooperate with other debuggers. Special sup- port has been built in for CodeView and Soft-ICE debug- gers. DMalloc can be used as a background watchdog as well as to interactively review the requirements and fragmentation status of the dynamic heap. DMalloc supports an alternate monitor to allow debugging of graphical applications. -------------------- 1 DMalloc was tested with DOS versions 3.30, 4.01, and 5.00. However, nothing special is needed from DOS, so other versions should do as well. Page 2 DMalloc ------------------------------------------------------------------------ DMalloc even remembers allocation units that have been tampered with from one session to the next. DMalloc provides a rich API to allow fine-tuning of debug- ging setups from within the source code. DMalloc is shareware, allowing you to fully evaluate it for 30 days. If you don't like it, you don't pay for it. However, DMalloc is a very professional debug utility, and not playware. 1.4. Summary of Features - Tracking of allocation and deallocation of dynamic memory - Integrity check on every allocated unit - Integrity check on the data segment null region (null pointer assignment error) - Integrity check and repair on the far-null region - Automatic pop-up when a heap problem is encountered - Automatic pop-up when allocating memory that has been corrupted in the last debug session, or that has been selected to be saved - Graceful program termination when the heap is destroyed and the program would be likely to hang - Interactive pop-up by pressing [PrtSc] - Sorted display of data segments and all allocated units - Assignment of allocation units to source file and line (when recompiling) - Optional selective display selection by specifying source file and line number - Viewing and editing of allocation unit contents - Pop-up when freeing/reallocating selected units (Watchpoint feature) - Possibility to set breakpoints to debuggers at return from a malloc call - Extensive setup options to tailor DMalloc's behaviour to the current debug context, and changing setup options at runtime - Alternate monitor support to allow debugging of graphical applications - User-defined screen colors on both monitors - Automatic save of setup options, and corrupted and selected allocation units on an per-application basis - Rich API for program/debugger interaction Page 3 DMalloc ------------------------------------------------------------------------ 1.5. What is Shareware Shareware distribution gives users a chance to try software before buying it. If you try a Shareware program and continue to use it, you are expected to register. Copyright laws apply to both Shareware and commercial software, and the copyright holder retains all rights. Shareware authors are accomplished programmers, just like commercial authors, and the programs are of comparable quality - in both cases, there are good programs and bad ones! The main difference between the two is in the method of distribution. So Shareware is a distribution method, not a type of software. You should find software that suits your needs and pocketbook, whether it's commercial or Shareware. The Shareware system makes fitting your needs easier, because you can try before you buy. And because the overhead is low, prices are low also. Shareware has the ultimate money-back guarantee - if you don't use the product, you don't pay for it. 1.6. DMalloc Unregistered Evaluation Version The unregistered version of DMalloc is fully functional. When a program linked with the unregistered version is starting and terminating, a window will pop up to remind you that you are using an unregistered copy. To pass this reminder screen, hit any key. The reminder screen at the start will automatically disappear after 5 seconds. 1.7. Registration DMalloc is copyrighted Shareware, it is NOT PUBLIC DOMAIN, it is NOT FREE. If you find DMalloc of value and continue to use it after a thirty day evaluation period you MUST register your copy of DMalloc. When you register you receive: - a serial number and license for one copy of DMalloc - a diskette with a registered copy of DMalloc - any technical updates of DMalloc v 0.9 available at that time - DMalloc v 1.0 when it becomes available - a printed and bound manual - free bonus standalone utilities (as available) - a greater voice in suggesting future enhancements - the satisfaction of supporting the shareware concept Page 4 DMalloc ------------------------------------------------------------------------ If you have not previously registered, and after an evaluation of DMalloc you wish to register, or if you would just like a registered copy to be shipped out to you, the cost is: 35.00 US$ s/h6.00 US$ ----------- 41.00 US$ To have an additional manual to be shipped, the cost is 10.00 US$ s/h6.00 US$ ----------- 16.00 US$ You have three options for registering, or ordering a printed manual: 1) By regular mail: forward your name, CompuServe UserID if available, (and serial number if upgrading) and check or money order made payable to Ernest Vogelsinger to: Ernest Vogelsinger Hietzinger Hauptstrasse 40 c A-1130 Vienna, Austria If you have the evaluation package of DMalloc, you can use the included fold up registration form/envelope. Then all you need is a stamp and a check. See section 2.1 for more information. 2) By telephone or fax(2): if this is by VISA card, call or fax your order to (+43) 1 828 46 09 ORDERS ONLY! SUPPORT IS NOT AVAILABLE AT THAT NUMBER. 3) By electronic mail: if this is by VISA card, you can forward the information directly to me by: Compuserve Mail at 100015,551 Internet 100015.551@compuserve.com MHS MAIL@CSERVE {100015,551} -------------------- 2 There is a voice/fax switch attached. If your fax doesn't get through, please tell the person answering to permanently switch to the fax. Page 5 DMalloc ------------------------------------------------------------------------ Check appendix B for detailed information on how to send email to Compuserve, and on how to obtain a Compuserve account. Your credit card will be charged in Austrian funds. You will receive a confirmation by electronic mail or fax (if available) when your order is processed. Currency exchange will vary, but at the time of this ver- sion's release 41.00 US$ was approximately: 41.00 US$ (35+6s/h) AS 492.00 DM 68,80 The registration fee licenses one copy of DMalloc for use on any one computer at any one time. You must treat this software just like a book. An example is that this software may be used by any number of people and may be freely moved from one computer location to another, as long as there is no possibility of it being used at one location while it's being used at another. Consider it like a book, a book cannot be read by two different people at the same time. For commercial users of DMalloc, site-license or multiple license discount arrangements may be made by contacting the author at the above address. If there is an unavoidable delay in registering, note that DMalloc will continue to work unchanged after the evaluation period. Under no circumstances will DMalloc do any mischief to those who dishonestly continue to use DMalloc without registering. 1.8. Distribution Policies DMalloc and its documentation are COPYRIGHTED, and are NOT PUBLIC DOMAIN. Anyone distributing DMalloc for any kind of direct fee must first contact me at the address above for authorization. Although authorization will generally be automatically granted to distributors recognized by ASP as adhering to its guidelines for shareware distributors, notification is still required. The above restriction does not apply to the case of normal & usual connect charges on a BBS, where no other specific charge is made for obtaining a copy of DMalloc. Individual users are encouraged to pass unregistered evaluation copies of DMalloc along to their friends for evaluation. When secondarily distributed, DMalloc must be in its original compressed form and accompanied by its full on-disk documentation and other information files. The distributed software and documentation may not have been modified in any way. Page 6 DMalloc ------------------------------------------------------------------------ No secondary distributor is authorized to "register" a copy of DMalloc. Registration fees may only be sent directly to the author as outlined above in section 1.7. Note that the registration fee is exclusive of, and over and above any fees that may be charged by a secondary distributor. Page 7 DMalloc ------------------------------------------------------------------------ 2. Installation DMalloc consists of at least: PACKING.LST a list of all files in package WARRANTY.DOC IMPORTANT WARRANTY INFORMATION !README!. PLEASE READ THIS! DMALLOC.OBJ | DMALLOC.LIB | the actual software DMALLOC.H | DMCNONE.LIB | DMALLOC.BC | DMALOC09.DOC this document MAILER.DOC an optional fold up registration form 2.1. Documentation MAILER.DOC is an optional quick and handy all-in-one fold up registration form and envelope, print it by typing: COPY MAILER.DOC PRN To register, or to order a printed manual just fill it in, staple your check INSIDE it, TAPE it closed as shown, (DO NOT USE STAPLES ON THE EXTERIOR) and stamp and mail it. DMALOC09.DOC is the installation, demo program and reference documentation. It contains no special format- ting commands, can be viewed with any DOS text file viewer or editor, and it should be printable on most any printer. To print, type at the DOS command line: COPY DMALOC09.DOC PRN You should have at least 50 pages of paper ready when printing the manual. The documentation file includes "box drawings", these use certain characters which may not be available on some printers. Generally such printers replace these special characters with italicised letters. If you are able to, choose the "IBM mode" on such a printer. However, don't let the thickness of the documentation scare you. DMalloc is extremely easy to use. This manual will do its best to teach you how to use DMalloc to debug your program. Page 8 DMalloc ------------------------------------------------------------------------ 2.2. A Quick Start To quickly get an existing program running with DMalloc, relink the application together with the DMALLOC.OBJ file. The DMALLOC.LIB library must be either in the current directory or in one of the directories specified in the LIB environment variable. After linking, start the program as usually. DMalloc will pop up before the main() function is called to allow you to set the different options. Note: if an application is not compiled using the large memory model (compiler directive -AL), the linker will issue an error message and the program will not work. You must compile the application using the large memory model(3). 2.3. Where to from here? If you have never used DMalloc before, I would suggest that you either run the demo program together with reading section 3, or if do not like a walkthrough approach to learning a program, then study the reference sections. Section 3 is the walkthrough demonstration. Section 4 describes dynamic memory, what may go wrong with it and what DMalloc does to catch those bugs. Section 5 describes the windows that appear in DMalloc, and the use of the function keys. Section 6 describes how to use DMalloc for debugging. Section 7 is the reference section for the DMalloc API. 2.4. Support & Thanks Questions, comments, suggestions, and even thanks are all welcome. I am supporting this software via regular mail or fax, or alternatively (this is preferred) on CompuServe/ ZiffNet, either via electronic mail, or on the Programming Forum, Toolkits(7) section. Via CompuServe: Address messages to my UserID 100015,551 through CompuServe MAIL, or leave a message for me in ZNT:PROGRAM forum in the Toolkits(7) section. Via regular mail: Forward all support questions to Ernest Vogelsinger Hietzinger Hauptstrasse 40 c A-1130 Vienna, Austria Via fax: Call (+43)1 828 46 09 There is an automatic voice/fax switch installed. However, support can only be granted to faxed requests. -------------------- 3 Future versions may support different memory models. Page 9 DMalloc ------------------------------------------------------------------------ For registered users, support is free for 6 (six) months from date of registration. Email support continues to be free, whereas support via fax or regular mail will be charged US$ 10.-- per case. If the support case question is of interest to all registered users, it will be held free, too. Improved or new versions will be announced on Com- puServe/ZiffNet on the Programming Forum, Toolkits(7) section. Registered users will be automatically notified either via electronic mail, fax, or regular mail. My sincere thanks go out to all of those who have helped me to improve DMalloc by offering up their wish lists, suggestions and criticisms. A big "Thank you" also to Orest Skrypuch, the author of Recon , and to M.E. Stanley, the author of TappeT , for their outstanding manuals. I couldn't resist taking these two as a skeleton for this documentation. Also a very special thanks to all the brave and tireless BETA/GAMMA testers (they are all writing much better programs now)! Enjoy! Ernest Vogelsinger Page 10 DMalloc ------------------------------------------------------------------------ 3. Demonstration Program The demonstration program consists of 3 files: DEMO.BAT batch file to start the demo DEMO.TXT text echoed by the batch file DMLDEMO.EXE the actual demonstration program The demonstration program is a very simple C program that prints text to the screen, allocates some memory, and contains some "bugs" to demonstrate the miscellaneous features of DMalloc. The demo program is not intended to cover the complete functionality of DMalloc. It will give you an overview on the basic features, the windows, and the integrity checks. Note: your monitor should be in text mode, and the display width should be 80x25 or greater. If your primary display is smaller (e.g.40x25), or a graphics mode is active, DMalloc will either use an alternate monitor, if available, or im- mediately quit with an appropriate runtime er- ror. To start the demo, type DEMO [Enter] Since DMalloc pops up just before the main() function is called (and before the demo can give you any explanation), there is a batch file to help you at the very start. If you typed DMLDEMO instead of DEMO, you are not really missing something, except the batch file telling you to press [F5] to start the demo. 3.1. DMalloc Startup Have a look at the screen now. On top you should see the Information Window. This window will always be visible whenever DMalloc pops up. Its title shows the version and license number of DMalloc. The contents will always reflect why DMalloc popped up - now it tells that it's about to initialize. The Setup Window in the center of the screen can be used to modify the configuration options. For now we'll keep them as they are. Page 11 DMalloc ------------------------------------------------------------------------ On the bottom line, the function keys are displayed. This line always reflects the actual status of the function keys - if there is no action for a key, it will be empty. The keys available now are [F2] Colors modify the window colors [F4] View temporarily hide the DMalloc windows and view the program screen [F5] Go! close all open windows and continue the running program [F6] Select select the heap entries that will be displayed when the Heap Entries Window pops up [F10] Back close the topmost window and continue with the window below The [LEFT] and [RIGHT] keys are always available. Remember, you are still before the execution of main() begins. To actually start the demo program press [F5] now. Now the demo program is allocating a bunch of memory. As in a real-world C program, different source modules issue calls to malloc(). Two of them have been compiled with DMalloc info enabled, and the third without (as third party code would generally be). While allocating you will notice DMalloc popping up regularly to check the consis- tency of the heap. At any time you may use DMalloc to look at the heap. To interactively popup DMalloc, press [PrtSc]. 3.2. Heap Overview As there is no heap problem the Information Window shows that you pressed [PrtSc]. Below you see the Heap Entries Window, the main window of DMalloc. The Heap Entries Window lists all memory units that are used by the program(4), sorted by address. Use the [Up], [Down], [PgUp], [PgDn], [Home] and [End] keys to move through the list. Press [Enter] to view the contents of a unit, or use the [F7] key to see the total heap status (see next section). If you are done, press [F5] to continue with the demo. 3.3. Total Heap Status Available at any time by pressing [F7], this window tells you the total amount of used and free memory, the size of the biggest available unit (very much like the _memmax() function), and the biggest unit available from DOS (i.e. memory that has not yet been claimed by the runtime library). -------------------- 4 except units allocated with halloc(). Page 12 DMalloc ------------------------------------------------------------------------ 3.4. Detecting Heap Problems Now the demo program will do some out-of-bound writes to the allocated units. What in a real-world program would happen cannot exactly be told since it depends very much on the actual memory available at runtime, what the program would do next (regarding the heap), and much more. It could never cause any harm, it could destroy some data, it could hang the machine, or crash the operating system. With DMalloc checking the heap, these errors will im- mediately be found. When DMalloc pops up you'll notice that the Information Window tells you that there are cor- rupted units found. The bar in the Heap Entries Window will be positioned at the first corrupted unit. To quickly switch between corrupted units, use the [Left] and [Right] keys. Three types of problems are shown here: Trailing Corruption (the first unit): This is the most common problem. It occurs whenever you write more to a unit than you have allocated. Under non-DMalloc conditions this would overwrite the allocation info of the following unit. Odd/Even Corruption (the second unit): Although similar to the first case it would never cause any problem in a real-world program. When an odd-sized unit is allocated, the runtime library automatically expands the size by one byte to evenly align units. However, the unit size may have been calculated, and this one-byte overwrite would cause a Trailing Corruption if the size was even! Leading Corruption (the third unit): This would destroy the allocation info of the unit itself. It may be caused by an overwrite of the preceding unit, or by a faulty negative-index calculation into the unit itself. Press [F5] to continue the demo when you're ready. 3.5. Invalid Pointer Warning Whenever the program passes invalid values to free() and realloc(), or a far pointer is passed to _nfree(), DMalloc will inform you. The reason for that kind of error may be either uninitialized variables, duplicate freeing of the same pointer, freeing pointers to not-allocated data, and much more. Since the free() function doesn't check anything (except NULL pointers), and simply writes the allocation info, this could harm data needed elsewhere. Page 13 DMalloc ------------------------------------------------------------------------ 3.6. Determining Action, Setting Breakpoints Now press [F10] to step back to the Information Window. You'll notice two selection fields: "You can:" and "Breakpoint:". These selection fields are always present in the Information Window, unless you have pressed [PrtSc]. Press [Space] to scroll the options, and press [Tab] or [Enter] to switch between the fields. The "You can:" field offers the following possibilities: Discard: since the pointer to be freed is invalid you may discard the call to free(). Exit program: this will immediately exit the debugged program by a call to exit(). Any function specified for atexit() or onexit() processing will be called. Continue: normally continue the program. (Note: if you choose this option now, freeing the invalid pointer may hang your machine!) The "Breakpoints:" field offers the following possibilities: None: no breakpoint will be set. SoftIce: DMalloc will generate a SoftIce breakpoint (see section 6.5.1). If you have SoftIce loaded, try this option now. CodeView: set a CodeView breakpoint. Int3: set an unspecified interrupt-3 breakpoint. Interrupt 3 can be generally used to set break- points for debuggers. The breakpoints will activate the debugger at the state- ment after calling malloc. In assembler, you'll see a statement like "ADD SP, +2". In source mode, you'll see the line containing the call to malloc(). After taking your selections, press [F5] or [F10] to continue. 3.7. Null Pointer Assignments DMalloc can check for null pointer assignments. The demo will now overwrite the first few bytes of the data seg- ment. In a real-world program this will be detected at runtime end. DMalloc will detect it when it walks the heap. The same check is also available for far null pointers. Usually, far null assignments overwrite the interrupt table. When a far null assignment is detected, DMalloc will not only tell, but also undo the changes! Page 14 DMalloc ------------------------------------------------------------------------ 3.8. Fatal Heap Errors Although DMalloc detects heap overwrites, it cannot guarantee that the allocation info needed by the runtime library is not tampered with. Whenever the heap structure is completely destroyed (and a non-DMalloc program would hang), it will tell you so and gracefully exit the program. 4. Dynamic Memory and DMalloc 4.1. Dynamic Memory Layout The MSC Runtime Library allocates dynamic memory by par- titioning the heap into allocation units. Each unit is preceded by an info block containing the size and the allocation status (used/free): ───┐ ┌───────────┐ ┌─────────── ╦═╧═╧╤════════╦═╧═╧╤════════╦ ║Info│Contents║Info│Contents║ ╩════╧╤═══════╩════╧════════╩ └ malloc() pointer Since the allocation information is used to link the single units it is very critical to the integrity of the dynamic heap. Any tampering with the contents of the in- formation field will produce unpredictable results. Even though most heap corruptions are only off-by-one errors, they can be nevertheless dangerous. 4.2. DMalloc and Dynamic Memory ───┐ ┌───────────────────┐ ┌─ ╦═╧═╧╤═══╤════════╤═══╦═╧═╧╤ ║Info│Dml│Contents│Dml║Info│ ╩════╧═══╧╤═══════╧═══╩════╧ └ malloc() pointer Here's where DMalloc comes in - it copes with heap problems is two ways: - it surrounds any allocated unit with small buffers containing initialized data to track those off-by- some errors, and to provide that they don't really corrupt the heap (allocation overhead = 2x4 bytes) - it tracks all allocated units in a tag table to hold additional information on that unit (tag table entry = 10 bytes): - it provides the source file name and the line num- ber where this unit has been allocated - it allows to "mark" any unit so freeing and real- locating will let DMalloc pop up - it can check the parameters for free() and realloc() calls Page 15 DMalloc ------------------------------------------------------------------------ 4.3. Tracking the Functions One of the most convenient features of DMalloc is that it automatically tracks calls to the malloc functions, even without recompiling the code. How does this work? On startup, before main() is called, DMalloc patches the entry points to the malloc functions. When they are called later, control will automatically be passed to the DMalloc code. The following functions will be tracked: _fmalloc (this is where the malloc() label points to in the large memory model) calloc realloc _ffree (this is where the free() label points to in the large memory model _nmalloc _nfree These functions are referenced throughout the manual as "malloc functions". Calling one of them will automatically activate DMalloc. 4.4. Checking the Heap DMalloc checks the heap by calling the _nheapwalk() function for the near and the _fheapwalk() function for the far heap and testing the results against its tag table. Whenever a corrupted unit is detected it will pop up. This heap walk can only be done when DMalloc gets control: - one of the above functions is called - each time DMalloc pops up - using the DMalloc programming API Usually it is not necessary to check the heap on every call to a malloc function. The frequency of the automatic check can be changed at runtime in the Setup Window (see section 5.4). 4.5. Types of Heap Corruption A program can overwrite the allocation information fields in both directions: upwards, destroying the info field of successive ("trailing") units, or downwards, destroying its own ("leading") information field. DMalloc detects both kinds of errors. Refer also to section 5.6, Heap Entries Window. 4.5.1. Lead Corruption Lead Corruption occurs when the allocation information field preceding the unit is destroyed. This may be caused by either faulty downward indexing at the corrupted unit itself, or by out-of-bounds writes to the preceding unit. Page 16 DMalloc ------------------------------------------------------------------------ 4.5.2. Trail Corruption Trail corruption occurs when the allocation information field following the unit is destroyed. This is most likely caused by out-of-bounds writes to the unit. 4.5.3. Odd/Even Problem Odd/Even corruption is a special case of Trail corruption. Regardless if the allocated size is even or odd, the mal- loc functions always pad the unit size to be even(5). Thus, writing one byte more than allocated would never cause a problem, and would never be detected. DMalloc catches this kind of problem as well, since the size could be a calculated value, and the off-by-one access would cause a Trail Corruption if it was even. 4.5.4. Mavericks Mavericks are allocated units that DMalloc doesn't know about, but detects when walking the heap. Since there is no "legal" way of allocation bypassing DMalloc, the occur- rence of Mavericks is a clear sign that stray pointers corrupted the heap. Mostly Mavericks will be found when DMalloc detects an unrecoverable heap failure, and thus would terminate the program. 4.6. Null Pointer Assignments The MSC runime library provides a way to detect Null pointer assignments at the end of the program. Since this is a bit late to tell where it could have happened, DMal- loc can check the NULL region whenever it checks the heap (see section 5.6.3 how to activate this feature). It will pop up whenever it detects a change in the contents of the NULL region. Note: the runtime library provides 40h bytes at the be- ginning of the data segment to allow for checking against Null pointer assignments. You may disable this feature to save data and code space by pro- viding a "int _nullcheck(void);" function retur- ning 0(6). In this case, the linker will not pull the constant NULL segment in, and DS:0 assign- ments are perfectly valid since it's the pro- gram's data. DMalloc is aware of this and disables the (near) Nullcheck feature. -------------------- 5 This grants all allocated units to be aligned at an even address. 6 The _nullcheck() function must reside in the _TEXT segment Page 17 DMalloc ------------------------------------------------------------------------ 4.7. Far Null Pointer Assignments Compiling for far data, NULL pointers will not point to the data segment NULL region but to the interrupt table. Assignments to FAR NULL pointers normally hang the machine, since interrupt pointers are destroyed. DMalloc may check the FAR NULL region (see section 5.6.3 how to activate this feature). Whenever an unknown change(7) is detected, DMalloc will reset the contents of the interrupt table to a known state, and pop up. Note: This is not a "lifebelt". Since an interrupt may be called before DMalloc detects the change, it may still crash the machine(8). 4.8. Watchpoints DMalloc provides a way to notify you whenever a specific allocation unit is to be reallocated or freed. Marking an allocated unit (see section 5.6.3) sets a Watchpoint that will direct DMalloc to popup whenever that unit is to be freed or reallocated. 4.9. Savepoints DMalloc can remeber certain allocated units from one ses- sion to the next, where it may pop up when a remembered unit has been allocated. This is automatically done with corrupted units. You may set Savepoints (see section 5.6.4) on allocated units to save them for the next ses- sion, similar to a corrupted unit. When DMalloc pops up because a remembered unit has just been allocated, it will tell if it has been a corrupted or a saved entry. -------------------- 7 DMalloc will know when the operating system changes an interrupt. 8 Interrupts called frequently are 08h and 1Ch (timer), 09h and 16h (keyboard), 10h (video), 21h (DOS), and some more. However, interrupts 00h to 07h (the first two paragraphs) are not frequently called. Page 18 DMalloc ------------------------------------------------------------------------ 5. DMalloc In Detail Regardless of the situation, two elements of the user interface will always be present when DMalloc is up: the Function Key display, and the Information Window. 5.1. About DMalloc Windows DMalloc uses three window types: - Informational windows containing only text. You can- not scroll or modify data - Data entry windows. You may enter or modify data at various entry fields - A List box type window Three types of data entry fields are available: - Ascii data entry to enter text - Numeric data entry to enter numeric values. You may use the [+], [Space] or [-] keys to let it count up or down. - Selection entry to select from certain available values. Press the [Space] key, or the first letter of the selection of your choice (e.g. [C] to select "Co- ntinue"). After entering or changing data in an data entry window, you may confirm the changes by pressing [F5] or [F10], or undo them by pressing [Esc]. 5.2. Function Keys The function keys that are currently available are always displayed at the bottom of the screen. Keys that are always available: [F4] View Hide the DMalloc screen to show the screen of the debugged program (if an alternate monitor is used (see section 5.4.8), this key is unavailable). [F5] Go! Close all open DMalloc windows (as if pressing [F10]) and immediately continue the interrupted program [F10] Back Close the topmost window and continue with the next below. If data has been entered in the active window, it is saved. [Esc] Undo Close the topmost window and continue with the next below. If data has been entered in the active window, changes are discarded. Page 19 DMalloc ------------------------------------------------------------------------ Keys that open a window, or perform an action: [F2] Setup Window -> Colors Window [Sh] +[F2] Repair unit [Ctl]+[F2] Repair all [F3] Heap Entries Window -> Dump Window -> Edit Contents [F6] Selection Window [F7] Heap Status Window [F9] Set/Clear Watchpoint [Ctl]+[F9] Set Watchpoint at all visible units [Alt]+[F9] Toggle Watchpoint at all visible units [Sh] +[F9] Clear Watchpoints at all visible units 5.3. Information Window ╔╡ DMalloc 1.00 (MSC 5.10, 6.00) (c) 1990-1992 E.Vogelsinger (UNREGISTERED)╞╗ ║ DMalloc was triggered by the host program (file test.c, line 68). ║ ║ Program suspended for heap debugging. ║ ║ You can: Continue Breakpoint: None 1 new heap problem ║ ╚═══════════════════════════════════════════════════════════════════════════╝ The title bar shows the DMalloc version and the serial number. The text in the window describes the exact reason for DMalloc to pop up. If a new heap corruption is detected (i.e. corrupted entries that have not yet been displayed), the total num- ber of the new detections is displayed in the lower right corner. Two selection fields are present at the bottom: 5.3.1. "You can" - Select the Next Action Continue will continue the debugged program. Exit program will exit the program as soon as you leave DMalloc. Discard action will discard the action that caused DMalloc to pop up. This choice is only available if - an invalid pointer was passed to realloc() or free() - a far pointer was passed to _nfree() - a Watchpoint has matured (see section 4.8) Page 20 DMalloc ------------------------------------------------------------------------ 5.3.2. "Breakpoint:" This field can be used to set breakpoints to debuggers (see section 6.5). None will not set any breakpoint SoftIce generates a breakpoint for the Soft-ICE debug- ger CodeView generates a breakpoint for the CodeView debug- ger Int3 generates an unspecified INT 03h instruction Note: Both selection fields are only present if DMalloc loc automatically popped up. Pressing the [PrtSc] key to activate DMalloc is an asynchronous action. The state of the operating system or a debugger cannot be predicted at this moment, so it could be fatal if DMalloc would try to break into the de- bugger, or to exit the running program. 5.4. Setup Window ╔╡ Setup ╞════════════════╗ ║ ║ ║ Alert on problem : Yes ║ ║ Popup on saved : No ║ ║ Cycles for popup : 0 ║ ║ Heap check cycles: 100 ║ ║ Popup for file ║ ║ line : 0 ║ ║ Startup screen : Yes ║ ║ Shutdown screen : Yes ║ ║ Alternate monitor: No ║ ║ Number of handles: 5000 ║ ║ ║ ╚═════════════════════════╝ The Setup Window allows to modify the behaviour of DMalloc at runtime. The Setup Window is always available by pres- sing [F2]. All setup options will be permanently stored in the con- figuration file (see section 5.10). Page 21 DMalloc ------------------------------------------------------------------------ 5.4.1. Alert on problem (Default: Yes) Specifies if DMalloc should pop up if heap corruption is detected. Entering "No" lets DMalloc keep quiet even if it detects newly corrupted allocation units. However, there are situations when DMalloc will pop up regardless of this switch: - DMalloc is about to initialize (except switched off, see section 5.4.6) - an unrecoverable heap failure has been detected a unit that has been found corrupted during the last session has been allocated, and the "Popup on saved" switch (see section 5.4.2) is set to "Corrupt" or "Both" - a unit marked for save (see section 5.6.4) has been allocated, and the "Popup on saved" switch is set to "Saved" or "Both" - the popup cycle count has elapsed (see section 5.4.3) - the source file/line specified as popup reason is executed (see section 5.4.5) - [PrtSc] has been pressed - the DML_Trigger() API function was executed (see section 7) - the program has finished, and DMalloc is about to shutdown (except switched off, see section 5.4.7) Regardless of this switch, a small "Please wait" sign will always pop up whenever DMalloc checks the heap. 5.4.2. Popup on saved (Default: No) DMalloc remembers units that have been found corrupted, and those marked for save (see section 5.6.4) during the last debug session. You may selectively specify which units you want to monitor: No disables this feature Corrupt will pop up only for those units that have been corrupted in the last session Saved will pop up only for those units marked for save Both will popup for both types 5.4.3. Cycles for popup (Default: 0) Regardless of heap corruption, DMalloc can be directed to pop up after a certain number of calls to the malloc functions have been made. Specify 0 if you do not want cycled popup. Note: the internal cycle counter is reset whenever DMalloc pops up. Page 22 DMalloc ------------------------------------------------------------------------ 5.4.4. Heap check cycles (Default: 100) Specifies after how many calls to the malloc functions DMalloc will check heap integrity. Although heap checking is quite fast, it is not necessary to check on any call. Specify 0 if you do not want any automatic checking. Note: the heap will always be checked before DMalloc pops up, regardless of this setting. 5.4.5. Popup for file/line (Default: blank/0) Entering a source file name will direct DMalloc to pop up whenever a call to the malloc functions is made by this source file. Entering a line number will restrict it to this specific source line, line number 0 will allow to popup at any call from this file. Note: the source file in question must be compiled with DMalloc information to enable this feature. If a wrong file name or a line number that does not contain a call to the malloc functions is entered, DMalloc will not pop up, even if the line is executed. 5.4.6. Startup screen (Default: Yes) Normally, DMalloc pops up at the beginning, just before calling main(). You may disable the Startup Window by specifying "No". 5.4.7. Shutdown screen (Default: Yes) Normally, DMalloc pops up at the end, after the atexit() or onexit() functions have been called. You may disable the Shutdown Window by specifying "No". 5.4.8. Alternate monitor (Default: No) You may use an alternate monitor for DMalloc by selecting "Yes". DMalloc will use the selected monitor when it pops up the next time. There are situations where DMalloc will use the alternate monitor regardless of this selection: - your program switched to graphics mode - your program switched to a text mode with a different horizontal or vertical resolution than at initialization time If you do not have an alternate monitor, and DMalloc would require it, it will not pop up until the display is reset for DMalloc's needs. Page 23 DMalloc ------------------------------------------------------------------------ Note: if, at initialization time, the display is either in graphics mode, or the text mode resolution is below 80x25, DMalloc will exclusively use the alternate display. If, in that case, you do not have an alternate display, DMalloc will immediately terminate at startup, issuing an appropriate runtime error. Note: if you do not have an alternate monitor, or the the alternate monitor is exlusively used by DMalloc, this field will not be accessible. 5.4.9. Number of handles (Default: 5000, Maximum: 10900) As mentioned in section 4.2, DMalloc allocates a tag table to track the allocated units. This entry specifies the size of the tag table. As this value is needed at initialization time, this field is not accessible later. Note: If DMalloc runs out of handles, it will abort the program and issue an appropriate runtime error. 5.5. Colors Window ╔╡ Window Colors╞══════════════════════╗ ║ ║ ║ Notice : 3E Frame 3F Contents ║ ║ Heap : 3E Frame 30 Contents ║ ║ Dump : 3E Frame 30 Contents ║ ║ Selection : 3E Frame 38 Contents ║ ║ Status : 3E Frame 31 Contents ║ ║ Color : 3E Frame 30 Contents ║ ║ Setup : 3E Frame 30 Contents ║ ║ Wait message : 3E Frame 30 Contents ║ ║ Function Keys: 70 Contents ║ ║ ║ ╚══════════════════════════════════════╝ The Colors Window allows to customize the screen colors of DMalloc. It is available only from the Setup Window by pressing [F2]. For each window there are two entries: for the window frame, and for the window contents. The fields are selec- tion fields that can be scrolled by pressing the [Space] key. To switch between the fields, press the [Tab] or the [Enter] key. DMalloc maintains two color tables, one for color and one for monochrome display. The Colors Window will display the table for matching the active display type. The color options will be permanently stored in the con- figuration file (see section 5.10). After colors have been changed they will be reflected whenever a window comes "on top" again. Page 24 DMalloc ------------------------------------------------------------------------ 5.6. Heap Entries Window ╔╡ Heap entries ╞══════════════════════════════════════════════╗ ║▒Block▒▒▒▒▒▒▒▒▒▒▒▒▒▒Owner▒▒line▒▒▒▒Size▒▒▒▒▒▒▒Lead▒▒▒▒▒▒Trail▒║ ║ 41CE:EAEC module1.c 175 86 OK OK ║ ║ 41CE:EB4C module2.c 24 77 OK OK ║ ║ 41CE:EBA4 ??unknown 43 OK OK ║ ║▒41CE:EBDA▒▒▒▒▒▒module1.c▒▒▒175▒▒▒▒▒▒86▒▒▒▒▒▒▒▒▒OK▒▒CORRUPTED▒║ ║ 41CE:EC3A module2.c 24 77 OK OK ║ ║ 41CE:EC92 ??unknown 43 CORRUPTED OK ║ ║ 41CE:ECC8 module1.c 175 86 OK OK ║ ║ 41CE:ED28 module2.c 24 77 OK ODD-EVEN ║ ║ 41CE:ED80 ??unknown 43 OK OK ║ ║ 41CE:EDB6 module1.c 175 86 OK OK ║ ╚══════════════════════════════════════════════════════════════╝ The Heap Entries Window displays a list of all allocated units. Usually, the Heap Entries Window is always visible(9). If not, you may activate it by pressing [F3]. You may scroll through the heap list using the [Up], [Down], [PgUp], [PgDn], [Home], and [End] keys. The current position in the list is marked by an inverted bar. Each line represents an allocated unit, or another part of the programs memory. As shown above, the display contains (from left to right) Block the (far) address of the allocated unit. This address was returned by the malloc functions. Owner the source file that allocated this unit. If the owning source has not been compiled with DMalloc information, "??unknown" is displayed. line the source line if the owner file is available. Size the allocated size in bytes. Lead the status of the leading control block (see section 4.2). Possible values are: OK the leading control block is OK CORRUPTED the leading control block has been overwritten Trail the status of the trailing control block (see section 4.2). Possible values are: OK the trailing control block is OK CORRUPTED the trailing control block has been overwritten ODD/EVEN an off-by-one error on an odd-sized allocation unit has been detected (see section 3.4) -------------------- 9 Unless you stepped back to the Information Window by pressing [F10] Page 25 DMalloc ------------------------------------------------------------------------ Other entries that may be visible belong to preallocated data space and the Far Null region: ║ 0000:0000 256 OK FAR_NULL ║ ║ 37DD:0000 4112 OK FAR_DATA ║ ║ 38DE:0000 5120 OK FAR_BSS ║ ║ 3A1E:0000 16726 OK _DATA ║ ║ 3A1E:4156 906 OK BSS ║ ║ 3A1E:742C 13716 OK DMALLOC ║ ║ 41AC:0128 132 OK STARTUP ║ FAR_NULL The first 256 bytes of the interrupt table. As a special feature for far pointers, DMalloc can track Far Null Pointer assignments (see section 4.7). To have Far Null checking enabled, this entry must be "tagged" (see section 5.6.3). FAR_DATA All pre-initialized data that doesn't fit into the data segment. Listed for completeness. FAR_BSS All non-initialized data that doesn't fit into the data segment. Listed for completeness. _DATA The data segment containing pre-initialized data(10). DMalloc can track Null pointer as- signments (see section 4.6). To have Null check- ing enables, this entry must be "tagged" (see section 5.6.3). BSS All non-initialized data belonging to the data segment(11). Listed for completeness. DMALLOC Memory allocated by DMalloc for its own purpose. One unit (on the near heap) is used for screen buffers, the others are used by the tag table. STARTUP Present only with MSC 6.+. Two units get al- located before DMalloc initializes. They contain a copy of the environment, and a bunch of pointers. Listed for completeness. You may freely select which type of entries you want to see. Refer to section 5.7, Selection Window. -------------------- 10 Actually the _DATA entry consists of four consecutive segments: NULL, _DATA, CONST, and MSG. Since they all contain pre-initialized data they are gathered in this entry. They all belong to DGROUP and are ad- dressed through the DS or SS register. 11 Since the BSS segment is part of DGROUP it has the same segment address as the _DATA entry. Page 26 DMalloc ------------------------------------------------------------------------ 5.6.1. Detecting Corrupted Entries Whenever DMalloc detects a problem it will pop up. Regardless of the popup reason displayed in the Infor- mation Window, the heap is checked completely, and the number of newly found corruptions blinks in the Infor- mation Window (see section 5.3). Corrupted Entries are always displayed in high-intensity color (refer to section 4.5 for different corruption types). When they are con- sidered new they will blink. You can quickly move between corrupted entries by pressing the [Left] or [Right] keys. An allocation unit that has been found corrupted will always be saved in the configuration file (see sections 5.10 and 5.4.2). 5.6.2. "Repairing" Corrupted Entries To clear the "corruption" marks at an entry, you can press [Shift]+[F2] to repair the currently active unit, or [Ctl]+[F2] to repair all. Repairing units will reset the corruption flags, and also reset the contents of the surrounding control blocks (see section 4.2). Repairing NULLCHECK at the _DATA entry will not reset the contents of the Null region but only clear the corruption flag. Repairing NULLCHECK at the FAR_NULL entry will only clear the corruption flag. The contents of the Far Null region are automatically reset whenever this type of corruption is encountered. Note: when repairing a corrupted unit, DMalloc will reset the control block contents. If the program relies on these contents (outside of the al- located unit) don't repair but exit the program and correct the error. Note: Having repaired a unit, it will not be remem- bered (see section 5.10). 5.6.3. Watchpoints ("Tags") Watchpoints are used to activate DMalloc whenever a watched unit is to be freed or reallocated (see section 4.8). Setting a Watchpoint on the FAR_NULL or _DATA seg- ment will enable checking for Null pointer assignments. Active Watchpoints are displayed as "Tags" () at the watched entry. You can quickly move between tagged entries by pressing the [Ctl]+[Left] or [Ctl]+[Right] keys. To set or clear Watchpoints, press [F9] or [T] to tag an entry [F9] or [U] to untag an entry [Ctl]+[F9] or [Ctl]+[T] to tag all visible entries [Alt]+[F9] to toggle all visible tags [Shift]+[F9] or [Ctl]+[U] to untag all entries Page 27 DMalloc ------------------------------------------------------------------------ 5.6.4. Savepoints DMalloc allows to remember allocation units between debug sessions (see section 4.9). This is done automatically for corrupted units. Optionally, you may specify some units to be saved by simply pressing [S]. Whenever DMalloc allo- cates a saved unit again it will pop up. Unlike remembering a corrupted unit, a Savepoint is sticky i.e. you have to clear it by pressing [S] or it will be kept for that unit (as long as it gets allocated again). Active Savepoints are displayed with an 'S' at the entry. 5.7. Selection Window ╔╡ Select ╞═══════════════╗ ║ ║ ║ Allocated units : Yes ║ ║ Tagged only : No ║ ║ Nullptr. areas : Yes ║ ║ Data segments : No ║ ║ System entries : No ║ ║ Owner file : ║ ║ line : 0 ║ ║ ║ ╚═════════════════════════╝ The Selection Window selects which entries will be displayed in the Heap Entries Window. It is available only from the Heap Entries Window by pressing [F6]. Changing the selection will immediately be reflected by the Heap Entries Window. Allocated Units (Default: Yes) Selects all allocated units except those marked DMALLOC and STARTUP. Tagged only (Default: No) If Yes, only those entries that are currently tagged will be shown. Nullptr. areas (Default: Yes) If Yes, the FAR_NULL and _DATA entries will be shown. Data segments (Default: No) If Yes, all data segments (FAR_NULL, FAR_DATA, FAR_BSS, _DATA, BSS) will be shown. If No, the FAR_NULL and _DATA segments may be shown when "Nullptr areas" is "Yes". System entries (Default: No) If Yes, DMalloc and STARTUP entries will be shown. Owner file/line (Default: blank/0) If a source file is entered here, only those entries belonging to the specified source file/line will be shown. Page 28 DMalloc ------------------------------------------------------------------------ 5.8. Dump Window ╔╡ Dump 55DE:0000 ╞═══════════════════════════════════════════════════════╗ ║ 55DE0: 00 00 00 00 00 00 00 00-4D 53 20 52 75 6E 2D 54 ........MS Run-t ║ ║ 55DF0: 69 6D 65 20 4C 69 62 72-61 72 79 20 2D 20 43 6F ime Library - Co ║ ║ 55E00: 70 79 72 69 67 68 74 20-28 63 29 20 31 39 39 30 pyright (c) 1990 ║ ║ 55E10: 2C 20 4D 69 63 72 6F 73-6F 66 74 20 43 6F 72 70 , Microsoft Corp ║ ║ 55E20: 00 00 00 00 00 00 00 00-00 00 00 00 00 00 00 00 ................ ║ ║ 55E30: 00 00 00 00 00 00 00 00-00 00 00 00 00 00 00 00 ................ ║ ║ 55E40: 00 00 00 00 00 00 00 00-00 00 00 00 00 00 00 00 ................ ║ ║ 55E50: 00 00 00 00 00 00 00 00-00 00 00 00 00 00 00 00 ................ ║ ║ 55E60: 00 00 00 00 00 00 00 00-00 00 00 00 00 00 00 00 ................ ║ ║ 55E70: 00 00 00 00 00 00 00 00-00 00 00 00 00 00 00 00 ................ ║ ║ 55E80: 00 00 00 00 00 00 00 00-00 00 00 00 00 00 00 00 ................ ║ ║ 55E90: 00 00 00 00 00 00 00 00-00 00 00 00 00 00 00 00 ................ ║ ║ 55EA0: 00 00 00 00 00 00 00 00-00 00 00 00 00 00 00 00 ................ ║ ║ 55EB0: 00 00 00 00 00 00 00 00-00 00 00 00 00 00 00 00 ................ ║ ╚═════════════════════════════════════════════════════════════════════════╝ The Dump Window allows you to view and edit the contents of a memory unit. It is available from the Heap Entries Window by pressing [F3] or [Enter]. The Window Title displays the unit address. The contents are shown in hex and ASCII format. The column to the far left shows the (incrementing) 20-bit address(12). The size of the Dump Window may vary, depending on the actual size of the memory unit. The maximum size is 16 paragraphs (or 256 bytes). If the size of the unit is big- ger you may scroll the Dump Window using the [Up], [Down], [PgUp], [PgDn], [Home], and [End] keys. 5.8.1. Editing Data Press [F3] to edit the Dump Window contents. When in Edit mode, a block cursor appears at the location where data is to be modified. Using the [Tab] key you can toggle between Hex Mode and Ascii Mode. Use the [Left], [Right], [Up], [Down], [Home], and [End] keys to move the cursor. Modified data will be displayed in high intensity color. Pressing [F5] or [F10] will write the modified data back, pressing [Esc] will ignore the changes. Note: Edit Mode is not available at the memory units marked FAR_NULL and DMalloc, since their con- tents are critical to the system. Note: Modifying any data between offset 00h and offset 40h will result in a NULLCHECK warning and the appropriate runtime error at program ter- mination. -------------------- 12 In Real Mode, the highest memory address available is FFFF:FFFF, or as absolute address 10FFEF. It needs 21 bits to form this number. However, this address should never be a malloc unit. Page 29 DMalloc ------------------------------------------------------------------------ 5.9. Heap Status Window ╔╡ Heap Status ╞════════════════╗ ║ Units Bytes ║ ║─────────────────────┬─────────║ ║ │ ║ ║ Allocated: 3 │ 33860 ║ ║ Free : 1 │ 4292 ║ ║ biggest on heap │ 4292 ║ ║ biggest in DOS │ 139728 ║ ║ │ ║ ╚═══════════════════════════════╝ The Heap Status Window is available at any time by pres- sing [F7]. The following information is presented: Allocated how many units are currently allocated, and the memory size that is occupied by them. Free how many free units are currently available,and the total size of all free units. biggest on heap the size of the biggest free unit in bytes(13). biggest in DOS the biggest continuous memory block cur- rently available from DOS(14). 5.10. The Configuration File All options from the Setup, Colors, and Selection Window are permanently stored in a configuration file. The name of the configuration file will be the same name as the name of the debugged EXE file, with extension .DMC(15). If, by chance, there is another file with the same name, DMalloc will not attempt to read its contents at initiali- zation time, and will not overwrite it when terminating. All allocated units that have been found corrupted are stored in the configuration file, even if they have been freed or reallocated again. Also units marked 'S' for save will be stored. DMalloc tries to be clever when storing pointers: the segment portion of the pointer is somehow normalized to allow for different runtime environments, where the program may be located somewhere else in memory. However, if the size of the data segments has changed, or the allocation sequence is different, there is no way for DMalloc to detect when saved pointers are allocated, since they may be located somewhere else. -------------------- 13 The similar _memmax() function reports on the near heap only. DMalloc reports on both near and far heap. 14 The total size of free memory may vary from the maxi- mum size, depending on the respective environment. 15 For example, for the TEST.EXE program, DMalloc would create a TEST.DMC configuration file. Page 30 DMalloc ------------------------------------------------------------------------ 6. How to use DMalloc for Debugging There are different levels of integration to the debugged program. You may simply link DMalloc to the program, recompile some source, or even call the DMalloc API from within the program. 6.1. Linking DMalloc to the Program This is the most simple way to integrate DMalloc. Relink the program with an additional object, DMALLOC.OBJ. You do not need to specify the DMALLOC.LIB library to the linker as long as it can be found in one of the directories specified in the LIB environment variable. This will integrate the whole DMalloc functionality except that DMalloc cannot know where units are allocated. 6.2. Recompiling If you want to know which source file allocated which units, you may recompile those source files where the malloc functions are called. First, define the _DMALLOC switch. You may either add -D_DMALLOC to the compiler directive in the make file, or add the line #define _DMALLOC to the source file. Next, include DMALLOC.H into the source by adding the following line to the source file: #include <DMALLOC.H> Third, recompile the source, and link the program as specified above. You still need DMALLOC.OBJ to be linked to the program. Note: The switch _DMALLOC needs to be defined before DMALLOC.H is included. 6.3. Calling the DMalloc API DMalloc provides API functions that can be called from the program (see section 7). The API functions allow to let DMalloc check the heap, popup DMalloc, temporarily or permanently modify the setup, set watchpoints or savepoints on pointers, generate debugger breakpoints, and to disable or enable DMalloc for special purposes. Please see the API reference for detailed discussion. Page 31 DMalloc ------------------------------------------------------------------------ 6.4. DMalloc and Spawn All exec.. functions and the system() function can be used together with DMalloc. Dmalloc will automatically detect when another process is being executed, and disable it- self. 6.5. DMalloc and Video DMalloc is compatible with the RLSI (Relocated Screen In- terface) specification. If you have installed a DOS memory manager (e.g. DesqView, or Memory Commander), that relo- cates the video buffer, DMalloc will work as well. Note: Your program needs to rely on RLSI as well, if it's accessing the video buffer, since the RLSI host will not trap video buffer accesses after RLSI has been initialized. 6.5.1. Calling RLSI RLSI is called via interrupt 10h (video interrupt): union REGS regs; struct SREGS sregs; regs.x.ax = 0xFE00; // RLSI function code regs.x.di = ofsVPage; // video page offset, usually 0 sregs.es = segVBuffer; // video buffer, usually B800 or B000 int86x(0x10, ®s, ®s, &sregs); ofsVPage = regs.x.di; // get the RLSI values segVBuffer = sregs.es; 6.6. DMalloc and Debuggers DMalloc allows to set debugger breakpoints. Whenever DMal- loc pops up (except [PrtSc] has been pressed) you may di- rect it to set a debugger breakpoint (see section 5.3.2). The debugger will receive control at the statement immedi- ately following the call to the malloc function (i.e. in your code instead of code belonging to the runtime li- brary, or DMalloc). 6.6.1. Soft-ICE Soft-ICE is a resident protected-mode debugger from Nu- Mega Technologies, Inc. It can be used to debug operating system code, high frquent interrupt code, TSR programs, and much more. Soft-ICE breakpoints are sticky. When Soft-ICE gets control you will see a message like this: Breakpoint generated by DMalloc (remove with BC 0) If you do not clear that breakpoint, Soft-ICE will always pop up at the very same location. Note: It will do no harm trying to set a Soft-ICE breakpoint without having Soft-ICE loaded. Page 32 DMalloc ------------------------------------------------------------------------ 6.6.2. CodeView Contrary to a Soft-ICE breakpoint, CodeView breakpoints are not sticky. CodeView will get control at the statement after the malloc function call, but no permanent break- point will be set. 6.6.3. Other Debuggers Every debugger will get control when interrupt 03h is executed. DMalloc provides that unspecific method for other debuggers. Note: CodeView will also get control at this type of breakpoint, Soft-ICE will not by default. 6.7. DMalloc and Bounds-Checker Bounds-Checker is a 386-based utility to detect out-of- bounds memory accesses while running a DOS program. It gives the same type of memory protection as a protected mode operating system. DMalloc and Bounds-Checker are ideal companions. You can use Bounds-Checker to verify segment-based integrity, and DMalloc to assure the in- tegrity of the heap contents. Bounds-Checker can be directed to allow access to memory locations that are protected by default(16) by specifying exceptions in an exception file. Since DMalloc accesses some restricted locations, Bounds-Checker must know about it or it would complain. An exception file for Bounds- Checker comes with the DMalloc package (DMALLOC.BC). Simply copy the contents of this file to your exception file, and Bounds-Checker will accept the liberties DMalloc takes. -------------------- 16 Typical candidates for exceptions are the code segment for routines written in assembler, the Bios area beginning at segment 40h, or the video buffer at B000h and B800h. Page 33 DMalloc ------------------------------------------------------------------------ 7. Programming API The DMalloc API functions are defined and prototyped in the DMALLOC.H include file. If the _DMALLOC switch is defined the functions will be accessed. If the _DMALLOC switch is undefined the functions are defined as "empty statements" so the source file will compile without errors. 7.1. Removing DMalloc API Calls Even without recompiling you can remove DMalloc code from the program by replacing the DMALLOC.LIB library with DMCNONE.LIB. This library provides dummy entries for all functions, and reroutes the DMalloc malloc function calls to the runtime library. void pascal DML_Trigger (void) Purpose: Directs DMalloc to pop up. Parameters: none Return: void Remarks: Actually this is a macro calling DM_Trigger$(__FILE__, __LINE__). void pascal DML_Check (void) Purpose: Directs DMalloc to check the heap. DMalloc will pop up if a problem is found unless supressed in the setup (see section 5.4.1). Parameters: none Return: void Page 34 DMalloc ------------------------------------------------------------------------ void pascal DML_Setup (fAlert, fSaved, usPopCycles, usCheckCycles, pszOwner, usLine) Purpose: Modifies switches from the Setup Window (see section 5.4). Parameters: unsigned fAlert SET_ON "Yes" SET_OFF "No" SET_UNCHANGED keep current value unsigned fSaved SET_CORRUPTED "Corrupted" SET_SAVED "Saved" SET_BOTH "Both" SET_OFF "No" SET_UNCHANGED keep current value unsigned usPopCycles lets DMalloc pop up regularly after this number of calls have been done unsigned usCheckCycles lets DMalloc check the heap after this number of calls have been done char *pszOwner lets DMalloc pop up whenever this file calls the malloc functions. Specify PSZ_UNCHANGED to keep the current value unsigned usLine narrows popup for a source file to this source line Specify SET_UNCHANGED to keep the current value Return: void void pascal DML_Select (fMalloc, fMarked, fNull, fData, fSystem, pszOwner, usLine) Purpose: modifies switches from the Selection Window (see section 5.7). For the logical switches you may specify either SET_ON, SET_OFF, or SET_UNCHANGED. Parameters: unsigned fMalloc show allocated units unsigned fMarked show only tagged units unsigned fNull show both NULL segment entries unsigned fData show the data segment entries unsigned fSystem show the system entries unsigned pszOwner show only entries owned by that source file Specify PSZ_UNCHANGED to keep the current value unsigned usLine narrows the source file range to this source line Specify SET_UNCHANGED to keep the current value Return: void Page 35 DMalloc ------------------------------------------------------------------------ void pascal DML_SaveState (pSaveBuffer) Purpose: Save the current DMalloc state to a save buffer. Parameters: void *pSaveBuffer Pointer to the buffer where DMalloc should save its setup. Return: void Remarks: The setup contains all switch settings from the Setup Window, the Selection Window, and the Colors Window. You may use the handy DML_SAVEAREA macro to define a local (or global) variable. If you are allocating a save buffer be sure to provide at least DML_SAVESIZE bytes. void pascal DML_RestoreState (pSaveBuffer) Purpose: Restore a previously saved DMalloc state. Parameters: void *pSaveBuffer Pointer to the buffer where DMalloc saved its setup. Return: void Remarks: The setup contains all switch settings from the Setup Window, the Selection Window, and the Colors Window. You may use the handy DML_SAVEAREA macro to define a local (or global) variable. If you are allocating a save buffer be sure to provide at least DML_SAVESIZE bytes. There is no error correction. You must not use a buffer that has not been previously filled by the DML_SaveState() function. Page 36 DMalloc ------------------------------------------------------------------------ unsigned pascal DML_Watchpoint (pUnit, fOnOff) Purpose: Set or clear a Watchpoint Parameters: void *pUnit Pointer to an allocated unit. You may specify FAR_NULLCHECK or DATA_NULLCHECK to en- or disable Null pointer assignment checks unsigned fOnOff SET_ON to switch Watchpoint on SET_OFF to switch Watchpoint off SET_UNCHANGED to keep it. Return: A nonzero value indicates that the Watchpoint has been set or cleared. A zero value indicates that the pointer passed to that function could not be found in DMalloc's tag table. Specifying SET_UNCHANGED may be used to verify if the pointer has been allocated by the malloc functions. Remarks: without the _DMALLOC switch defined, this function will always return nonzero. unsigned pascal DML_Savepoint (pUnit, fOnOff) Purpose: Set or clear a Savepoint Parameters: void *pUnit Pointer to an allocated unit. unsigned fOnOff SET_ON to switch Savepoint on SET_OFF to switch Savepoint off SET_UNCHANGED to keep it. Return: A nonzero value indicates that the Savepoint has been set or cleared. A zero value indicates that the pointer passed to that function could not be found in DMalloc's tag table. Specifying SET_UNCHANGED may be used to verify if the pointer has been allocated by the malloc functions. Remarks: without the _DMALLOC switch defined, this function will always return nonzero. void pascal DML_Breakpoint (fType) Purpose: Trigger a debugger breakpoint Parameters: unsigned fType BPT_SOFTICE to set a Soft-ICE breakpoint, BPT_CODEVIEW for a CodeView BPT_INT3 for a generic Int03 breakpoint. Return: void Remarks: The debugger will get control at the statement following the call to DML_Breakpoint(). Page 37 DMalloc ------------------------------------------------------------------------ void pascal DML_Disable (void) Purpose: Completely disables DMalloc Parameters: none Return: void Remarks: Normally this function needs not to be called. It completely disables DMalloc, and after re- enabling it, any memory unit allocated in the meantime will show up as MAVERICK error, since DMalloc didn't know about it. Disabling increments a counter. You need to call the enable function as often as you have called the disable function. void pascal DML_Enable (void) Purpose: Enables DMalloc after disabling Parameters: none Return: void Remarks: Enable DMalloc. Since DMalloc is enabled at the beginning, this function is only necessary after calling DML_Disable. Page 38 DMalloc ------------------------------------------------------------------------ 8. Problem Solving Q: When I'm pressing the [PrtSc] key, DMalloc doesn't pop up, but something else happens. A: Three reasons are possible: - Your keyboard doesn't have a sole [PrtSc] key. Try the [Shift]+[PrtSc] keys together. - Your program redirected interrupt 05h (the print-screen interrupt) for its own use. If this is the case, you cannot interactively popup DMalloc. DMallocs heap checker functionality will still be kept, and it will pop up whenever necessary. You may force DMalloc to pop up regularly by selecting a popup cycle count in the setup win- dow (see section 5.4.3). - Some resident program is repeatedly changing interrupt 05h ([PrtSc] interrupt).Known programs are Pizzaz Plus, and HiJaak. Either unload these programs, or modify their setup, if possible (e.g. HiJaak can be set to "semi-active"). Q: When I start the program, DMalloc doesn't come up with the Setup Window. A: In the Setup Window, you have specified "No" at the "Startup Screen" entry. Either change this to "Yes", or simply delete the configuration file to restore the default setup. Q: Whenever I run the program, DMalloc repeatedly pops up and shows an overwrite to the FARNULL region. A: Some resident program is repeatedly changing inter- rupts that have been routed to your program. Inter- rupts used by the C runtime library and DMalloc are: Int 00h - division by zero (runtime library) Int 05h - print screen handler (DMalloc) Int 16h - keyboard interrupt (DMalloc) Int 21h - DOS OS entry (DMalloc) Int 23h - Ctrl-C and Ctrl-Break handler (runtime library and DMalloc) Some resident programs hook one or more of these interrupts, and, using the timer tick, repeatedly reset them, bypassing the operating system. Known examples are Pizzaz Plus and HiJaak. Having loaded these programs, untag the topmost (FARNULL) entry in the Heap Window. This will disable checking of the FARNULL region. Page 39 DMalloc ------------------------------------------------------------------------ Q: After an unrecoverable heap failure, the con- figuration file doesn't contain the corrupted pointers, only those I specified to "Save". A: This is perfectly normal. Usually, when an un- recoverable heap error is encountered, you will notice a lot of different problems like overwritten pointers, and Maverick entries. To avoid confusion during the next session, DMalloc skips the corrupted pointers in that case, and only saves those specified for "Save". Q: The manual states that the configuration file name would be the same as the program name. Why is mine named "_DMALLOC.DMC" ? A: DMalloc uses the environment information to retrieve the program name. If either your operating system doesn't provide this information (DOS <3.0), or your program releases the environment for memory's sake, DMalloc uses this name as a last resort. Q: I had corrupted pointers, but DMalloc didn't remind me on the next session, even with the correct setup. A: To have this feature work reliable, there are two things that must be kept in mind: - The environment settings, and the program parameters, should be the same. This is because the MSC startup code allocates some memory for these values, and if the sizes of these units differ, so may the location of successivly al- located units. - The size of the data segments should not change. If you have recompiled with somewhat modified code, this feature is most likely to fail. - It is absolutely necessary to do the same things you did in the last session, and in the same se- quence. If you're calling the malloc functions in different order, or with different parameters, the layout of the dynamic heap will be different, and the pointers will be dif- ferent, too. Q: I want to have NULLCHECK enabled, but DMalloc wouldn't let me tag the _DATA segment entry. A: It is possible to disable the runtime library NULL check. If you provide a module containing a "_nullcheck()" routine at link time, the linker will take this module instead of that the runtime library provides. Your _nullcheck() function must return (int)0. Page 40 DMalloc ------------------------------------------------------------------------ In that case the linker will not link the NULL seg- ment that normally makes up the first 4 paragraphs of the data segment. As the contents of these paragraphs are data of your program and no constant value anymore, Null Pointer assignments are perfectly valid. DMalloc is aware of this, and will not allow to do Nullcheck on a non-constant data segment. Q: I am using Bounds-Checker , and so far my code seems to be clean. Now, having linked my program with DMal- loc, Bounds-Checker permanently pops up and complains. A: You need to tell Bounds-Checker the exceptions needed for DMalloc. Copy the contents of the DMALLOC.BC file from the DMalloc original diskette to your exception file, and Bounds-Checker should not complain any more. Q: Under DesqView, my program used to work. Now, having linked with DMalloc, I can see DMalloc's output, but my program's windows are gone! A: DMalloc uses the RLSI (Relocatable Screen Interface) specification for direct video access. So if your program writes to the screen buffer directly, an RLSI host (as DV) would normally trap and relocate your memory access -- your program is slower. Using RLSI, you'll get the actual address of your video buffer. Alas, after RLSI has initialized, the "standard" video accesses are not trapped anymore. Thus, your program writes to "nowhere". Refer to section 6.5.1 on how to call the RLSI host. Page 41 DMalloc ------------------------------------------------------------------------ Appendix A - The Legal Department (License Agreement) Shareware distribution gives users a chance to try software before buying it. If you try a shareware program and continue using it, you are expected to register. Individual programs may differ on details - some request registration while others require it, some specify a maximum trial period. Registration often entitles the user for updates, printed documentation, or other "perks". Copyright laws apply to both shareware and commercial software, and the copyright holder may retain all rights. The only meaningful difference between shareware and commercial software is in the method of distribution. Shareware authors specifical- ly grant the rights to copy and distribute the software/docu- mentation, either to all and sundry, or with specific restric- tions. You should find software that suits your needs and bank ac- count, whether it's commercial or shareware. Both types have good programs and bad, but shareware makes finding the right program easier, because you can try before you buy. Also, because distribution overhead is much lower, shareware prices are often lower, too. Finally, shareware has the ultimate money back guarantee - if you don't use it, you don't pay for it. For this agreement, the term "DMalloc" refers to the DMalloc library and include file (DMALLOC.EXE and DMALLOC.H), the demonstration program (DEMO.BAT, DEMO.TXT, and DMLDEMO.EXE) together with its accompanying documentation (DMALOC09.DOC). A G R E E M E N T ***************** DMALLOC IS "SHAREWARE" AND IS LICENSED AT NO CHARGE TO THE USER FOR EVALUATION. FEEL FREE TO SHARE IT, BUT YOU MAY NOT ALTER THE PROGRAM OR DOCUMENTATION NOR INCLUDE DMALLOC AS PART OF ANOTHER SYSTEM. IF YOU FIND THIS LIBRARY USEFUL AND CONTINUE TO USE DMALLOC AFTER A 30 DAY TRIAL PERIOD, YOU MUST MAKE A REGISTRATION PAYMENT TO ERNEST VOGELSINGER. THE REGISTRATION FEE WILL LICENSE ONE COPY FOR USE ON ONE COMPUTER AT ANY ONE TIME. FOR COMMERCIAL USERS OF DMALLOC, AND FOR THOSE WHO WANT TO INCLUDE DMALLOC WITHIN A BETA-VERSION OF A PROGRAM, VERY AT- TRACTIVE SITE-LICENSE AGREEMENTS MAY BE OBTAINED BY ERNEST VOGELSINGER. ANYONE DISTRIBUTING DMALLOC FOR REMUNERATION OF ANY SORT MUST FIRST OBTAIN AUTHORIZATION FROM ERNEST VOGELSINGER. SUCH AUTHORIZATION WILL AUTOMATICALLY BE GRANTED TO DISTRIBUTORS RECOGNIZED BY THE (ASP) AS ADHERING TO ITS GUIDELINES FOR SHAREWARE DISTRIBUTORS, AND SUCH DISTRIBUTORS MAY BEGIN OF- FERING DMALLOC IMMEDIATELY. IN EITHER CASE, ERNEST VOGELSINGER MUST BE ADVISED. Page 42 DMalloc ------------------------------------------------------------------------ You are encouraged to pass a copy of the DMalloc library, demo program, and documentation along to your friends and colleagues for evaluation. Please encourage them to register too. All registered users receive the many benefits decribed in sec- tion 1.7. Page 43 DMalloc ------------------------------------------------------------------------ Appendix B - How to Send Email to Compuserve The following information was put together by CompuServe's Feedback team in a response time of less than 12 hours to my inquiry. A very big thanks to all those people doing a wonderful job! B.1 How to obtain a CompuServe Account DMalloc is also supported via CompuServe, either on the ZNT:PROGRAMMING forum (ZiffNet is part of CompuServe), Toolkits(7) section, or via CompuServe MAIL(17). If you do not have a CompuServe, or PC Magnet, account, and want to obtain one, please contact CompuServe Customer Service 800-848-8990 or 614-457-8650 You may use your modem to call PC MagNet via CompuServe. Dial 800-346-3247. When the modem connects: - at the HOST NAME prompt, enter PHONES. Follow the menus and note the number closest to you. Set your communications software to 300, 1200, or 2400 bits per second, 7 data bits, 1 stop bit, and full duplex. Dial the local number. When the modem connects: - type ^C. - At the HOST NAME prompt, enter CIS. - At the USER ID prompt, enter 177000,5000. - At the PASSWORD prompt, enter PC*MAGNET. - At the ENTER AGGREEMENT NUMBER prompt, type PCMAG92. Register your name and enter your MasterCard, Visa, or American Express number. (If you want to have your company billed instead, call CompuServe at 800-848-8900). Your personal User Id and a temporary password will be displayed. A new password will arrive in the mail within 10 days to confirm your subscription. To send email, type GO MAIL at any CompuServe "!" prompt. Follow the instructions from CompuServe. If you want to register DMalloc, send a note to 100015,551, stating your will to register, your Visa number, and that you agree to pay with your Visa account. If you have an account on a different network it is likely that you are able to send email to CompuServe. For some systems here's how to send email to CompuServe: -------------------- 17 Former "Easyplex" Page 44 DMalloc ------------------------------------------------------------------------ B.2 MCI At MCI Mail's "Command:" prompt, type CREATE and press the [Enter] key. At the "TO:" prompt, type my name, press [Space], type EMS within parenthesis and press the [Enter] key. For example: TO: Ernest Vogelsinger (EMS) At the "EMS:" prompt, type COMPUSERVE and press the [Enter] key. For example: EMS: COMPUSERVE MCI Mail responds by displaying EMS 281-6320 COMPUSERVE. At the "MBX:" prompt, type my CompuServe User ID number and press [Enter] : MBX: 100015,551 At the second "MBX:" prompt, press [Enter]. The information that you have entered is displayed for your approval. You should type YES if correct or type NO if there is an error and press [Enter]. For example: TO: Ernest Vogelsinger EMS: COMPUSERVE/ MCI ID: 281-6320 MBX: 100015,551 Is this address correct (Yes or No)? YES At the next two prompts, "TO:" and "CC:", press to skip them. Now type your message and send it as any MCI Mail message. When unsure as to what to enter at any MCI Mail prompt, typing a "?" and pressing the [Enter] key will display an explanation of available options. Page 45 DMalloc ------------------------------------------------------------------------ B.3 Internet Internet is an electronic mail system connecting governmental institutions, military branches, educational institutions, and commercial companies. Only ASCII text messages up to 50,000 characters can be sent through this system. Internet is a connection of various systems. The message format will vary from one system to another. Check at your mail location for the correct format. Two things that must be known: My User Id is 100015.551 (note that the comma changes to a period on Internet) The CompuServe domain address is "compuserve.com". An typical example of the format used on the Internet system is: INTERNET: 100015.551@compuserve.com The format will vary, but the essential elements of the address will stay the same. B.4 Telex, Twx CompuServe Mail allows to receive messages from any TELEX or TWX machine in the world. The information the TELEX user needs to send a message to a CompuServe electronic mailbox is: The User Id (100015,551) The machine number to send the message to: 3762848 (which has the answerback of CompuServe) Specify on the first non-blank line of the message a "TO:" followed by the User ID to inform CompuServe Mail where to deliver the message. If a subject is desired, you also can add an "RE:" after the "TO:" line in the message. The format would look as follows: TO: 100015,551 (This is required) CompuServe Inc. (This is optional) RE: DMalloc Registration (This is optional) Note: If you are using another electronic mail service to generate a TELEX to be sent to CompuServe, you need to first verify you can place the "TO:" information on the first non-blank line of the message. Some electronic mail systems automatically insert other information at the top of an outbound TELEX making it impossible for CompuServe Mail to determine the correct address. EasyLink is an electronic mail service from which CompuServe cannot currently receive inbound TELEXes. Page 46 DMalloc ------------------------------------------------------------------------ B.5 X.400 The address that you should specify to a mail system which can route messages to CompuServe via an X.400 connection is: Country = US ADMD = CompuServe PRMD = CSMail DDA = 100015.551 (note the period instead the comma) On AT&T Mail, for example, you could specify To: mhs/c=us/ad=compuserve/pd=csmail/d.id=100015.551 AT&T has defined a gateway named mhs!csmail that may replace the c=, ad=, and pd= information. On AT&T, you could also specify To: mhs!csmail!100015.551 Note: Again, the User Id must contain a period instead of a comma. B.6 MHS You can send MHS messages to the CompuServe Mail Hub. Specify the message adressee as MAIL@CSERVE {100015,551} Note: Some MHS applications do not have a specific procedure for entering the foreign address field. If you are unsure of the foreign address field capabilities of the MHS application, con- sult the documentation or call the producers of the software to see if their package supports foreign address fields. If an MHS application does not specifically support the foreign address field, there may still be a way to address a message to a non-MHS address. In the space where the MHS address is normally entered, you may be able to enter the foreign address field. The foreign address field must be enclosed in braces. For example, at the TO: or CC: prompt enter: MAIL@CSERVE {100015,551}