UPS(1) UPS(1) NAME ups - X11 and SunView based source level C debugger SYNOPSIS ups target [corefile|pid] [[:]srcdir[:srcdir]] [-a target- args] DESCRIPTION Ups is a X based source level debugger for the C, C++ and Fortran programming languages. It supports both run time debugging with breakpoints and post-mortem debugging from a core file. On Suns you can attach ups to a running pro- cess. Ups runs in its own window, thus not interfering with the target program's I/O. The ups window has two major areas - one showing a structured document represent- ing the target state, the other showing the source that is being executed. Ups makes heavy use of direct manipulation and feedback. When you add a breakpoint it is shown as a pseudo C state- ment (#stop) in the source display. The current point of execution is highlighted in the source display and you can watch it move as you step through loops and function calls. You can edit in fragments of interpreted C code (including assignments to variables and calls to target functions). There are powerful facilities for exploring linked data structures - you can recursively expand and collapse structures to follow links. Ups is primarily a C debugger, but it also has support for debugging Fortran 77 and Fortran 90 code. See the section DEBUGGING FORTRAN CODE (near the end of this manual page) for information on Fortran specific features. Ups has reasonable support of C++. See the section SUPPORT FOR C++ after the Fortran section for information on on this. The URL for the ups web site is: http://ups.sourceforge.net/ It is maintained by Ian Edwards (ian@con- certo.demon.co.uk). It includes a FAQ, html man pages, site listings where ups can be found, supported architec- tures, a history of changes between versions and other information. GETTING STARTED This section gives step by step instructions on how to use ups on a small example C program. The idea is to get a feel for how to use ups without getting bogged down in details. After following the instructions here you should be able to explore a little on your own and then be ready to have a look at the reference material that follows. Here is the sample source code: struct argst { char *a_name; struct argst *a_next; }; struct argst *listhead = 0; void stash(name) char *name; { struct argst *a; char *malloc(); a = (struct argst *)malloc(sizeof(struct argst)); a->a_name = name; a->a_next = listhead; listhead = a; } int main() { stash("foo"); stash("bar"); } We skip error checking code here in the interests of brevity. Put a copy of the code above into a .c file (e.g. sample.c) by cut-and-paste or by snarfing the lines from the file that contains this manual page. If you have the source directory of ups around you will find this code below there in the file ups/doc/sample.c. Assuming you have a copy of the above code in a file and you are sitting at a workstation or X terminal and have an X or Sunview session running, here is what you do: o Compile and link the code with the -g flag to cc(1) or gcc(1). The -g flag directs the compilers to include extra symbol table information in the object file that is needed by debuggers. o Give the command `ups a.out' (or whatever you called the object file). After a short pause a window will be cre- ated; the details obviously depend on your window manager. This is the simplest way of invoking ups. For a complete description of the command line flags and arguments see UPS COMMAND LINE ARGUMENTS. In the window you should see a display divided into various rectangular boxes and menus, with two large regions in the upper and lower halves of the win- dow. The top region is the display area - it con- tains captions looking roughly like: Target a.out a.out Signals Environment Untyped variables Source files Functions Breakpoints In the lower region you should see the start of main() displayed. Note: the layout of the window is explained in detail in a later section. o Move the mouse cursor over the Breakpoints caption in the upper region, and press and release the left mouse button. You should see two things happen: the caption is inverted to show that it is selected, and a menu appears near the top of the window with the cap- tions Add new, Remove all, Restore, and Load file. All the objects in the display area (except Func- tions) can be selected like this and have their own menus. Selecting an object (or many objects) and clicking on one of the commands in its associated menu is the primary way of issuing commands to ups. o Click (press and release) the left mouse button over the Add new menu caption. You should see a line below the Breakpoints caption looking like: Function:[] line:0 The hollow square represents the editing cursor, which indicates where typed characters will appear. (this is actually displayed as a solid black rect- angle on the screen). o Type `main' You can use the delete key as you would expect to fix typos. There are various other useful control characters - see the EDITABLE FIELDS section for details. o Press ESC (the escape key). This confirms the edit. You should see the text #stop; appear at the start of main in the source region. Ups represents breakpoints as this fragment of pseudo C. You can edit breakpoints to do things other than just stop (e.g. call a target function or only stop if a certain condition is true). This is covered later in this section, and described fully in the section ADDING INTERPRETED CODE. You can also add breakpoints by pointing at the appropriate line in the source region - this is described later in this section. o Click the left button over the caption Start at the left hand side of the menu just below the display area. This menu is the target control menu. Here is a brief description of what the other commands in this menu do (these are explained in more detail in the CONTROLLING TARGET EXECUTION section). As you have just seen Start starts the target running. Step and Next step execution over single lines of code (Step steps into function calls, Next doesn't). Cont makes the target process run until it hits a breakpoint or exits. Stop stops a run- ning target process, queues a request to terminate a symbol search, or breaks out of a Step that takes a long time, and Attach prompts for a PID of a tar- get process to attach to (for SunOS), and Detach detaches from an attached process. Kill kills off the target process, ready for another run using Start. You should see the first line of code in main high- lighted. This means that execution has stopped just before this line. If you look at the display area you will also see that a new line has appeared under the Functions object. This should look like: main sample.c:18 This shows that you are stopped at line 18 of sam- ple.c in function main. At this point you are in the usual state for ups: you have the target stopped, with the line that is about to be executed highlighted in the source win- dow and your current position in the source file shown under the Functions object in the display area. o Click on Step in the target control menu. The source display switches to function stash, which you have just stepped into. You will also see an extra line under Functions - the display should look like: main sample.c:18 stash sample.c:10 As you can see this is a stack trace, showing you which function called which starting from main and working inwards towards the function you are cur- rently stopped in. o In the source region move the mouse over the `a' at the start of the highlighted line and click the left mouse button. You should see a line added to the stack trace, making it look like: main sample.c:18 stash sample.c:10 struct argst * 0x4 This is one of the main strengths of ups: to see the type and value of any variable that is visible in the source window you simply click on its name. This is showing that a is a variable of type struct argst * with the value 4. Ignore the angle brack- ets round the `a' for now - they will be explained later. This is an uninitialized variable, so the value you see will probably be different from this. You will also notice that the menu near the top of the display area has changed. Every object in the display area has an associated menu, which is dis- played when that object is selected. Ignore the menu for now. o Click on Step in the target control menu. The value displayed for the variable a changes to whatever is returned by malloc. This shows another key feature of ups - displayed variables remain in the display area as you step through the program code so you can watch the values change. o Now click the left mouse button over the displayed line for the variable a. The line will be inverted to show that it is selected and a menu will appear as before near the top of the display area. o Click on Expand in the menu that was produced by the last step. You will see an entry added for each member of the structure, giving a display under the Functions object that looks something like: main sample.c:18 stash sample.c:11 struct argst 0x60c8 char *NULL struct argst * 0x0 The member types and values are shown in the same way as the structure pointer `a' itself. As before the values are uninitialized, so the values you see will depend on the exact behaviour of your malloc implementation. o Click on Next in the target menu. The highlighting in the source window will move on to the next line, and the value displayed for the a_name field will change. This sort of interaction is typical use of ups - you expand structures to see members of interest, and then step through the source code watching how they change. o Move the mouse over the highlighted source line, press and hold down the right hand mouse button then release it. When you pressed the mouse button you will have seen a popup menu with the captions Add breakpoint, Execute to here, Jump to here, and Edit source. You will also have seen an arrow to the left of the menu pointing at the source line you pressed the mouse over. When you release the mouse button a breakpoint is added just before the source line. You will see the text #stop; appear. This is the simplest and most common way of adding breakpoints in ups. The normal sequence of actions is: o Type the name of the function you are inter- ested in (or enough of it to uniquely iden- tify it) and hit ESC (the escape key). The source of the function is displayed in the source window. o Scroll the source to make visible the line where you want to add a breakpoint. o Add a breakpoint by clicking the right mouse button over the source line. o Click on Cont in the target control menu. The target continues until it hits a breakpoint. In this case the target stops in the second call of stash from main. You will notice that in the dis- play area the displayed value of a_name has changed. o Click on Cont again. The target continues to completion and exits. The stack trace and variables disappear from the dis- play area, and all the target control menu captions except Start are greyed out to indicate that they are unavailable while the target is stopped. We are almost at the end of this example. These last steps are to show how you can add printf calls (in fact any interpreted C). The actions we are about to cover are: o Editing some interpreted C into a breakpoint. o Scrolling the source window to show the other breakpoint and removing it. o Re-running the target to see the effect of the interpreted code. o Move the mouse over the `#stop;' text that indicates the breakpoint in the stash function and click the middle mouse button. You should see an editing cursor (a black rectan- gle) appear. If it is not at the end of the `#stop;' text then click the middle mouse button further to the right. o Use the delete key to delete the `#stop;' text. o Type the following text: $printf("Setting a->a_name to %s\n", a->a_name); $printf is a built in ups function with an inter- face almost identical to printf except that it sends output to an region in the ups display. o Hit ESC (the escape key) If you haven't made any errors ups will silently accept the line and the editing cursor will disap- pear. If you have made a syntax error ups will beep, give you an error message and put the editing cursor at the point of the error. You can then correct the error. o Press and hold down the left mouse button in the scroll bar to the left of the source window, and with the mouse button pressed move the mouse button a few pixels towards the top of the window. You should see the source text scrolling slowly upwards. The more you move the mouse from the place you first pressed it, the faster the source scrolls. o When you see the source of Main appear in the source win- dow release the mouse button. The scrolling will stop. o Click the middle mouse button on the #stop at the start of main. This displays the editing cursor as before, but if you look in the display are you will notice that it also selects the corresponding breakpoint object. You will see the breakpoint entry highlighted, as well as a menu with the captions Remove, Source, Save to file, Execute, Activate, and Inactivate near the top of the window. o Click on Remove in the menu You will see the breakpoint entry in the display area disappear, along with the #stop; line in the source window. o Click on Start in the target control menu. You should see a third subregion appear in the dis- play. This looks similar to the source window, with a controlling menu above it and a scroll bar on the left hand side. This is the output region. It is where output from the built in function $printf appears. This region appears the first time $printf is called by inter- preted code. You will see that the text Setting a->a_name to foo Setting a->a_name to bar has appeared. This was produced by the interpreted code that you added. Note that the target ran to completion without stopping. A breakpoint only stops the target if the pseudo C statement #stop is executed. This lets you add conditional breakpoints simply by putting an if statement around them. One final point: you can call target functions (like stash in this example) from interpreted breakpoint code. This is often used to call printf in cases where you do want the debugging output interspersed with the target program's output. Here endeth the example. It certainly hasn't covered all of the features of ups, but hopefully it has given you a feel for the way it works. Some basic points: o The two important areas in the display are the dis- play area (top) and the source region (bottom). o The display area contains captions representing objects of different types. o You can select an object by clicking on it with the left mouse button. o Each different object type has an associated menu which appears near the top of the ups window when the object is selected. o Commands selected from these menus act on the cur- rently selected objects. o The source region displays the currently executing source code, with the line that is about to be exe- cuted highlighted. o You can add any variable to the display area by clicking on an instance of it in the source window with the left mouse button. o Double clicks will alternately expand and compress the variable, if possible. You can add breakpoints by pointing at lines of source. o You can edit breakpoints to add printf statements and conditional breakpoints. o You can expand and collapse structures to explore data structures. o Variables remain in the display area as you step through the code so you can watch the values change. The rest of this manual page gives a complete description of ups . You should probably skim through it at first reading before playing with ups on some of your own code for a while. When you are more familiar with ups reread these sections in more detail. UPS COMMAND LINE ARGUMENTS This section gives a complete description of the command line arguments accepted by ups. The command line syntax is: ups target [corefile|pid] [[:]srcdir[:srcdir]] [-a target-args] [-nodemangle] [-nosavesigs] [-split[:screen]] [-fullpath] [-install] Ups accepts various other flags, but these are mostly to support maintenance and testing, and are not of interest to the general user. You can see a full list of the ups flags by giving the command `ups -fullusage'. The only mandatory argument is the name of the executable file containing the program to be debugged (the target). If a corefile argument is given it is taken to be the name of a core image dumped from target. If no corefile argu- ment is given and there is a core image file called `core' in the directory of the target then that is taken as the core file. Old core files, and core files which weren't dumped from the target, are silently ignored unless you give the name of the core file explicitly (in which case ups will use it, but give a warning message). If the corefile argument consists solely of digits, it is taken to be the process id of the target. This allows you to attach ups to an already running process on machines with the necessary support (currently only Suns). If you subsequently quit ups while still attached in this way, it detaches from the target, allowing the target to continue. By default ups looks for source files in the directory of the target. You can specify alternative source directo- ries by giving a list of directories separated by `:' characters. An empty initial path (i.e. a leading `:') means the directory of the target. On Suns running SunOS 4, the C compiler includes directory paths for source files, so ups will normally find source files in other directories even without the source path argument. You can specify the arguments that the target should be invoked with by giving the -a option, followed by a single argument. You can give multiple arguments for the target by enclosing the list of arguments in single or double quotes. Ups will itself interpret metacharacters like `*' and `>' - see TARGET COMMAND LINE ARGUMENTS. When the `-nodemangle' argument is specified, ups will do no demangling on function or variable names. This should result is slightly faster invocation time for pure C code. It is still possible to debug C++ code in this mode, although the names need some mental deciphering. A unique feature of this version of ups, is that even when C++ names are shown mangled, you can generally still click on variables in the source window, and ups will still find the name to display, albeit in a mangled state. If you are saving state between debugging sessions by cre- ating a "ups-state" directory, the command option, "-nosavesigs" stops UPS from saving signal state to the ups state file. By default, ups passes only the final component of the target filename to the process as argv[0]. Sometimes, the process needs the full path to itself, for example, to locate auxiliary files. If the `-fullpath' argument is specified, this default behaviour is suppressed and the target filename is passed directly from the ups command line to the process command line. ENVIRONMENT VARIABLES AFFECTING UPS You can see all the symbol table names that are loaded and not loaded by setting VERBOSE to 1, e.g. if you use csh(1) by doing "setenv VERBOSE 1" before calling ups. Setting VERBOSE to "NOLOAD" causes ups to list just the libraries that are not loaded. The variable EDITOR is used, if set, as the editor for source files. If not set the default is vi(1). Unless the editor is emacs(1), or the name starts with an "x", it will be started in a new xterm(1) window. You can change the source code language and compiler type that ups assumes have been used by setting UPS_LANGUAGE or UPS_COMPILER as appropriate. Note that these settings will be used for all files. These might be useful if you use non-standard file extensions, or have compiled C with a C++ compiler. UPS_LANGUAGE can be "C", "C++", "F77" or "F90". UPS_COMPILER can be "cc" (Sun C/C++ compiler), "gcc" (GNU gcc/g++/g77), "clcc" (Centerline C++), "f77" (Sun Fortran) or "f90" (EPCF90). On Sun SPARC systems UPS_SUNOS_STEP controls whether Step will take you into a routine if it is in a shared library. If not set, or set to 1, you can step into shared libraries. If set to 0 then Step will continue to the next statement in the current routine. Most software projects of any size develop formal or informal naming conventions that make it possible to spec- ify the desired format for a variable based on the name and, possibly, the type, regardless of the context in which it appears. If, like most software engineers, you spend much of your time debugging the same code, you can set up a UPS_FORMATS string in your environment to specify the desired formats for frequently examined variables. The following is an example of a UPS_FORMATS string: export UPS_FORMATS=" \ unsigned : UHEX; /* Default unsigned to hex */ \ unsigned *any_int[NTLW] : UDML; \ char abyte: OCT; \ *bits* : UBIN; \ auto " The first line of this format string causes ups to format unsigned variables in hex rather than decimal. The format string accepts C-style comments to allow for more readable .login or .cshrc files. The second line specifies that any unsigned variable whose name matches the string "*any_int[NTLW]" is an exception and should be formatted in decimal. Pattern matching is as in shells such as sh, csh, or bash. It is important that the exception come after the general rule specified in the first line. Note that in the UPS_FORMATS string, "char *foo" means any variable of type char whose name ends in "foo", not a variable named "foo" of type char*. The third line specifies that any variable of type char and name "abyte" should be formatted in octal. The forth line specifies that any variable of any basic type with the string "bits" in its name should be format- ted in binary. The last line specifies that any time the you change a format ups should automatically save the change and use it as the default format for any variable of the same name and type. The syntax of the UPS_FORMATS string is format_string ::= format_spec [ ; format_string] [;] format_spec ::= format_request | auto_save_request format_request ::= ["unsigned"] [type] [ pattern ] : [format] type ::= "char" | "short" | "int" | "long" pattern ::= < any C identifier with wild cards '*', '?' or "[]" > format ::= "UHEX" | "UOCT" | "UDML" | "UBIN | | "HEX" | "OCT" | "DML" | "ASCII" | "STRING" auto_save_request ::= "auto" In the format request, if the type is omitted then either all unsigned basic types or all basic types regardless of sign are selected. If the pattern is omitted the default pattern is "*" so that all variables of the specified type are selected. It is possible to insert pre-defined strings when editing text. This applies to all editing: in the typing line, in the display area, in breakpoint code and in the output window. The right mouse button invokes a menu of strings defined by environment variables of name `UPS_F*_STR' where `*' is a number from 1 through 12. When the cursor is over the typing line or output window, the mousehole shows "(menu)" for the right button as an indication that a custom menu may be available. The UPS_F*_STR strings accept control, meta, and escape characters as follows: \n, \r, or \e: Enter an escape character to termi- nate the edit ^A, ^B, etc.: Enter the corresponding control char- acter. @f, @b, etc.: Enter the corresponding meta charac- ter. This allows movement by words. \\ or \^ or \@: Override the special meaning of '\', '^', or '@'. As an example, it is often nice to have skeleton strings for `printf' or `cout' statements in breakpoint code, or a directive for expanding linked lists for the typing line, or a string for setting breakpoints on `cout' statements in C++ code. Yet another string can be used to call strcmp for a conditional breakpoint. The F6 string pastes in the X-windows selection and the F7 string sets a breakpoint in purified code. To do this, if you use csh(1), put the following in your environment: setenv UPS_F1_STR '$printf("\\n");' setenv UPS_F2_STR 'if (strcmp(, ""))' setenv UPS_F3_STR '@name .next' setenv UPS_F4_STR "ostream::operator<<" setenv UPS_F5_STR 'ostream::operator<<(&cout, "");' setenv UPS_F6_STR "^e^u^y\n" setenv UPS_F7_STR "%b purify_stop_here\n" If your shell is sh(1) or bash(1) then use: export UPS_F1_STR='$printf("\\n");' etc INTERACTIVELY ADDING SEARCH PATHS Search paths can be given to ups at any time during debug by selecting the `Source Files' header in the display win- dow and pressing Add source path. The typing line will prompt for input. It will display the last entry in the search path list as a default, if a list exists. Multiple paths may be entered at once by entering a colon separated list. This is the same syntax as the ups command line arguments. This enables the paths for source files to be found without the need to back out of the debugger and add the search path to the command line. Note that this will work only if the file is already an entry in the source file list, but cannot be listed. When this condition occurs, pressing the `path' caption will display the assumed path for the file, which must be in error. The program may have to be statically linked to find all source file names. LAYOUT OF THE UPS WINDOW The ups window is divided into a number of rectangular regions. This section gives a brief description of each region. It won't make much sense unless you are also looking at an ups window. o At the top of the window on the left is the typing line. On startup a black rectangle known as a editing cursor is shown. Typed characters appear in this region, and some ups commands use the text in this window as an argument (e.g., the command to search for a regular expression in a source file). o Below the typing line is the dynamic menu area. On startup this area is greyed out. See THE DISPLAY AREA below for a description of the dynamic menu. o Below the dynamic menu area is a region where mes- sages from ups appear (usually with a beep). o To the right of the above three regions is a mouse- hole. This has a representation of the three mouse buttons, and captions for each button saying what that button will do. The captions change as you move from region to region, reflecting the fact that the mouse buttons have different functions in different regions. o Below the preceding four regions is the display area - a large region used to display and investi- gate the current state of the target. There is a scroll bar to the left of the display area. See THE DISPLAY AREA. o Below the display area is the target menu. This has a set of commands for controlling target execu- tion. See CONTROLLING TARGET EXECUTION below. o Below the target menu is the source menu, with a set of commands for managing the source region, which is below this menu. There is a scroll bar to the left of the source region. See THE SOURCE REGION below. THE DISPLAY AREA The display area is the large region in the upper half of the ups window. Its main use is to show the state of the program when it stopped, though it is also used for other control functions. There are a number of captions in the display area, like Signals, Breakpoints etc. These are known as objects . To select an object, press and release the left mouse but- ton over it. Any objects that were previously selected are deselected, the object is inverted to show that it is selected, and a menu of commands applicable to that object appears in the second of the three slots at the top of the window. At any time this region of the display either contains a menu corresponding to a selected object, or is empty (painted a uniform grey) if there are no objects selected. A command selected from the menu (by pressing and releas- ing the left mouse button over the caption) is applied to the currently selected objects. It is possible to apply a command to a group of objects. To do this, select a group of objects by pressing the left mouse button over the first object and then dragging the mouse over the other objects you wish to select before releasing the button. You cannot select objects of different types simultane- ously as each different type of object has its own menu. Once the first object has been selected, only objects of the same type will be selected (and highlighted) as the cursor passes over them. The right hand mouse button is used to toggle whether an object is selected - clicking it over a selected object deselects that object, and clicking over an object that isn't selected adds that object to the selection. As with the left mouse button, you can drag the mouse with the right button down to toggle a group of objects. Several of the menu commands add new objects to the dis- play. For example, when you expand an entry in the stack trace all the local variables for the function it repre- sents are added to the display (see EXAMINING VARIABLE VALUES below). These new objects can be selected in the same way as the existing ones, and have an associated menu of commands. Once a few objects have been added to the display area, there is usually not enough room to display all of them at once. There is a scroll bar to the left of the display area which lets you scroll the display area up and down. To scroll, press and hold down the left mouse button whilst within the scroll bar, and move the mouse in the direction you wish the display to move. The further you move the mouse, the faster the scrolling. You can also use the left and right mouse buttons to page up and down through the display in the same way as with the xterm(1) scroll bar. Clicking the left mouse button in the scroll bar pages the display down. Similarly, clicking the right button pages the display up. The dis- tance paged depends on how far the cursor is from the top of the scroll bar. The black blob in the scroll bar represents the proportion of the entire display that is currently visible, and the position of this visible part within the whole display. For example, if the black blob is one third the height of the scroll bar, and in the middle, it means that the total height of the objects is about three times the height of the display area, and the middle third is currently being displayed. You can use the scroll bar to go directly to a given point in the display. Press and release the middle mouse button at a point in the scroll bar. The black blob is moved so that it centres around the point, and the display is moved correspondingly. THE SOURCE REGION The source region is used to display the source line that the target is currently stopped at, or more precisely the line that is about to be executed. Like the display area, the source region has a scroll bar to the left of it, which behaves in the same way as the display area scroll bar. Above and to the left of the source region is a box where the name of the current source file and the current line number is displayed. See the FILE NAME BOX section for details of the right button menu for this region. To the right of this is the source region menu with com- mands Back, Search, Up and Down. The Up and Down commands step up and down through the tar- get program's call stack. If you are looking at the source code of the currently executing function, Up switches the display to show the source of the function that called it. Repeatedly clicking on Up will take you all the way up the stack to main (or MAIN for Fortran pro- grams). Similarly, Down steps one level down in the call stack. When ups has been attached to a target, it is possible to detach without quitting the debugger by pressing the Detach caption at the bottom of the display window. At a later time, ups can then be attached to the same instance of the target, or to a new instance of the target by using the attach caption described below. On an attach, the debugger will reload any shared libraries that have changed, as well as any new shared libraries that the target uses. If ups has been detached from the target as described above, or if the target ter- minates for any reason, it is possible to attach to the same or a new invocation of the target without quitting the debugger. The advantage of this is that it may take several minutes for ups to initially come up, but once the symbol tables have been read, the time to reattach will be at most, of the order of tens of seconds, and often just a few seconds. All breakpoints and even breakpoint code will still work. After pressing Attach you will be prompted to enter the PID number. The PID of the last attached process is displayed as a default. If the new invocation of the target has changed, the reattached session may not work correctly if statically linked object files have changed. ups will re-read any changed shared libraries when attach- ing. A very handy use of the attach item is for debugging spawned processes that can timeout unless a communications handshake or license check is performed quickly. If the spawned process is stopped at a pause while ups is invoked from scratch, the process may well timeout and exit before ups can read all the necessary symbol information. The solution is to first invoke ups on the target without a PID in the command line. After the symbols have been read, breakpoints can be set, then the real process to be debugged is spawned. Then press Attach and quickly enter the PID of the spawned process to debug. Shared libraries are reloaded if they change between attach/detach cycles. So one can attach to a target, debug, detach and then rebuild a shared library that the target uses. Then after the target is rerun with the new library, ups can be attached again and the new library will be re-scanned and debugging can continue without quitting ups, and without the overhead of re-reading sym- bols for the other libraries. Breakpoints in the new library will need to be reset. Ups puts out a message about what libraries are being reloaded in such cases. The Search command is used to search for regular expres- sions (using the same syntax as grep(1) patterns) in the currently displayed source file. First type in the pat- tern to be searched for (typed characters appear in the typing line at the top of the window on the left) then press and hold down the left mouse button over the Search caption. A popup menu appears with the options Backwards and Forwards. Move the mouse over the one you want and release the button. If the pattern is found, the matching text is made visible in the source region and highlighted. You can click the left mouse button on any variable or function name in the source window to display it. Double clicks will alternately expand and compress the variable. Variables are added to the display area, as described in EXAMINING VARIABLE VALUES below. If you click on a func- tion name, the source for that function is displayed (this is similar to the tags facility in emacs or vi). Ups maintains a stack of where you've been. After you have clicked on a function name you can use the Back command in the source menu to return to where you were. With a left click, ups reads the function symbols before navigating to the function. You can bypass the symbol reading by using the middle mouse button. So an unmodified left click looks up local symbols, then globals, a Shift-left click does an automatic "add expr" and a middle click edits breakpoint code, but if not over breakpoint code it looks up global symbol lookup only. You can also get a function displayed by typing the name into the typing line at the top of the ups window. You do not need to type the whole name - just enough characters to uniquely identify the function. As for typing in a breakpoint, pressing ESC does partial name completion, and Shift-ESC, or Shift-RETURN will list the matching names in the output window. If a function appears by the same name in more than one source file, you can use the syntax `filename:funcname' to specify which function you want. Ups will also understand shell-style globbing with `*' (e.g. `*foo_func*') for function and global variable names, with the restriction that the pattern must match only a single name. Whenever the source region switches to a new source file, ups checks the last modified time of the source file against the last modified time of the target object file. If the source file is newer than the target you get a warning message and the source code is displayed with foreground and background colours reversed as a reminder that this source code might not correspond the object file you are debugging. See the section FILE NAME BOX below this for getting actual file dates. You can select arbitrary text in the source window by dragging the mouse over it with the left button pressed. The selected text is highlighted, and can be pasted into other windows, or other areas in the ups window (such as the typing line). Note that dragging (press mouse button, move mouse, release) has a different effect than clicking (pressing and releasing the left mouse button without mov- ing the mouse). FILE NAME BOX There is a menu associated with this file name box above the source, and the mousehole and cursor also indicate that the right mouse button invokes a menu over the region The menu has options to edit the source, show used and assumed file paths, rematch and reload the file, and to show file dates. The latter is useful for an explanation of why ups may be showing reverse video for a file. In the bottom output window, it list the source file date, the associated shared library date if applicable, and the tar- get file date. The menu is a convenient way to get infor- mation about a file without having to find the file in the source file list. For breakpoints, when the source is displayed, the menu provides a quick way to get at full file names and dates. EDITABLE FIELDS All editable fields in ups work in the same way. To start editing you click the middle mouse button over the editable text. A black marker bar appears - characters that you type appear to the left of this marker bar. You can reposition the marker bar by clicking in the new posi- tion with the middle mouse button, or by using one of the cursor movement key sequences described below. Clicking the left or right button confirms the edit. Clicking the middle mouse button outside the editable text area also confirms the edit. In both cases the mouse click is then interpreted as normal - this means that to confirm an edit you can simply move on to another activ- ity. The final way to confirm an edit is to type ESC (the escape key) or click the left mouse button on the Enter Button (the small region to the right of the typing line with the "<<" image). To paste the current window system cut buffer, use Con- trol-Y or click the middle mouse button on the Enter But- ton. When you try to confirm an edit ups checks that the new field value is reasonable. If not you get an error mes- sage and you are left in the edit. An immediate second attempt to quit abandons the edit and restores the origi- nal field value. Ups recognizes a subset of the GNU emacs key bindings when editing fields. In the current version there is no way to customize these key bindings. This will be fixed in a future release. You can use most of the common emacs key mappings when editing text (e.g. in the typing line, when adding break- points etc). Here is a list of the supported mappings (C- x means CONTROL-X, M-x means ALT-X, UP, DOWN, LEFT and RIGHT are the arrow keys, SPC is the space bar and DEL is the delete key): C-a Move to start of line C-e Move to end of line M-m Move to first non-whitespace character M-@, M-SPC Set mark C-w Delete text between mark and point C-p, UP Move up a line, if possible, otherwise retrieve the next previous item in the history buffer C-n, DOWN Move down a line, if possible, otherwise retrieve the next later item in the history buffer C-b, LEFT Move backwards one character C-f, RIGHT Move forward one character M-b Move backwards one word M-f Move forward one word C-j, C-m In an editable field, finish the edit. In the source win- dow, start a new line. ESC Finish edit, in both editable fields and the source window. C-c Cancel edit (not an emacs bind- ing). C-k Delete to end of line C-u Delete to start of line (not an emacsbinding ) C-d Delete character under cursor M-d Delete word starting at cursor DEL Delete character before cursor M-DEL Delete word before cursor C-y Paste X selection M-> Move to end of buffer M-< Move to start of buffer If you run ups from a terminal (or a terminal emulator like xterm), it tries to discover what keys you are using for delete and line erase. If this fails it takes both ^H (backspace) and DEL to mean delete, and ^U to mean line erase. EDIT HISTORY Most of the editable fields in Ups have their own history of recently typed commands. For example, there is a his- tory of typing line commands, a history of breakpoint code entered, and a history of variable values changed. Pressing the Left mouse button on the History Button, the small region to the right of the typing line with the tri- angular image, pops up a menu of recently entered data for that field. When editing most single line fields, a Control-P, or up arrow moves the history pointer back one entry and replaces the current text with the previous entry. Typing a Control-N, or down arrow, moves the history pointer for- ward one entry. Edit histories are saved between sessions of Ups in ups- state/editHistory, if you use the ups-state feature, or in the file ~/.upsEditHistory if not. CUT AND PASTE You can select text with highlighting by pressing the left mouse button and dragging. Releasing the left mouse but- ton sets the X selection. You can paste text into an edit with Control-Y or by clicking the middle mouse button on the Enter Button (the small region to the right of the typing line with the "<<" image). Another useful trick is to define paste strings by using control characters in a custom menu: e.g. define setenv UPS_F1_STR "^e^u^y" setenv UPS_F2_STR "^y" then the right mouse button will invoke a menu: the first item clears the current text no matter where the text cur- sor is, and does a paste; the second just does a paste at the current location. See the section ENVIRONMENT VARI- ABLES AFFECTING UPS for details on custom menus. In the source window there are some extra shortcuts: o Pressing and releasing the left mouse button (with- out dragging) adds a variable name to the display as in previous versions of ups. Only if you move the mouse to a different character with the left button down do you get a plain X selection. o Doing a press-left-and-drag selection with the shift key pressed automatically pastes the selected text as an expression into the appropriate place in the stack trace. It is equivalent to selecting some text, selecting `add expr' for the appropriate entry in the stack trace, pressing ^Y to paste the text and hitting RETURN. o If you hold the shift key down, the press and release the left mouse button without moving the mouse, ups adds the expression under the mouse to the display area. It makes a reasonable attempt to select what to display. Try it out to see what I mean. See PASTING EXPRESSIONS FROM THE SOURCE WINDOW in the man- ual page for more information. In the display window, left button selects objects for operations, and one can pan vertically to select groups of objects. Selecting objects for some operation is distinct from making an X text selection. However, while the but- ton is down, if the horizontal distance from the original click exceeds a certain value, the window shifts from selecting objects to making an text selection. So one can easily just pan right to select a string for instance. The pixel value is 30 by defaults, but can be overridden with an X resource. See "X RESOURCES" for details. EDITING IN THE OUTPUT WINDOW You can edit in the output window (the window where $printf output goes. Click with the middle mouse button to display a cursor. You can then append or delete text. This is useful for tidying up output to make it clearer, or for deleting uninteresting stuff. You can also dump objects (like the stack trace) to the output window (see the `Windows' menu item to the left of `Quit'), and save or restore the output window contents from/to files (`Load' and `Save' in the output window menu). LISTING MATCHING SYMBOLS FOR BREAKPOINTS Pressing Shift-ESC, or Shift-RETURN when setting a break- point lists matching functions in the output window. So `*' matches all function names, and `file.c:*' matches all function names for `file.c'. ESC states how many matching functions there are, while holding the shift key down lists them in the output window. To list all functions in a program (and there may be many thousands) enter `*' then Shift-ESC. The full path names of source files are given when listing symbols. Stripped libraries contain no symbol information or file names, so it is not possible to use the `file_name:func- tion_name' syntax to specify a unique breakpoint via the `Breakpoint' header. For such cases, ups accepts a shared library name in conjunction with the function name. The syntax is `shared_lib_name:function_name' This allows breakpoints to be set in specific shared libraries when there are name conflicts. The width of the breakpoint text has been doubled to allow for longer breakpoint specifications. EXAMINING THE TARGET'S STATE When the target is stopped at a breakpoint or when ups has been started with a core file, the target's state is show in the form of a stack trace in the display area. This consists of a line for each active function giving the name of the function, the source line number of the line that was being executed, and the name of the source file containing the function. The stack trace appears under the Functions object in the display area. As an example, consider the following stack trace: Functions main main.c:42 docmd commands.c:84 getline io.c:21 In this example, execution in function main reached line 42, at which point main called docmd. In turn, docmd at line 84 called getline. Getline is stopped at line 21 (which is yet to be executed). When the target stops, the source of the innermost func- tion is displayed, with the line that is just about to be executed highlighted (displayed in reverse video). To look at the source of other functions in the stack trace: o Click the left mouse button over a line in the stack trace. The line is highlighted, and a menu appears near the top of the window with the cap- tions Expand, Collapse, Add expr, Source, and Path. o Click on Source in the menu. The source corre- sponding to the selected line in the stack trace is shown, with the line that is currently executing highlighted. In this way you can see exactly where the target is stopped at any level in the stack. If the initialization file has been used to load only cer- tain libraries, unloaded libraries will be indicated by the sytax in the stack trace. To load it, select the line and press "Load library". As always for objects in the display window, multiple objects in the stack can be selected at once, and loaded as a group. EXAMINING VARIABLE VALUES There are several ways to find the values of variables. The simplest and most often used is simply to click with the left mouse button on the name of a variable in the source region. A line is added to the display area which looks something like: int 73 In this example, an integer variable called varname with a current value of 73 is shown. The meaning of the angle brackets around the name is explained later - ignore them for now. If the variable is local to a function, it is added just below the line in the stack trace for that function. If the variable is global, an entry for the source file of the variable is added below the Source files object in the display area and the variable is displayed below that. In rare cases ups does not know the type of the variable, in which case it is assumed to be an integer and displayed under the Untyped variables object. Once the variable is added to the display, it remains there until its function returns (for a local variable) or you explicitly delete it (see later for how to do this). This means that you can watch the value change as you con- trol the execution of the target. As well as selecting individual variables to be shown, you can add all the local variables of an active function to the display. Select the function in the stack trace whose variables you wish to see, and select Expand from the menu produced. This will produce a popup menu with the options Like before and Completely. The default option is Like before - it means to make the display look like it did last time you looked at the local variables for this func- tion. If there is no `last time', all the local variables are displayed. The second Expand option (Completely) always adds all the function's local variables to the dis- play. To remove all the local variables select Collapse. You can subsequently put them back as they were using Expand, Like before. If you have saved state enabled, you can do this even after exiting ups and starting it again. See the SAVING STATE section for details. When you use Expand to add all the local variables of a function, you may see some lines like this: _______ lines 84..93 _______ These lines are added for variables declared within inner blocks of a function. In this example, there is an inner block starting at line 84 and ending at line 93 which con- tains local variable declarations (the line numbers are sometimes inaccurate because of bad information supplied by some compilers). If you click the left mouse button over one of these entries, a menu with the options Expand, Collapse, Add Expr Source, and Path, is produced. Select- ing Expand adds to the display all variables declared in the block. Collapse removes them again, and Source makes the first line of the block visible in the source region. Selecting Path brings up a sub menu with Used, Assumed, Rematch, Reload and Dates items. The Used item shows what file is actually being displayed in the source window. The Assumed item displays the assumed path name of the selected file as suggested by the target binary. If the file could not be found under the Assumed name, the Used name will be the first good match in the source path list. For C code, there is normally no problem in finding the source and hence the Used and Assumed paths will be the same. For Centerline C++ code, the two are usually dif- ferent. Ups uses symbol table function line number infor- mation to find the most likely match. This also allows different files of the same name to be located correctly. This feature removes the need to constantly rearrange the Use paths in the ups init file to accommodate debugging different targets. Ups outputs a message for C++ files indicating what file was matched. When no symbols are available for a function, both items print the library name for that function. If for some reason the match process described above gets the wrong file, it is possible to find the next match in the search path list. To replace the file with the next match, select the Rematch item in the Path menu. The Reload item will reload the currently selected file. A situation where this may be useful is, when in the middle of a debug session, it becomes apparent that the debugger is using version of a file that differs from the build version of the file. If the current version is newer than the object code, or the target, the file will appear in reverse video as a warning. To correct such a problem, restore the file, and reload. This will reload the text and also retest the file dates and remove the reverse video if appropriate. The Dates item shows the full names and dates of the source file, shared library if used, and target binary. See the later section CONTROLLING THE DISPLAY OF VARIABLES for information on (among other things) how to change the format of a displayed variable, indirect through pointers, expand structures and unions and step through the elements of an array. EXAMINING MACRO VALUES It is also possible to examine the value of macros if that information has been included by the compiler. This can be done by clicking with the left mouse button on the name of a macro in the source region. A line is added to the dis- play region which looks something like: macroname 86 In this example, a macro called macroname with a value of 86 is shown. This line is actually an expression, as described in EXPRESSIONS IN THE DISPLAY AREA below. Because macros do not follow the normal language scoping rules, there is sometimes an ambiguity about what value to use for a macro. The rule used by ups is that the value of the macro on the first line of the function where you evaluate the macro is shown. If you are using gcc(1) you need to use the -g3 command line option when compiling to include macro information. ACCELERATORS IN THE DISPLAY AREA A Shift-left click or double left click does the most com- monly used actions for the object listed below: env header Toggle between expanding and compressing the envi- ronment display. signal header Toggle between expanding and compressing the signal display. source header Toggle between expanding and compressing all source files. Files are expanded to `like before state'. If some files have variables or expressions dis- played, such files will remain visible when the source file list is compressed. Use the menu item "completely" to remove all source files. source files Toggle between expanding and compressing all the global variables of the file file add expr See the actions under "variable". function Toggle between expanding and compressing all the outermost local variables. Variables are expanded to `like before state'. function block Toggle between expanding and compressing all the local variables of the block func add expr See the actions under "variable". variable If the variable is a struct or union, or pointer to a struct or union, toggle between expanding and compressing the current level of the variable. If the variable is a pointer to data of integer type, dereference the pointer one level. If the variable is of integer type, or fully dereferenced pointer to a such a variable, toggle between unsigned hex and signed decimal formats. bpt header By default, toggle the global breakpoint enable flag. The BreakPointHeaderAcceleratorAction X resource may be set to request that ups prompt for a new breakpoint instead. breakpoint By default, toggle the current breakpoint between the active an inactive states. The BreakPointAc- celeratorAction X resource may be set to request that the breakpoint be removed instead. Double clicking ( but not shift-clicking) on the break- point in the source window selects has the same effect of toggling or removing breakpoint according to the BreakPointAcceleratorAction X resource. SOURCE FILES MENU There is a menu for compressing the source file list. It has options of "first level" and "completely". The Shift- left accelerator on the source file header is equivalent to "first level". When globals are displayed in ups, they appear under the source file name. The "first level" item only removes files that do not have any globals or expres- sions displayed. This cleans up the display, just leaving items of interest. The "completely" item removes all file names and globals from the display. If state has been saved from a prior usage of UPS on the same target, by creating a "ups-state" directory, the next invocation of the debugger allows you to restore the glob- als shown before. After the target is running, simply expand the source file list to show all files and the cho- sen globals, then compress the list to the first level to leave just the globals. BREAKPOINT MENUS By selecting a breakpoint, the Activate and Inactivate, captions control whether the breakpoint is either active or inactive. Active code is executed normally, whereas inactive code is ignored. The activation state is set by the two captions labeled Activate and Inactivate that appear after selecting the breakpoint object. The current state appears to the right of the breakpoint line number. The Execute caption can be used to execute breakpoint code whenever the target context allows it. The most common use for this is to repeatedly call a function, such as the Purify API functions purify_describe() or purify_all_leaks() without having to enter the call at every line in the source where it may be required. By selecting the Breakpoints header object, the captions labeled Enable and Disable allow global control of pro- cessing of breakpoints. When globally enabled, all break- point code is examined, and if the breakpoint is active, the code is executed. Conversely, when breakpoint code is globally disabled, no breakpoint code is executed, regard- less of its activation state. The current enabled state is implicitly shown by the shaded caption - so after pressing Disable, that caption is shaded and the Enable caption becomes normal. When globally disabled or individually inactivated, the breakpoint code will still exist in the source, but the code will be ignored until re-enabled. The target will run at full speed for such breakpoints. When typing in a breakpoint, pressing ESC does partial name completion whenever possible. So if a program has just two routines, `process_key()' and `process_cmd()', typing `p' then ESC will expand the line to `process_' and in the third line will be a message like `process_' matches `process_key' and `process_cmd'. Then typing `k' then ESC will complete the line to `process_key' See the LISTING MATCHING SYMBOLS FOR BREAKPOINTS section for details on listing the matches. SPECIAL HANDLING FOR SIGSEGV AND SIGBUS Some programs have exception handlers that allow the pro- gram to continue to run despite receiving SIGKILL, SIGSEGV or SIGBUS signals. If SIGSEGV or SIGBUS are changed from the default of `Stop - ignore signal on continue' to `Stop - accept signal on continue', ups will stop on the excep- tion, but allow the target to continue running upon press- ing Cont, Next, or Step. SIGSEGV or SIGBUS signals that intercepted by third party software such as ObjectStore can be handled by setting the signal to accept and continue. Do not use ignore as then the target never gets the signal and it will appear to hang. However, when set to accept and continue, the target can crash on bad code, but ups will not catch it. For such cases, set a breakpoint in the a target's signal handler (if it has one), or change `accept' to `stop'. CONTROLLING TARGET EXECUTION Once you have the target stopped at a breakpoint there are several ways of controlling its execution. Most of these are invoked from the target menu - the permanent menu just below the display area. The usual way of debugging is to set a breakpoint in the function which you think is misbehaving and then step through its code one line at a time. The GETTING STARTED section above explains how to set breakpoints and start the target running. To step over a line of source, select Next from the target menu. The code on the highlighted line is executed, and the highlighting moves on to the next line to be executed. The values of variables in the display area are updated every time the target stops, so you can watch values change as you step through the code. On colour displays variables are shown in a different colour if their values have changed since the last time the target stopped. If the line to be executed calls a function, Step takes you to the first line of the called function, and stepping continues in the function. The step action may take some time occasionally; however the Stop command can be used to break out such a situation. If you don't want to step through the code of called functions in this way, use the Next command. This behaves like Step, except that it never steps into called functions. Both Next and Step work with respect to the currently dis- played source. If you click on a function in the stack trace and select Source to display its source, a subse- quent Next or Step moves to the next line of the displayed source. This makes it easy to get out of a function that you have stepped into by accident and don't wish to step all the way through. Use the Source command to display the source of the calling function, then use Next or Step. The Cont command in the target menu offers a third way to control the target - this command runs the target until it hits another breakpoint, gets a signal, or exits. See the section THE SOURCE REGION for details about the Attach and Detach buttons. Finally, you can `drag' execution in the target to a line in the source file. Move the mouse cursor over the line you wish to get to, and press and hold down the right mouse button. A popup menu appears, with the captions Add breakpoint Execute to here. Jump to here. and Edit source. Drag the mouse down so that the Execute to here caption is highlighted, and release the button. The effect of this is to set a temporary breakpoint at the line, temporarily disable all other breakpoints, and then continue the target. You can use this command to move past uninteresting bits of code without having to set up and remove breakpoints. The second command on the popup menu, Add breakpoint, adds a breakpoint at the line of source you pointed at. Unfor- tunately, to set a breakpoint at (or execute to) a single statement that extends over several text lines, you must point at the last text line. This is due to limitations in the symbol table information put out by the compilers. The Jump to here command causes the target execution to jump to the current line without executing any intervening code. Use this with caution as it is possible to jump to a bad context where the data is bad or where there is no valid call stack. The safest usage is to jump over lines within a function. It can also be used to jump back within a function. If you try a jump to an invalid context, such as to a point up in the stack, you can use the stop button to restore the program to the state it had before the jump. When the current lowest level function has no sym- bols (such as "poll"), you will need to press the stop button twice to restore the program state. The Edit source command spawns an editor (typically either emacs or vi), and set the cursor at the current location in the file. The editor used is controlled by the EDITOR environ- ment variable. You can stop the target running at any time by clicking on Stop in the target control menu. The target will then stop wherever it is currently executing as if it had hit a breakpoint. In addition, if a symbol search puts the debugger in a long traversal of stack functions or files, the stop command will break it out of the search. The com- mand is queued, and will be honored after completing the scan of the current function or file. In addition, the stop command will break out of a step command that is tak- ing a long time. The Kill command kills off the current instance target process. You can then use Start or Execute to here to start the target again. Quitting ups also kills the tar- get process (unless you attached ups to a running process, in which case ups detaches from the process and leaves it to continue unmolested). THE TYPING LINE MENUS The caption labeled Windows, just to the left of the Quit caption, provides a number of options loosely related to coordinating the various UPS windows. The Snapshot Selected Objects item dumps objects (like the stack trace) to the output window. The Snapshot All Objects item dumps the complete display to the output window. The Message Logging item toggles on or off the copying of all subse- quent messages printed to the message line to the bottom window. As well as providing a log of messages, this facility allows the text of messages to be selected for pasting. This allows a path that has been displayed with the path caption to be pasted when setting a breakpoint in a function name that is not unique. The four items No Raise On Break, Raise On Break, Raise On Break/Lower On Run and Raise On Break/Iconify On Run select how ups manages its window(s) when the target pro- cess goes in or out of run. The default action is No Raise On Break, that is, no special action is taken. If Raise On Break is selected, ups will automatically raise its main window to the foreground when the debugged appli- cation stops. If Raise On Break/Lower On Run is selected, then in addition to raising the main window on a break, ups will lower the main window to the bottom of the window stack, after a brief delay, when the process goes into run. If Raise On Break/Iconify On Run is selected, then in addition to raising the main window on a break, ups will iconify the all windows, after a brief delay, when the process goes into run. In split screen modes, these options raise or lower the window containing the source display and start/next/step buttons. The initial state of these options may be set using the WantRaiseOnBreak family of X Resources (see the section X RESOURCES below), or by the -raise_on_break, -lower_on_run, and -iconify_on_run command line options. The button labeled Search to the left of the Windows but- ton is used to search for regular expressions (using the same syntax as grep(1) patterns) in the display window. First type in the pattern to be searched for (typed char- acters appear in the typing line at the top of the window on the left) then press and hold down the left mouse but- ton over the Search caption. A popup menu appears with the options Backwards and Forwards. Move the mouse over the one you want and release the button. If the pattern is found, the matching text is made visible in the display region and highlighted. The button labeled Help to the left of the Search button provides simple textual help information on a variety of topics. Output is placed in the bottom output window. By default, the text is appended to the bottom of the window, with the scrollbar positioned so that the topic begins at the top of the window. The last item in the help menu allows the window to be cleared before a new help topic is printed out. TARGET COMMAND LINE The first line of the display area shows the command line that specifies the target to debug. It can be edited and changed to a different target at any time in order to debug a different target. It accepts csh style tilde nota- tion. When changing targets, ups will read new symbols as necessary and reinstate breakpoints and variables as pos- sible. So if you are working on a shared library, and you need to test it with different targets, simply enter the new target name and attach, and the debug state informa- tion will be preserved. TARGET COMMAND LINE ARGUMENTS The second line of the display area shows the command line arguments that will be given to the target when it is next started. The arguments shown include the zero'th argument which is initially set to the name of the target. You can specify an initial set of arguments for the target with the -a option when you start ups. If you don't give the -a option and you are debugging from a core file, ups attempts to extract the command line arguments from the core file. Otherwise the command line contains no argu- ments other than the name of the target. Ups parses the command line in a similar way to the shell. It supports Bourne shell type redirection (>, >>, <, >&dig, etc.) as well as the csh forms >& and >>&. Ups also understands most csh metacharacters - globbing with `*', `?' and `[xyz]', the `~', `~user' and `{a,b,c}' shorthands, and quoting with single or double quotes and backslash. The current version of ups does not support $var type shell variable substitution. You can edit the command line at any time to change the command line arguments (although the changes will only take effect when you next start the target). The command name shown is just the zero'th argument and can be edited just like the other arguments. This is use- ful with programs which use the zero'th argument as a sort of hidden flag. Changing the command name only affects the arguments given to the target - it does not change which program is being debugged. CONTROLLING THE DISPLAY OF VARIABLES When you add a variable to the display (see EXAMINING VARIABLE VALUES above) it is displayed in a default for- mat. If you click the left button over the line for the variable, a menu appears in the top part of the window. You can use this menu to set the display format for the variable ( Format) , to change the level of indirection for pointers (* and &), to expand all base classes and show vector tables for a class ( ::), to show all the mem- bers of structures and unions ( Expand and Collapse), to choose the format variables are displayed in Format, to duplicate or delete entries for variables ( Dup and Del) to control whether typedefs are used in displayed vari- ables ( Decl) and if watchpoints are available, add a watchpoint at the variable address ( Watch) Pointers The default for a pointer variable is simply to show the pointer value in hex. To take a common example, if you add a variable of type pointer to pointer to char called argv to the display, you will get a line like: char ** 0x7fffe184 The angle brackets separate the type from the value. In this example, what is shown is the value of argv, which is of type char **. If you now click with the left mouse button on this line, and select `*' (the leftmost caption) in the variables menu, the format of the line changes to something like: char * 0x7fffe1d0 This says that what is shown is the value of argv[0], which is of type char *. The braces (`{' and `}') are used to distinguish a dereferenced pointer from a true array. A second click on the `*' menu option changes the line to: char "foo" This is a special case in ups - variables of type char are displayed as strings if they are indirected pointers or members of arrays. The `&' menu option is the opposite of `*' - it drops one level of indirection. You can only use this on indirected pointers. Use an expression if you want to see the address of a variable (see EXPRESSIONS IN THE DISPLAY AREA below). Arrays Arrays are initially displayed with all subscripts zero. You can edit the subscript to another value by clicking on it with the middle mouse button. A marker bar appears, and you can use the delete key to delete the old subscript and type a new one. When you hit ESC, the value of the new array element is shown. Often you wish to quickly scan through all the elements of an array. You can do this using either the arrow key or the `>' and '<' keys. When editing an array subscript, the '>' key adds one to the subscript value and displays the new element. Note that the ReverseArrows X resource can be used to reverse the function of the arrow keys. Similarly, the '<' key subtracts one from the subscript value. Using these keys you can rapidly scan up or down an array. Emacs users can use ^P and ^N as synonyms for '<' and '>'. Vi users can use 'k' and 'j' similarly. The arrow (or whatever) keys actually act on the digit to the left of the cursor, so by moving the cursor left you can step by tens, hundreds etc. Structures Note: in this section `structures' also include unions: they are simply treated as structures with all members having an offset of zero. Variables that are structures or pointers to structures are initially displayed with just the address in hex. You can use the Expand command in the variables menu to add all the members of a structure to the display. The struc- ture members are indented to make it clear which structure they belong to. Clicking on Expand will produce a popup menu with the options Expand Structure and Expand Static Variables. Selecting Expand Structure will display all the non-static members members of the structure except vector tables. ( See the section EXAMINING BASE CLASSES AND VECTOR TABLES below for vector tables.) If the selected item is a member of a class with static members, the Expand Static Variables option will show all the static members of the class. See the section EXAMINING STATIC MEMBERS OF CLASSES below. If a structure element is itself a structure or a pointer to a structure, it can be expanded in turn to show all its members. In this way linked data structures can be explored. For a more selective way of exploring a linked data structure, see the EXAMINING LINKED DATA STRUCTURES section below. Show size will display size of the arrays and structures (but not memory sizes that may have been allocated to a pointer - such variables will the standard 4 bytes). Note that in the display window, a variable formatted as "type " indicates an array, whereas "type " indicates a pointer. To remove all the members of a structure from the display, use the Collapse command in the variables menu. This has a submenu with the options First level and Completely. The first of these removes all members except expanded ones; the second recursively collapses all expanded struc- tures below the selected one. Changing formats By default integer variables are displayed in decimal and pointer values are shown in hex. You can change the for- mat with the Format command in the variables menu. The possible formats are signed or unsigned decimal, hex, octal and binary, as well as `ascii' and `string'. The `ascii' format displays integers in C character notation (e.g. the value 65 is displayed as `a'). The `string' format is applicable to variables of type char that are indirected pointers or arrays - it treats the address as the first character of a NULL terminated string. Floating point values are shown in the conventional nota- tion (using the printf %g format). You can use the Format command to display a hex representation of the value (it makes no difference whether you select signed or unsigned hex from the menu). This shows in hex the bit pattern used to represent the floating point value. Duplicating and deleting entries The Delete command in the variables menu deletes all selected variables from the display area. This is useful for tidying up the display by removing variables that are no longer of interest. Sometimes it is useful to have a variable displayed more than once. One common case is where you want to see sev- eral elements of an array simultaneously. The Dup command in the variables menu duplicates the entries for all selected variables. So to see multiple elements of an array, use Dup to add an entry for each element you wish to see, then edit the subscripts separately for each entry. When duplicating a pointer variable for which the contents of the pointer is displayed, the array index is bumped by 1, or by 40 if a string is displayed. Use of typedefs If a structure, union or enum has a typedef name then ups will use it in the display area. Thus if you have the following in a function: typedef struct foo_s { int x; int y; } foo_t; foo_t *f; then clicking on variable f will add a line like: foo_t * 0x40ec to the display area. Typedefs are not used if they hide a level of indirection or an array, or if the typedefed type is not a struct, union or enum. If you want to see the non-typedef type for a variable in the display area, select the variable and press and hold down the left mouse button over the Decl command in the variables menu. This produces a popup menu with the cap- tions Use typedefs and Ignore typedefs. Release the mouse over Ignore typedefs and you will be shown the non-type- defed type for all the selected variables. CHANGING VARIABLE VALUES You can change the value of a displayed variable simply by editing the displayed value (i.e. by clicking on it with the middle mouse button and editing in the new value). This works for C pointers and integral types (including enums), floating point values and strings. You can use any of the integer display formats for the new value (decimal, hex, octal, binary or ASCII character). You can use enum constant names for new enum values, and function names for function pointers. When editing strings or characters you can use the standard C notation for special characters (`\n', `\b', `\007' etc). Normally ups will not let you edit extra characters into a string as this would overwrite whatever was stored in mem- ory just after the string. If space is known to exist (for example if the string is stored in an array of known size and there are unused bytes) then you can add as many characters as will fit. If you know you want to overwrite memory beyond the end of the string you can force ups to accept a long value by putting `>>' before the leading quote character of the string. Normally a trailing NUL ('\0') is added to the edited string in the normal C way. If you delete the trailing quote character then this is omitted. EXPRESSIONS IN THE DISPLAY AREA You can add C expressions as well as variables to the dis- play area. This is useful if you wish to see what an expression in the source code evaluates to. It also allows you to use casts when you know better than the source code what the type of a given variable is. To add an expression, select a function in the stack trace and click on Add expr in the function menu. A marker bar appears, ready for you to enter an expression. When you have finished type ESC, and if the expression is legal the value will be displayed. If there is an error in the expression you will get an error message and the marker bar will be repositioned at the point of the error. A workaround for dealing with preprocessor macros is to create a repltab file. Ups will look in ups-state/repltab below the current directory. If that file does not exist, it will look for $HOME/repltab. See the section PASTING EXPRESSIONS FROM THE SOURCE WINDOW for details on the repltab file. In an expression you can use any variable name, structure tag or typedef name that is in scope in the function. If you want to add expressions using a variable in an inner block, you will have to add the expression to the appro- priate inner block. The easiest way to get the inner block object displayed is to click on a variable in the inner block in the source region. Once it is displayed select the block header and click on Add expr in its menu. If your compiler has included macro information as part of the debugging data then you can also use macro names in an expression. When you do this the macro is assumed to have the value which it held on the first line of the function where you have entered the expression. You can `bump' numbers in expressions in a similar way to array subscripts. Hitting the down arrow (or Control-N) over a number while editing an expression increases the digit to the left of the marker bar and displays the new value of the expression. Similarly the up arrow (or Control-P) decreases the digit to the left of the marker bar and redisplays the expression value. Expressions are reevaluated like variable values every time the target stops. They also have the same menu asso- ciated with them as variables, and you can have both expressions and variables in the same selection. All the menu commands work as they do on variables. This means in particular that if you add an expression whose type is `pointer to struct' (or union) you can use Expand to show the structure elements. You can also use Format to change the format used to display the expression value. You can call target functions in expressions, but you can't modify target data in a display area expression (thus operators like `++' are illegal). EXAMINING BASE CLASSES AND VECTOR TABLES When the object selected is a class, clicking on :: recur- sively adds all base classes for the object to the dis- play, and displays the vector table(s), showing the address symbolically when possible. This is useful if you want to expand a base class to look at a member of a base class several levels deep in the class hierarchy, without expanding everything in between. In addition, it is usually possible to tell from the name of the vector table which subclass of the current class the object is "really" a member of. A special case worth knowing about occurs when the selected object has been deleted. In this case, the vec- tor table will indicate that the object is a member of the root class for the class hierarchy, rather than of any subclass. For example, consider the short C++ program: class A { public: A() { cnt++;} virtual ~A() { cnt--;} private: static int cnt; }; int A::cnt; class B : public A { public: void bad(); virtual void v() {} }; class C : public B { public: virtual void v() {} }; void B::bad() { delete this; v(); } main() { C* c = new C; c->bad(); } If you stop at the start of B::bad(), click on "this" then select "::", you will see something like: Functions main B::bad B* 0x12345678 struct A 0x12345678 void *<_vtbl.> C::__vtbl Breakpoints The _vtbl entry shows that "this" is really a C, a sub- class of B. When you single step over the delete, the display changes to Functions main B::bad B* 0x12345678 struct A 0x12345678 void *<_vtbl.> A::__vtbl Breakpoints Since class A is a base class for B, seeing that "this" is really an A in a method for class B is surely an error, and often results from object having been been deleted. The expansion of base classes only works for compilers that include base class information in their symbol tables, namely for g++ and SC4. The symbolic representa- tion of vector tables works for both of these and also for cfront. EXAMINING STATIC MEMBERS OF CLASSES Static members of classes may be examined as other global data. In addition, depending on the compiler, they may be examined as members of a structure are examined. In the example in the previous section, the static member A::cnt may be displayed by Typing "A::cnt" in the typing line. Clicking on "A::cnt" anywhere in the source window. In addition, if the compiler supplies information about static members in the symbol table (g++ and SC4 do this), A::cnt may be examined by: While in a NON-static method for class A, click on "cnt" in the source window. Select an object of type A and enter ".cnt" in the typing line. Select an object of type A, press the Expand option then select Expand Static Variables from the resulting popup menu. This latter option displays all static members for class A. PASTING EXPRESSIONS FROM THE SOURCE WINDOW It is often useful to display the value of an expression in the source. You could select Add expr as described in the previous section, and cut and paste the expression from the source window. This works, but there is a quicker way: simply select the text of the expression in the source window while holding the shift key down (i.e. press the shift key, then drag the mouse over the desired text). When you release the mouse button, the selected text is added as an expression in the display area. It is OK to drag over multiple lines. You will notice that when you first press the left mouse button (with the shift key pressed), ups highlights some text. This is its guess as the to expression you would like to paste. If you are happy with this, release the mouse button without moving the mouse, and the highlighted text will be added as an expression. If the highlighted text is not what you want, drag the mouse to make the selection as described before. Pasting expressions from the source window can often fail because of preprocessor macros which ups does not under- stand (e.g. NULL). The correct fix for this is for ups to understand #defines, but in the interim there is a workaround: if the file ups-state/repltab exists below the current directory ups will apply the substitutions speci- fied there. If that file does not exist, it will look for $HOME/repltab. Here is a repltab file that would deal with NULL and EOF: # Repltab for ups NULL 0 EOF (-1) Hash comments and blank lines are ignored in the normal way. Any substitutions will be visible in the pasted expression. Ups checks to see if the repltab file has been updated each time an expression is pasted, so you don't have to restart ups to it to notice changes. ADDING INTERPRETED CODE The ups display area gives a good picture of that state of a program at any one time. Often though, you want a record of what happened over a series of calls of a func- tion. This is one of the reasons why people still tend to put print statements in code despite the availability of debuggers and the inconvenience of recompiling the code. To make it easier to add diagnostic output statements, ups allows you to insert fragments of C code at any break- point. The default breakpoint action - stopping the tar- get - is represented as a fragment of pseudo C code. This is the #stop; line that appears in the source region when you add a breakpoint. You can change this to a fragment of C code, editing the text in the usual way by clicking the middle mouse button to position a marker bar. You can use the RETURN key to enter multi-line code fragments. As with other editable fields, you end the edit with ESC. If there is an error in the code, an error message is given and the marker is positioned at the point of the error. For example, you could change the breakpoint action to: printf("Entered function foo with x = %d\n", x); From now on, whenever the target reaches this point in the program, it will call printf rather than stopping. Note that a breakpoint will not stop the target unless the special keyword #stop is executed. You can use this to set conditional breakpoints, like: if (i == 72) #stop; or, to use a more sophisticated example: if (strcmp(p->p_name, "foo") == 0) #stop; In the above examples, the function calls (printf and str- cmp) are implemented as calls to functions in the target. You can call any target function from a breakpoint, but in the current version of ups all functions are assumed to return int. You can often get around this by casting the return value to the correct type. One problem with calling functions like printf to do diag- nostic output is that the output is mixed up with the nor- mal output of the target program. If you want the output kept separate, use the built in ups function $printf. This function creates a new region in the ups window the first time it is called, and sends output to that region. The menu at the top of the region allows you to search for regular expressions in the output, as well as page through it and clear all output. The $printf function takes the same format string as printf, with one addition. The `%v' format string can be used with any variable type, and means print in the default ups format for the type. The `%v' format charac- ter will print symbolic names for enum values and function pointers (i.e. you will get output like RED and close_callback rather than 23 and 0x5e748. In addition `%v' applied to a struct or union pointer will print the names and values of all the fields of the pointed-to struct or union. You can declare your own variables in breakpoint code. This is useful when you want only want to stop at a break- point after it has been hit a given number of times. A code fragment to do this would look something like: { static int count = 0; if (++count == 74) #stop; } This would stop the target the 74th time the breakpoint was encountered. Static variables are reinitialized every time the target is started. Automatic variables are uninitialized and do not preserve their values between separate executions of breakpoint code. You can mix C interpreter variables with real target vari- ables in expressions in breakpoint code, with some restrictions. You can assign to target variables, but making a target pointer point at an interpreter variable will not work, as interpreter variables do not exist in the target's address space. On the other hand, the inter- preter knows about the target address space, so you can point interpreter variables at target variables. Note that you can only add interpreted code - you can't directly affect the flow of control of the compiled code. For example adding a return statement will not cause the compiled function to return to the caller. It is some- times possible to indirectly affect the flow of control by judicious changes to variable values. You cannot add C interpreter variables to the display; if you click on a variable in interpreted code it is taken to be a variable from the target process. [ You probably want to skip this paragraph. ] For people who want to live at the ragged edge, the C interpreter uses copy-in copy-out semantics when passing interpreter addresses to the target. If you pass an argument of type pointer to T to a compiled target function then the inter- preter copies sizeof(T) bytes to the target address space and passes a pointer to that copy. When the target func- tion returns the same number of bytes are copied back from the target into the interpreter address space. Similarly when you pass an array, the contents of the array are copied in and out. Note that this mechanism does not work in general - it only copes with passing an array or a pointer to a single object. The main motivation for this feature was to make string literals (e.g. "hello") work as expected when passed to target functions like strcmp. EXAMINING LINKED DATA STRUCTURES Ups has several facilities that are useful for examining linked data structures. Firstly, you can expand struc- tures or structure pointers. By repeatedly expanding structures you can follow down a linked list or tree. Often this adds too much information to the display, as you are probably not interested in all the structure ele- ments. There is a more selective method of expanding lists and trees which lets you easily see just the ele- ments you want. Suppose you have a structure declaration like this: struct linkst { struct linkst *prev, *next; int key; }; Suppose also that you have a variable linkptr displayed which is a pointer to this structure. If you type in a `.' followed by the name of element, such as prev, that element of any selected structures or struc- ture pointers will be added to the display and selected when you hit ESC. Assume linkptr in the example above is displayed and selected. Typing .next followed by ESC will add the next field of linkptr to the display and select it, and dese- lect linkptr. Typing ESC again will add the next element of the list. Thus by repeatedly typing ESC you can easily walk down a linked list. You can give many structure elements separated by spaces. Thus the line .key .next would add both fields to the display. In this way you can walk down a linked list with members of interest displayed as well as the links. One problem with this way of looking at lists is that the indentation of structure elements tends to make the list wander off the right hand side of the display area. To avoid this you can say `@member' rather than `.member'. The `@' character means do not indent - this is the only difference between it and `.'. Thus to get a nicely laid out list in the example above you could enter the line: .key @next and keep typing ESC to walk down the list. One last wrinkle: if you add `#nnn' to the end of the typ- ing line, where `nnn' is a decimal number, the effect is as if you had pressed ESC that number of times. This is handy if you want to see all of a 500 element linked list without having to type ESC 500 times. In C interpreter code (described in the previous section) you can scan through a linked list as if it were an array using the (non-standard) `->[count]' operator. This is a shorthand for applying the `->' operator count times. You can use the arrow keys (or ^N and ^P) as described in EXPRESSIONS IN THE DISPLAY AREA to bump the count parame- ter up or down and step through a linked list one element at a time. Thus in the example above, adding the following expression to the display area: linkptr->[0]next would just show the value of linkptr (the -> operator is being applied zero times). You can expand the structure and add and delete elements to get the display set up as you like. Then you can edit the `0' to `1' to see the next element of the list, and so on. DUMPING MEMORY The contents of raw memory may be dumped to the output window in two ways. If the memory to be dumped is the address of a simple variable or structure, or is pointed to by a pointer variable, select the variable of interest, press the Expand option then select Dump Memory from the resulting popup menu. This option displays the contents of memory at the selected address. The length of memory displayed, and the grouping (as bytes, shorts, or longs) is based on the type of object selected. This option also prints in the output window the equivalent typing line command, which you may copy to the typing line and edit as required. The commands to display memory through the typing line begin with "%d" (for dump): %d address [size|.. end_address] dump size bytes of memory at address %db address [size|.. end_address] dump size bytes of memory as bytes at address %ds address [size|.. end_address] dump size bytes of memory as shorts at address %dl address [size|.. end_address] dump size bytes of memory as longs at address If the size is omitted, 16 bytes are displayed. If the grouping is unspecified, bytes or shorts are selected depending on target endianness. ENVIRONMENT VARIABLES By default the target inherits the same set of environment variables as ups . You can change this using the Environ- ment object in the display area. Any changes to the tar- get environment take effect the next time the target is started. Selecting the Environment object produces a menu with the commands Expand, Collapse, Add entry and Reset env. The Expand command adds an entry to the display area for each environment variable. You edit an environment variable name or value by clicking on it in the normal way with the middle mouse button. Collapse removes all the entries from the display area. To add a new entry select Add entry from the environment menu and type in the `name=value' string. Ups will accept any string as an entry, but gives a warning for odd-look- ing entries. If you wish to abandon any changes you have made to the environment select Reset env. This resets to the environ- ment to the state it was in when ups was started. If you select an individual environment entry you get a menu with the options Hide, Delete and Append entry. The Hide command removes the entry from the display but not from the environment. This is useful for clearing the display of uninteresting entries. By contrast the Delete command removes the entry from the environment. The Append entry command allows you to add a new environment variable just after the one selected; this is useful if you need the environment set in a particular order. SIGNALS When the target gets a signal control returns to ups. Depending on the signal and the way you have specified it should be handled, the target is either stopped or restarted (possibly with a display refresh), and the sig- nal can either be passed on to the target or ignored. Near the top of the main display area is a Signals object. Selecting this produces a menu with Expand and Collapse as options. Expanding the signals object produces a list of all signals, with the current way the signal is handled displayed for each signal. Selecting a signal produces a menu which lets you change the way it is handled. You can control whether a given signal causes ups to stop the target, refresh the display and continue the target or just continue the target without refreshing the display. You can also control whether the signal should be passed on to the target. You can trim the signals display by selecting the ones you aren't interested in and clicking on Hide in the signals menu. This will remove those signals from the display area. The `Next' and `Step' commands both step over functions called as a result of a signal. Breakpoints in signal handling functions work normally. TYPING LINE SHORTCUTS A few frequent requests can be invoked by typing input as an alternative to mouse operations. o Typing "%g name" will display the global variable or function `name', skipping the sometimes slow search for `name' as a local variable. o Typing "%l file" will list 'file', the same as expanding the list of source files and clicking on a file name. It is only necessary to enter the final component of the file name. o Typing "%b function" will enter a breakpoint at the entry to `function', the same as clicking on the breakpoint header, selecting "add breakpoint", and entering the function name. o Typing "%d address" will dump 16 bytes of memory at the given address to the output window. See the section DUMPING MEMORY for more on the %d command. o Typing "/pattern" or "?pattern" will do a forward or backward search for pattern. The search may be continued in the same direction by hitting RETURN, or in either direction using the Search pulldown menu. X AND SUNVIEW COMMAND LINE FLAGS Under SunView ups recognizes the standard SunView tool flags. These can occur anywhere on the command line. Under X ups recognizes most common X11 command line argu- ments. The currently recognized flags are: -iconic Start up as an icon rather than as a window. -display displayname Create a window on the named display rather than using the value of the DISPLAY environment vari- able. -geometry geometry Use the specified X geometry for the window. -name name Use name rather than the default ups as the window and icon name. This name is also used when fetch- ing X defaults. -fn fontname Use X font fontname rather than the default. -fg colorspec Use colorspec (which should be a standard X11 color specification) as the color of the foreground pixel. -bg colorspec Use colorspec as the color of the background pixel. -rv Reverse the foreground and background pixel colors. These options are available under X and SunView: -mono Force monochrome mode even if when using a color display. Use this flag to stop ups interfering with the colormap on pseudocolor displays (e.g. when you are debugging a program with a colormap related problem). The flag is also useful on some Sun displays under SunView where using monochrome significantly increases the display speed. -wn_record filename Record mouse and keyboard events in file filename. -wn_replay filename Read mouse and keyboard input from file filename rather than the mouse and keyboard. The file file- name must have been created with the -wn_record flag in a previous session. -wn_replay_warp When replaying events with -wn_replay, warp the mouse in the ups window to reflect the recorded mouse movement events. X RESOURCES Ups recognizes a number of X defaults. By default it uses the last pathname component of the name you run it with as the application name when looking up resources (i.e. if you run it as `/usr/bin/ups' it will use `ups'). You change the name with the -name flag described above. If it fails to find a resource with the application name, ups does a lookup using `Ups' (note the initial upper case letter). A resource specified as `Ups.xxx' will thus always be noticed. Finally ups looks in the resource file /usr/lib/X11/app-defaults/Ups if a resource is not found anywhere else. (In addition to the above directory, ups looks for the file Ups in the colon separated list of directories given by the environment variable XUSERFILE- SEARCHPATH, and in the single directory given by the envi- ronment variable XAPPLRESDIR.) The current list of recognized resources is: Font The name of the normal font. The default is `fixed'. MenuFont The font used for menu captions. The default is to use the normal font. SrcFont The font used for text in the source window. The default is to use the normal font. EditFont The font used for editable text in the source window. The default is a bold version of the nor- mal font (using the name formed by replacing medium with bold in the font name). If this substitution cannot be made, ups tries -*-fixed-bold-r-nor- mal--15-*-*-*-*-*-*-*. If this font is unavail- able, ups complains and uses the normal font. Foreground The color of the foreground pixel. The default is whatever the BlackPixel macro returns for the dis- play. Background The color of the background pixel. The default is whatever the WhitePixel macro returns for the dis- play. ReverseVideo If this is set (to anything) it has the same effect as the -rv flag. WantInstalledColormap If this is set to "yes", ups will install its own colormap, rather than use the default colormap. Use this if ups complains that it failed to allo- cate some colors. The same effect can be achieved by using the command line option "-install". Note that the command line option of "-noinstall" will override the resource. Geometry The size and (optionally) position of the main ups window. The default is to suggest to the window manager a window 580 pixels wide by 550 pixels deep at a user-specified position. Most window managers will of course let you sweep out a window of the size you require. In the split window modes, the source and output windows have their own Geometry resources. Set the resource Ups.Src.Geometry to specify a geometry for the ups Source window, and Ups.Output.Geometry to specify the geometry for the ups Output window. Or set the resource Ups*Geometry to specify the same geometry for all ups windows. EditlinesColor The color used for editable text in the source win- dow. The default is blue. ColorVars Can be set to "off" to disable coloring of variable names. VariableColor The color used for variable names in the display area. The default is purple. HighlightColor The color used to highlight variables in the dis- play area whose values have changed since the last time the target stopped. The default is red. WantMenuColors If set to `yes', ups will use foreground and back- ground menu colors as listed below. If not set to `yes', such settings are ignored, and the Fore- ground and Background resources are used. MenuForeground, MenuBackground The default colors for text and background in all buttons and menus. Sub menus inherit the colors of their parents unless specifically overwritten. DisabledTextColor The color for text that is disabled, such as the `start' caption after starting the target, or glob- ally disabled breakpoints. LastButtonTextColor The text color of a busy button pressed (such as `cont' while the target is executing) or the parent menu item of a sub menu. SourceMenuForeground, SourceMenuBackground The text and background colors of the pop up menu for the source window. CustomMenuForeground, CustomMenuBackground The text and background colors of the custom pop up menu for editing text strings. FileBoxMenuForeground, FileBoxMenuBackground The text and background colors of the pop up menu for the file name and line number box that is directly above the source window. UnloadedLibMenuForeground, UnloadedLibMenuBackground The text and background colors of the pop up menu for the "Load library" menu invoked from the target line. Foreground, Background The text and background colors for a menu item with a specific text caption: for example "Add break- pointForeground". Note that embedded spaces are allowed. AsteriskForeground, AsteriskBackground The text and background colors of the "*" menu cap- tion that appears when selecting a variable. This caption uses a special resource name in order to resolve a conflict with main foreground and back- ground resources. WantExtendedTextColors If set to `yes', ups will use the colors for the text items in the display window as listed below. If not set to `yes', such settings are ignored. SignalTextColor The text color of the signals listed under the `Signal' header. EnvironmentTextColor The text color of environment strings listed under the `Environment' header. SourceFileTextColor The text color of the file names listed under the `Source files' header. FunctionTextColor The text color of the function names in the stack under the `Functions' header. BreakpointTextColor The text color of active breakpoints listed under the `Breakpoints' header. Inactive breakpoints are in the main foreground color, as is the text of breakpoint code in the source window. WatchpointTextColor The text color of active Watchpoints listed under the `Watchpoints' header. Inactive watchpoint are in the main foreground color. MouseholeWidth The width of the mousehole in pixels. WantWatchpoints If this is set to `yes', watchpoints will be avail- able. On x86 machines, watchpoints are available be default but watchpoint action is unreliable on othe