NAME

sdb - symbolic debugger

SYNOPSIS

sdb  [-e]  [-s  signo]  [-V]  [-W]  [-w]  [objfile  [corfile
[directory-list]]]

DESCRIPTION

sdb is the symbolic debugger for C and assembly programs. sdb may be used to examine executable program files and core files. It may also be used to examine live processes in a controlled execution environment.

The objfile argument is the name of an executable program file. To take full advantage of the symbolic capabilities of sdb, this file should be compiled with the -g (debug) option. If it has not been compiled with the -g option, the symbolic capabilities of sdb will be limited, but the file can still be examined and the program debugged. objfile may also be a path name in the /proc directory, in which case the currently executing process denoted by that path name is controlled by sdb.

The corfile argument is the name of a core image file. A core image file is produced by the abnormal termination of objfile or by the use of gcore. A core image file contains a copy of the segments of a program. The default for corfile is core. A core image file need not be present to use sdb. Using a hyphen (-) instead of corfile forces sdb to ignore an existing core image file.

The directory-list argument is a colon-separated list of directories that is used by sdb to locate source files used to build objfile. If no directory list is specified, sdb will look in the current directory.

The following options are recognized by sdb:

-e Ignore symbolic information and treat nonsymbolic addresses as file offsets.

-s signo

Where signo is a decimal number that corresponds to a signal number [see signal(2)], do not stop live processes under control of sdb that receive the signal. This option may be used more than once on the sdb command line.

-V Print version information. If no objfile argument is specified on the command line, sdb will exit after printing the version information.

-W   Suppress  warnings  about  corfile  being  older   than
     objfile  or  about  source  files  that  are older than
     objfile.

-w   Allow user to write to objfile or corfile.

sdb recognizes a current line and a current file. When sdb is examining an executable program file without a core file, the current line and current file are initially set to the line and file containing the first line of main. If corfile exists, then current line and current file are initially set to the line and file containing the source statement where the process terminated. The current line and current file change automatically as a live process executes. They may also be changed with the source file examination commands.

Names of variables are written as in C. 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.

Structure members may be referred to as variable.member, pointers to structure members as variable->member, and array elements as variable[number]. Pointers may also be dereferenced by using the form pointer[number]. Combinations of these forms may also be used. The form number->member may be used where number is the address of a pointer, and number.member where number is interpreted as the address of a structure instance. The template of the structure type used in this case will be the last structure type referenced. When sdb displays the value of a structure, it does so by displaying the value of all elements of the structure. The address of a structure is displayed by displaying the address of the structure instance rather than the addresses of individual elements.

Elements of a multidimensional array may be referred to 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. If no subscripts are specified, sdb will display the value of all elements of the array.

A particular instance of a variable on the stack is referred to as procedure:variable,number. The number is the occurrence of the specified procedure on the stack, with the topmost occurrence being 1. The default procedure is the one containing the current line.

Addresses may be used in sdb commands as well. Addresses are specified by decimal, octal, or hexadecimal numbers.

Line numbers in the source program are specified by the form filename:number or procedure:number. In either case, the number is relative to the beginning of the file and corresponds to the line number used by text editors or the output of pr. A number used by itself implies a line in the current file.

While a live process is running under sdb, all addresses and identifiers refer to the live process. When sdb is not examining a live process, the addresses and identifiers refer to objfile or corfile.

Commands

The commands for examining data in the program are:

t Prints a stack trace of the terminated or halted program. The function invoked most recently is at the top of the stack. For C programs, the stack ends with _start, which is the startup routine that invokes main.

T Prints the top line of the stack trace.

variable/clm

Print the value of variable according to length l and format m. The 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)

Legal values for m are:

c character

d signed decimal

u unsigned decimal

o octal

x hexadecimal

f 32-bit single precision floating point

g 64-bit double precision floating point

s Assumes that variable is a string pointer and prints characters starting at the address pointed to by the variable.

a Prints characters starting at the variable's address. Do not use this with register variables.

p pointer to procedure

i Disassembles machine-language instruction with addresses printed numerically and symbolically.

I Disassembles machine-language instruction with addresses printed numerically only.

Length specifiers are effective with formats c, d, u, o, x. The length specifier determines the output length of the value to be displayed. This value may be truncated. The count specifier c displays that many units of memory, starting at the address of the variable. The number of bytes in the unit of memory is determined by l or by the size associated with the variable. If the specifiers c, l, and m are omitted, sdb uses defaults. If a count specifier is used with the s or a command, 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.

For a limited form of pattern matching, use the sh metacharacters * and ? within procedure and variable names. (sdb does not accept these metacharacters in file names, as the function name in a line number when setting a breakpoint, in the function call command, or as the argument to the e command.) If no procedure name is supplied, sdb matches both local and global variables. If the procedure name is specified, then sdb matches only local variables. To match global variables only, use :pattern. To print all variables, use *:*.

linenumber?lm
variable:?lm
     Prints the value at the address from the executable  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
     Prints the address of variable or  linenumber,  or  the
     value of number. l specifies length and m specifies the
     format.  If no format is specified, then  sdb  uses  lx
     (four-byte  hex).   m  allows  you  to  convert between
     decimal, octal, and hexadecimal.

variable!value

Sets variable to the given value. The value may be a number, a character constant, or a variable. The value must be well-defined; structures are allowed only if assigning to another structure variable of the same type. Character constants are denoted 'character. Numbers are viewed as integers unless a decimal point or exponent is used. In this case, they are treated as having the type double. Registers, except the floating point registers, are viewed as integers. Register names are identical to those used by the assembler (for example, %regname where regname is the name of a register). 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 Prints the machine registers and the current machine-language instruction.

