sdb(CP) 6 January 1993 sdb(CP) Name sdb - symbolic debugger Syntax sdb [-w] [-W] [[objfile [corefile]] [directory:directory:...] [[corefile|-]] Description The sdb command calls a symbolic debugger that can be used to debug C programs. It may be used to examine their object files and core files and to provide a controlled environment for their execution. The command-line options available are: -w While a process is running under sdb, all addresses refer to the exe- cuting program; otherwise they refer to objfile or corefile. An ini- tial argument of -w permits overwriting locations in objfile. -W By default, warnings are provided if the source files used in produc- ing objfile cannot be found, or are newer than objfile. This check- ing feature and the accompanying warnings may be disabled by the use of the -W flag. objfile is a COFF format executable program file which has been compiled with the -g or -Zi (debug) option. If it has not been compiled with a debug option specified, the symbolic capabilities of sdb will be limited, but the file can still be examined and the program debugged. The default for objfile is a.out. corefile is assumed to be a core image file pro- duced after executing objfile; the default for corefile is core. The core file need not be present. A ``-'' in place of corefile will force sdb to ignore any core image file. It is useful to know that at any time there is a current line and current file. If corefile exists, then they are initially set to the line and file containing the source statement at which the process terminated. Otherwise, they are set to the first line in main(). The current line and file may be changed with the source file examination commands. Names of variables are written just as they are in C. sdb does not trun- cate names. Variables local to a procedure may be accessed using the form procedure:variable. If no procedure name is given, the procedure containing the current line is used by default. It is also possible to refer to structure members as variable pointers to structure members as variable->member, and array elements as variable[number]. Pointers may be dereferenced by using the form pointer[0]. Combinations of these forms may also be used. A number may be used in place of a structure variable name, in which case the number is viewed as the address of the structure, and the template used for the structure is that of the last structure referenced by sdb. An unquali- fied structure variable may also be used with various commands. Gen- erally, sdb will interpret a structure as a set of variables. Thus, sdb will display the values of all the elements of a structure when it is requested to display a structure. An exception to this interpretation occurs when displaying variable addresses. An entire structure does have an address, and it is this value sdb displays, not the addresses of indi- vidual elements. Elements of a multidimensional array may be referenced as variable[num- ber][number]..., or as variable [number,number,...]. In place of number, the form number;number may be used to indicate a range of values, an asterisk (*) may be used to indicate all legitimate values for that sub- script, or subscripts may be omitted entirely if they are the last sub- scripts and the full range of values is desired. As with structures, sdb displays all the values of an array or of the section of an array if trailing subscripts are omitted. It displays only the address of the array itself or of the section specified by the user if subscripts are omitted. A particular instance of a variable on the stack may be referenced by using the form procedure:variable,number. All the variations mentioned in naming variables may be used. number is the occurrence of the specified procedure on the stack, counting the top, or most current, as the first. If no procedure is specified, the procedure currently executing is used by default. It is also possible to specify a variable by its address. All forms of integer constants which are valid in C may be used, so that addresses may be input in decimal, octal, or hexadecimal. Line numbers in the source program are referred to as filename:number or procedure:number. In either case the number is relative to the beginning of the file. If no procedure or filename is given, the current file is used by default. If no number is given, the first line of the named pro- cedure or file is used. Addresses The address in a file associated with a written address is determined by a mapping associated with that file. Each mapping is represented by two triples (b1, e1, f1) and (b2, e2, f2) and the file address corresponding to a written address is calculated as follows: b1<=address<e1 then file address=address+f1-b1 otherwise b2<=address<e2 then file address=address+f2-b2 otherwise, the requested address is not legal. In some cases (for exam- ple, programs with separated text and data space) the two segments for a file may overlap. The initial setting of both mappings is suitable for normal a.out and core files. If either file is not of the kind expected, then, for that file, b1 is set to 0, e1 is set to the maximum file size, and f1 is set to 0; in this way the whole file can be examined with no address transla- tion. In order for sdb to be used on large files, all appropriate values are kept as signed 32-bit integers. Commands The commands for examining data in the program are: t Print a stack trace of the terminated or halted program. T Print the top line of the stack trace. variable/clm Print the value of variable according to length l and format m. A numeric count c indicates that a region of memory, beginning at the address implied by variable, is to be displayed. The length specif- iers are: b one byte h two bytes (half word) l four bytes (long word) Legal values for m are: c character d decimal u unsigned decimal o octal x hexadecimal f 32-bit single precision floating point g 64-bit double precision floating point s Assume variable is a string pointer and print the characters starting at the address pointed to by the variable. a Print characters starting at the variable's address. This for- mat may not be used with register variables. p Pointer to procedure. i Disassemble machine-language instruction with addresses printed numerically and symbolically. I Disassemble machine-language instruction with addresses just printed numerically. Length specifiers are only effective with the c, d, u, o, and x for- mats. Any of the specifiers, c, l, and m, may be omitted. If all are omitted, sdb chooses a length and a format suitable for the variable's type as declared in the program. If m is specified, then this format is used for displaying the variable. A length specifier determines the output length of the value to be displayed, sometimes resulting in truncation. A count specifier c tells sdb to display that many units of memory, beginning at the address of variable. The number of bytes in one such unit of memory is determined by the length specifier l, or if no length is given, by the size associated with the variable. If a count specifier is used for the s or a com- mand, then that many characters are printed. Otherwise successive characters are printed until either a null byte is reached or 128 characters are printed. The last variable may be redisplayed with the command ``./''. The sh(C) metacharacters * and ? may be used within procedure and variable names, providing a limited form of pattern matching. If no procedure name is given, variables local to the current procedure and global variables are matched; if a procedure name is specified, then only variables local to that procedure are matched. To match only global variables, the form :pattern is used. linenumber?lm variable:?lm Print the value at the address from a.out or text space given by linenumber or variable (procedure name), according to the format lm. The default format is i. variable=lm linenumber=lm number=lm Print the address of variable or linenumber, or the value of number, in the format specified by lm. If no format is given, then lx is used. The last variant of this command provides a convenient way to convert between decimal, octal, and hexadecimal. variable!value Set variable to the given value. The value may be a number, a char- acter constant, or a variable. The value must be well defined; expressions which produce more than one value, such as structures, are not allowed. Character constants are denoted 'character. Num- bers are viewed as integers unless a decimal point or exponent is used. In this case, they are treated as having the type double. Registers are viewed as integers. The variable may be an expression which indicates more than one variable, such as an array or struc- ture name. If the address of a variable is given, it is regarded as the address of a variable of type int. C conventions are used in any type conversions necessary to perform the indicated assignment. x Print the machine registers and the current machine-language instruction. X Print the current machine-language instruction. The commands for examining source files are: e [procedure] e [filename] e [directory/] e [directory filename] The first two forms set the current file to the file containing pro- cedure or to filename. The current line is set to the first line in the named procedure or file. Source files are assumed to be in directory (the default is the current working directory). The latter two forms change the value of directory. If no procedure, filename, or directory is given, the current procedure and file names are reported. /regular expression[/] Search forward from the current line for a line containing a string matching regular expression as in ed(C). The trailing / may be omitted. ?regular expression[?] Search backward from the current line for a line containing a string matching regular expression as in ed(C). The trailing ? may be omitted. p Print the current line. z Print the current line followed by the next 9 lines. Set the current line to the last line printed. w Window. Print the 10 lines around the current line. number Set the current line to the given line number. Print the new current line. count[+-] Increment (+) or decrement (-) the current line by count lines. Print the new current line. The commands for controlling the execution of the source program are: [count] r args [count] R Run the program with the given arguments. The r command with no arguments reuses the previous arguments to the program while the R command runs the program with no arguments. An argument beginning with < or > causes redirection for standard input or output, respec- tively. If count is given, it specifies the number of breakpoints to be ignored. linenumber c [count] linenumber C [count] Continue after a breakpoint or interrupt. If count is given, the program will stop when count breakpoints have been encountered. The signal which caused the program to stop is reactivated with the C command and ignored with the c command. If a line number is speci- fied, a temporary breakpoint is placed at the line and execution is continued. The breakpoint is deleted when the command finishes. linenumber g [count] Continue after a breakpoint with execution resumed at the given line. If count is given, it specifies the number of breakpoints to be ignored. s [count] S [count] Single-step the program through count lines. If no count is given, then the program is run for one line. S is equivalent to s except it steps through procedure calls. i I Single-step by one machine-language instruction. The signal which caused the program to stop is reactivated with the I command and ignored with the i command. variable: m [count] address: m [count] Single-step (as with s) until the specified location is modified with a new value. If count is omitted, it is effectively infinity. Variable must be accessible from the current procedure. Since this command is done by software, it can be very slow. [level] v Toggle verbose mode, for use when single-stepping with the S, s, or m commands. If level is omitted, then just the current source file and/or subroutine name is printed when either changes. If level is 1 or greater, each C source line is printed before it is executed; if level is 2 or greater, each assembler statement is also printed. A v turns verbose mode off if it is on for any level. k Kill the program being debugged. procedure(arg1,arg2,...) procedure(arg1,arg2,...)/m Execute the named procedure with the given arguments. Arguments can be integer, character, or string constants or names of variables accessible from the current procedure. The second form causes the value returned by the procedure to be printed according to format m. If no format is given, it defaults to d. This facility is only available if the program was compiled with the -g or -Zi options. [linenumber] b [command;command;...] Set a breakpoint at the given line. If a procedure name without a line number is given (for example, ``proc:''), a breakpoint is placed at the first line in the procedure even if it was not com- piled with the -g or -Zi options. If no linenumber is given, a breakpoint is placed at the current line. If no commands are given, execution stops just before the breakpoint and control is returned to sdb. Otherwise the commands are executed when the breakpoint is encountered and execution continues. Multiple commands are speci- fied by separating them with semicolons. If the k command is speci- fied, control returns to sdb at the breakpoint. B Print a list of the currently active breakpoints. [linenumber] d Delete a breakpoint at the given line. If no linenumber is given, then the breakpoints are deleted interactively. Each breakpoint location is printed and a line is read from standard input. If the line begins with a y or d, then the breakpoint is deleted. D Delete all breakpoints. l Print the last executed line. linenumber a Announce. If linenumber is of the form proc:number, the command effectively does a linenumber b l. If linenumber is of the form proc:, the command effectively does a proc:b T. Miscellaneous commands: ! command The command is interpreted by sh(C). new-line If the previous command printed a source line, then advance the current line by one and print the new current line. If the previous command displayed a memory location, display the next memory loca- tion. end-of-file character Scroll. Print the next 10 lines of instructions, source or data depending on which was printed last. The end-of-file character is usually <Ctrl>-D. < filename Read commands from filename until the end of file is reached, and then continue to accept commands from standard input. When sdb is told to display a variable by a command in such a file, the variable name is displayed along with the value. This command may not be nested; ``<'' may not appear as a command in a file. M Print the address maps. M [?/] [*] b e f Record new values for the address map. The arguments ``?'' and ``/'' specify the text and data maps, respectively. The first seg- ment (b1, e1, f1) is changed unless ``*'' is specified; in which case, the second segment (b2, e2, f2) of the mapping is changed. If fewer than three values are given, the remaining map parameters are left unchanged. " string Print the given string. The C escape sequences of the form \charac- ter are recognized, where character is non-numeric. q Exit the debugger. The following commands also exist and are intended only for debugging the debugger: V Print the version number. Q Print a list of procedures and files being debugged. Y Toggle debug output. Files a.out core Warnings When sdb prints the value of an external variable for which there is no debugging information, a warning is printed before the value. The size is assumed to be int (integer). Data which are stored in text sections are indistinguishable from func- tions. Line number information in optimized functions is unreliable, and some information may be missing. Notes If a procedure is called when the program is not stopped at a breakpoint (such as when a core image is being debugged), all variables are initial- ized before the procedure is started. This makes it impossible to use a procedure which formats data from a core image. See also a.out(FP), cc(CP), core(FP), sh(C), syms(FP) Standards conformance sdb is conformant with: AT&T SVID Issue 2; and X/Open Portability Guide, Issue 3, 1989.