sdb(1) sdb(1)NAME sdb - symbolic debugger SYNOPSIS sdb [-w] [-W] [objfil [corfil [directory]]] DESCRIPTION sdb is a symbolic debugger which can be used with C and For- tran programs. It may be used to examine their object files and core files and to provide a controlled environment for their execution. objfil is normally an executable program file which has been compiled with the -g (debug) flag option; if it has not been compiled with the -g flag option, or if it is not an execut- able file, the symbolic capabilities of sdb are limited, but the file can still be examined and the program debugged. The default for objfil is a.out. corfil is assumed to be a core image file produced after executing objfil; the default for corfil is core. The core file need not be present. A - in place of corfil forces sdb to ignore any core image file. Source files used in constructing objfil must be in directo- ry to be located. It is useful to know that at any time there is a current line and current file. If corfil exists then they are ini- tially set to the line and file containing the source state- ment 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. By default, warnings are provided if the source files used in producing objfil cannot be found, or are newer than objfil. This checking feature and the accompanying warnings may be disabled by the use of the -W flag. Names of variables are written just as they are in C or f77(1). Variables local to a procedure may be accessed us- ing 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.member, 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. f77 common variables may be referenced by using the name of the common block instead of the structure name. Blank common variables may be named by the form .variable. 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 April, 1990 1
sdb(1) sdb(1)used for the structure is that of the last structure refer- enced by sdb. An unqualified structure variable may also be used with various commands. Generally, sdb interprets a structure as a set of variables; thus, it displays the values of all the elements of a structure when it is re- quested to display a structure. An exception to this in- terpretation occurs when displaying variable addresses. An entire structure does have an address, and it is this value sdb displays, not the addresses of individual elements. Elements of a multidimensional array may be referenced as variable[number][number]... or as variable[number,number,...] In place of number, the form number;number may be used to indicate a range of values, * may be used to indicate all legitimate values for that subscript, or subscripts may be omitted entirely if they are the last subscripts 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 multidimensional parameter in an f77 program cannot be displayed as an array, but it is actually a pointer, whose value is the location of the array. The array itself can be accessed symbolically from the calling function. 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 file- name: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 procedure or file is used. 2 April, 1990
sdb(1) sdb(1)While a process is running under sdb all addresses refer to the executing program; otherwise they refer to objfil or corfil. An initial argument of -w permits overwriting loca- tions in objfil. 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). The file address corresponding to a written ad- dress is calculated as follows: b1address<e1 file address=address+f1-b1 otherwise b2address<e2 file address=address+f2-b2, otherwise, the requested address is not legal. In some cases (e.g., for programs with separated I and D 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 ex- pected 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 translation. 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 pro- gram. 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 specifiers are: b one byte h two bytes (half word) l four bytes (long word) April, 1990 3
sdb(1) sdb(1)Legal values for m are: c character d decimal u decimal, unsigned 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 characters starting at the address pointed to by the variable. a Print characters starting at the variable's address. This format may not be used with register variables. p pointer to procedure i Disassemble machine-language instruction with addresses printed numerically and symbolical- ly. I Disassemble machine-language instruction with addresses printed numerically only. The length specifiers are only effective with the for- mats c, d, u, o and x. 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 trunca- tion. A count specifier c tells sdb to display that many units of memory, beginning at the address of vari- able. 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 vari- able. 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(1) 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 speci- fied, only variables local to that procedure are matched. To match only global variables, the form :pattern is used. linenumber?lm 4 April, 1990
sdb(1) sdb(1)variable:?lm Print the value at the address from a.out or I space given by linenumber or variable (procedure name), ac- cording 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 character constant or a variable. The value must be well defined; expressions that produce more than one value, such as structures, are not allowed. Character constants are denoted 'character. Numbers are viewed as integers unless a decimal point or ex- ponent is used. In this case, they are treated as hav- ing the type double. Registers are viewed as integers. The variable may be an expression that indicates more than one variable, such as an array or structure name. If the address of a variable is given, it is regarded as the address of a variable of type int. C conven- tions 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 file-name e directory/ e directory file-name The first two forms set the current file to the file containing procedure or to file-name. 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 name and filename are reported. /regular expression/ Search forward from the current line for a line con- April, 1990 5
sdb(1) sdb(1)taining a string matching regular expression as in ed(1). The trailing / may be elided. ?regular expression? Search backward from the current line for a line con- taining a string matching regular expression as in ed(1). The trailing ? may be elided. 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+ Advance the current line by count lines. Print the new current line. count - Retreat 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 com- mand 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 the 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, it specifies the number of breakpoints to be ig- nored. C continues with the signal that caused the program to stop reactivated and c ignores it. If a linenumber is specified then 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 6 April, 1990
sdb(1) sdb(1)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. I steps with the signal that caused the program to stop reactivated and i ignores it. 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 S, s, or m. If level is omitted, then just the current source file and/or subroutine name is printed when ei- ther 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 pro- cedure. 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. linenumber b commands Set a breakpoint at the given line. If a procedure name without a line number is given (e.g., proc:), a breakpoint is placed at the first line in the procedure even if it was not compiled with the -g flag option. 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 re- turned to sdb. Otherwise the commands are executed April, 1990 7
sdb(1) sdb(1)when the breakpoint is encountered and execution con- tinues. Multiple commands are specified by separating them with semicolons. If k is used as a command to ex- ecute at a breakpoint, control returns to sdb, instead of continuing execution. B Print a list of the currently active breakpoints. linenumber d Delete a breakpoint at the given line. If no linenumber is given, the breakpoints are deleted in- teractively. Each breakpoint location is printed and a line is read from the standard input. If the line be- gins with a y or d, 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 bl. If linenumber is of the form proc:, the command effective- ly does a proc: b T. Miscellaneous commands: !command The command is interpreted by sh(1). newline If the previous command printed a source line, advance the current line by one line and print the new current line. If the previous command displayed a memory loca- tion, display the next memory location. CONTROL-D Scroll. Print the next 10 lines of instructions, source, or data, depending on which was printed last. < filename Read commands from filename until the end of file is reached, 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 ? 8 April, 1990
sdb(1) sdb(1)and / specify the text and data maps, respectively. The first segment, (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 are recognized, where character is a nonnumeric character. 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 /usr/bin/sdb a.out core SEE ALSO adb(1), cc(1), ctrace(1), f77(1), sh(1), a.out(4), core(4). ``sdb Reference'' in A/UX Programming Languages and Tools, Volume 1. WARNINGS Data stored in text sections are indistinguishable from functions. Line number information in optimized functions is unreli- able, and some information may be missing. BUGS 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 initialized before the procedure is start- ed. This makes it impossible to use a procedure which for- mats data from a core image. The default type for printing f77 parameters is incorrect. Their address is printed instead of their value. Tracebacks containing f77 subprograms with multiple entry points may print too many arguments in the wrong order, but their values are correct. April, 1990 9
sdb(1) sdb(1)The range of an f77 array subscript is assumed to be 1 to n, where n is the dimension corresponding to that subscript. This is only significant when the user omits a subscript, or uses * to indicate the full range. There is no problem in general with arrays having subscripts whose lower bounds are not 1. 10 April, 1990