X Prints the current machine-language instruction.

The commands for examining source files are:

e
e procedure
e filename
e directory/
     e, without arguments, prints the name  of  the  current
     file.   The  second  form  sets the current file to the
     file containing the procedure. The third form sets  the
     current  file  to filename.  The current line is set to
     the first line in the named procedure or file.   Source
     files  are  assumed  to  be  in  the directories in the
     directory list.  The fourth form adds directory to  the
     end of the directory list.

/regular expression/

Searches forward from the current line for a line containing a string matching regular expression, as in ed. The trailing / may be omitted, except when associated with a breakpoint.

?regular expression?

Searches backward from the current line for a line containing a string matching regular expression, as in ed. The trailing ? may be omitted, except when associated with a breakpoint.

p Prints the current line.

z Prints the current line and the following nine lines. Sets the current line to the last line printed.

w Prints the 10 lines (the window) around the current line.

number

Specifies the current line. Prints the new current line.

count+

Advances the current line by count lines. Prints the new current line.

count-

Resets the current line by count lines back. Prints the new current line.

are:

     The commands for controlling the execution of the source  program

     count r args
     count R
          Runs the program with the given arguments.  The r  com-
          mand with no arguments reuses the previous arguments to
          the program. The R command runs  the  program  with  no
          arguments.  An argument beginning with < or > redirects
          the standard input or output,  respectively.   Full  sh
          syntax  is  accepted.   If count is given, it specifies
          the number of breakpoints to be ignored.

     linenumber c count
     linenumber C count
          Continues execution.   sdb  stops  when  it  encounters
          count breakpoints.  The signal that stopped the program
          is reactivated with the C command and ignored with  the
          c  command.  If a line number is specified, then a tem-
          porary breakpoint is placed at the line  and  execution
          continues.   The breakpoint is deleted when the command
          finishes.

     linenumber g count

Continues with execution resumed at the given line. If count is given, it specifies the number of breakpoints to be ignored.

s count
S count
     s single steps the program through count lines or if no
     count is given,  then the program runs for one line.  s
     will step from one function into a called function.   S
     also  steps  a  program,  but  it  will not step into a
     called function. It steps over the function called.

i count
I count
     Single steps by  count  machine-language  instructions.
     The  signal  that  caused  the program to stop is reac-
     tivated with the I command and ignored with the i  com-
     mand.

variable$m count
address:m count
     Single steps (as with s) until the  specified  location
     is  modified with a new value.  If count is omitted, it
     is, in effect, infinity.  Variable must  be  accessible
     from  the  current procedure.  This command can be very
     slow.

level v

Toggles verbose mode. This is for use when single stepping with S, s, or m. If level is omitted, then just the current source file and/or function name is printed when either changes. If level is 1 or greater, each C source line is printed before it executes. If level is 2 or greater, each assembler statement is also printed. A v turns verbose mode off.

k    Kills the program being debugged.

procedure(arg1,arg2,...)
procedure(arg1,arg2,...)/m
     Executes the named procedure with the given  arguments.
     Arguments can be register names, 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.

linenumber b commands

Sets 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 option. If no linenumber is given, a breakpoint is placed at the current line. If no commands are given, execution stops at the breakpoint and control is returned to sdb. Otherwise the commands are executed when the breakpoint is encountered. Multiple commands are specified by separating them with semicolons. Nested associated commands are not permitted; setting breakpoints within the associated environments is permitted.

B    Prints a list of the currently active breakpoints.

linenumber d

Deletes 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 the standard input. If the line begins with a y or d, then the breakpoint is deleted.

D    Deletes all breakpoints.

l    Prints the last executed line.

linenumber a

Announces a line number. If linenumber is of the form proc:number, the command effectively does a linenumber:b l;c. If linenumber is of the form proc:, the command effectively does a proc:b T;c.

Miscellaneous commands:

#rest-of-line

The rest-of-line represents comments that are ignored by sdb.

!command

The command is interpreted by sh.

new-line

If the previous command printed a source line, then advance the current line by one line and print the new current line. If the previous command displayed a memory location, then display the next memory location. If the previous command disassembled an instruction, then disassemble the next instruction.

end-of-file character

     Scrolls the next 10 lines of instructions,  source,  or
     data  depending on which was printed last.  The end-of-
     file character is usually control-d.

< filename

Read commands from filename until the end of file is reached, and then continue to accept commands from standard input. Commands are echoed, preceded by two asterisks, just before being executed. This command may not be nested; < may not appear as a command in a file.

M    Prints the address maps.

" string "

Prints the given string. The C escape sequences of the form \character, \octaldigits, or \xhexdigits are recognized, where character is a nonnumeric character. The trailing quote may be omitted.

q    Exits the debugger.

V    Prints version stamping information.

SEE ALSO

cc(1), signal(2), a.out(4), core(4), syms(4).
ed(1), gcore(1), sh(1) in the User's Reference Manual.
The ``sdb'' chapter in the Programmer's Guide:  ANSI  C  and
Programming Support Tools.

NOTES

If objfile is a dynamically linked executable, variables, function names, and so on that are defined in shared objects may not be referenced until the shared object in which the variable, etc., is defined is attached to the process. For shared objects attached at startup (e.g., libc.so.1, the default C library), this implies that such variables may not be accessed until main is called.

The objfile argument is accessed directly for debugging information while the process is created via the PATH variable.