SINIXOpen Desktop Development System CodeView Debugger Edition April 1990 (SINIX Open Desktop V1.0) Order No. U5760-J-Z95-1-7600 Printed in the Federal Republic of Germany 4460 AG 2900.5 (5580) SINIX® Open Desktop Copyright © Siemens AG 1990 All right reserved Base: OPEN DESKTOP™ ©1983-1989 The Santa Cruz Operation, Inc. Delivery subject to availability: right of technical modifications reserved. Published by Bereich Daten- und Informationstechnik Postfach 83 09 51, D-8000 München 83 Siemens Aktiengesellschaft Portions © 1980, 1981, 1982, 1983, 1984, 1985, 1986, 1987, 1988, 1989 Microsoft Corporation. All rights reserved. Portions © 1989 AT&T. All rights reserved. Portions © 1983, 1984, 1985, 1986, 1987, 1988, 1989 The Santa Cruz Operation, Inc. All rights reserved. No part of this publication may be reproduced, transmitted, stored in a retrieval system, nor translated into any human or computer language, in any form or by any means, electronic, mechanical, magnetic, optical, chemical, manual, or otherwise, without the prior written permission of the copyright owner, The Santa Cruz Operation, Inc., 400 Encinal, Santa Cruz, California, 95062, U.S.A. Copyright infringement is a serious matter under the United States and foreign Copyright Laws. The copyrighted software that accompanies this manual is licensed to the End User only for use in strict accordance with the End User License Agreement, which should be read carefully before commencing use of the software. Information in this document is subject to change without notice and does not represent a commitment on the part of The Santa Cruz Operation, Inc. USE, DUPLICATION, OR DISCLOSURE BY THE UNITED STATES GOVERNMENT IS SUBJECT TO RESTRICTIONS AS SET FORTH IN SUBPARAGRAPH (c) (1) OF THE COMMERCIAL COMPUTER SOFTWARE - RESTRICTED RIGHTS CLAUSE AT FAR 52.227-19 OR SUBPARAGRAPH (c) (1) (ii) OF THE RIGHTS IN TECHNICAL DATA AND COMPUTER SOFTWARE CLAUSE AT DFARS 52.227-7013. “ CONTRACTOR/ MANUFACTURER” IS THE SANTA CRUZ OPERATION, INC., 400 ENCINAL STREET, P.O. BOX 1900, SANTA CRUZ, CALIFORNIA, 95061, U.S.A. Microsoft and MS-DOS are registered trademarks of Microsoft Corporation. UNIX is a registered trademark of AT&T. SCO Document Number: 6-26-89-6.0/3.2.0 Contents 1 Introduction Introduction 1-1 About this Manual 1 -2 2 Getting Started Introduction 2-1 Restrictions 2-2 Preparing Programs for the CodeView Debugger 2-3 Starting die CodeView Debugger 2-11 Using CodeView Options 2-14 3 The CodeView Display Introduction 3-1 Using Window Mode 3-2 Using Sequential Mode 3-22 4 Using Dialog Commands Introduction 4-1 Entering Commands and Arguments 4-2 Format for CodeView Commands and Arguments 4-4 5 CodeView Expressions Introduction 5-1 C Expressions 5-2 Assembly Expressions 5-7 Line Numbers 5-10 Registers and Addresses 5-11 Memory Operators 5-15 6 Executing Code Introduction 6-1 Trace Command 6-3 -l- 7 Examining Data and Expressions Introduction 7-1 Display Expression Command 7-2 Examine Symbols Command 7-9 Dump Commands 7-13 8 Managing Breakpoints Introduction 8-1 Breakpoint Set Command 8-2 Breakpoint Clear Command 8-5 Breakpoint Disable Command 8-7 Breakpoint Enable Command 8-9 Breakpoint List Command 8-10 9 Managing Watch Statements Introduction 9-1 Setting Watch-Expression and Watch-Memory Statements 9-3 Setting Watchpoints 9-7 Setting Tracepoints 9-10 Deleting Watch Statements 9-15 Listing Watchpoints and Tracepoints 9-17 Assembly Examples 9-19 10 Examining Code Introduction 10-1 Set Mode Command 10-2 Unassemble Command 10-4 V ie w Command 10-7 Current Location Command 10-10 Stack Trace Command 10-12 11 Modifying Code or Data Introduction 11-1 Assemble Command 11-2 Enter Commands 11-6 - i t - 12 Using CodeView System-Control Commands Introduction 12-1 Help Command 12-2 Quit Command 12-3 Radix Command 12-4 Redraw Command 12-7 Screen Exchange Command 12-8 Search Command 12-9 Shell Escape Command 12-12 Tab Set Command 12-14 Option Command 12-15 Redirection Commands 12-17 - i n Chapter 1 Introduction Introduction 1-1 About this Manual 1-2 Introduction Introduction Welcome to the CodeView® debugger. This is an executable program that helps you debug software written with the C and Macro Assembler languages. The CodeView debugger is a window-oriented tool that enables you to track down logical errors in programs; it allows you to analyze a program as the program is actually running. The CodeView debugger displays source code or assembly code, indicates which line is about to be exe­ cuted, dynamically watches the values of variables (local or global), switches screens to display program output, and performs many other related functions. The debugger can be easily learned and used, by assem­ bly and high-level language programmers alike. To use CodeView, you first create an executable file from compiled object files. (When a program is made into an executable file, it is in the form that can be loaded and executed by the system.) This executable file must be compiled and linked with the correct options so that it contains the line-number information and a symbol table needed by CodeView. You can use the C compiler, or cc, which calls the linking program, Id, The correct options for compiling and linking for use with CodeView are described in Chapter 2, “ Getting Started.” Introduction 1-1 About this Manual About this Manual This manual explains the use of the CodeView debugger. Commands, display, and interface of the debugger are presented here. The manual is comprised of the following chapters: • Chapter 2, “ Getting Started,” explains how to create a C or assem­ bly program that can be run with the CodeView debugger; it also explains how to start the debugger and select various command­ line options. • Chapter 3, “ The CodeView Display,” discusses the CodeView dis­ play screen and interface, including function keys and keyboard commands. • Chapter 4, “ Using Dialog Commands,” presents the general form of CodeView commands. • Chapter 5, “ CodeView Expressions,” describes how to build com­ plex expressions for use in commands. • Chapter 6, “ Executing Code,” explains the CodeView commands that execute code from within a program. • Chapter 7, “ Examining Data and Expressions,” discusses several data-evaluation commands. • Chapter 8, “ Managing Breakpoints,” explains how to use break­ points to suspend execution. • Chapter 9, “ Managing Watch Statements,” describes the use of watch statement commands to set, delete, and list watch state­ ments. • Chapter 10, “ Examining Code,” discusses several commands that let you examine program code or data related to code. • Chapter 11, “ Modifying Code or Data,” explains how to alter code temporarily for testing in the CodeView debugger. • Chapter 12, “ Using CodeView System-Control Commands,” discusses commands that control the operation of the CodeView debugger. 1-2 The CodeView Debugger Chapter 2 Getting Started Introduction 2-1 Restrictions 2-2 Preparing Programs for the CodeView Debugger 2-3 Programming Considerations 2-3 CodeView Compile Options 2-4 CodeView Link Options 2-5 Preparing C Programs 2-6 Preparing Assembly Programs 2-8 Starting the CodeView Debugger 2-11 Using CodeView Options 2-14 Starting with a Black-and-White Display 2-15 Specifying Start-Up Commands 2-16 Enabling Sequential Mode 2-17 Working with Older Versions of the Assembler 2-18 w Introduction Introduction Getting started with the CodeView debugger requires several simple steps. First you must prepare a special-format executable file for the pro­ gram that you wish to debug; then you can invoke the debugger. You may also wish to specify options that affect the debugger’s operation. This chapter describes how to produce executable files in the CodeView format using C or assembly language, and how to load a program into the CodeView debugger. This chapter lists restrictions and programming considerations with regard to the debugger, which you may want to con­ sult before compiling or assembling. Finally, this chapter describes how to use the debugger with the Macro Assembler. Getting Started 2-1 Restrictions Restrictions You cannot use the CodeView debugger to debug source code in include files. This restriction applies generally to the use of the CodeView debugger, regardless of the language being used. 2-2 The CodeView Debugger Preparing Programs for the CodeView Debugger Preparing Programs for the CodeView Debugger You must compile and link with the correct options, in order to use a pro­ gram with the CodeView debugger. These options direct the compiler and the linker to produce an executable file, which contains line-number in­ formation and a symbol table, in addition to the executable code. Note For the sake of brevity, this section and its three subsections use the term “ compiling” to refer to the process of producing object modules. However, almost everything said about compiling in this section applies equally well to assembling. Exceptions are noted in the section “ Preparing Assembly Programs” in this chapter. Not all compiler and linker versions support CodeView options. Consult the specific language documentation for information about compiler ver­ sions. If you try to debug an executable file that was not compiled and linked with CodeView options, or if you use a compiler that does not sup­ port these options, then you are only able to use the debugger in assembly mode. This means that the CodeView debugger does not display source code or understand source-level symbols, such as symbols for functions and variables. The two CodeView basic display modes are source mode, in which the program is displayed as source lines, and assembly mode, in which the program is displayed as assembly-language instructions. These two modes can be combined in mixed mode, in which the program is dis­ played with both source lines and assembly-language instructions.