debug [opts][[-f none|procs|all][-r][-l start_loc] cmd_line]debug [opts][-f none|procs|all][-l object_file] live_object ...
debug [opts] -c core_file object_file
opts: [-V][-i c|x][-X opt][-d defaults][-s path][-Yitem,dir]
To take full advantage of the symbolic capabilities of debug, the programs examined and controlled by debug should be compiled with the -g option to the compiler [see cc(1)]. If the controlled program has not been compiled with -g, the capabilities of debug will be limited, but the program can still be controlled and examined.
debug provides both a command line interface and an X Windows based graphical user interface. Only the command line interface is described here.
If no cmd_line is specified, debug simply enters interactive mode.
In the second form of invocation, the user specifies one or more existing processes by giving a list of live_objects: either pathnames (entries in the /proc directory) or process ids. In either case, the debugger attempts to control the specified objects as live processes and, if successful, suspends their execution.
Finally, the user may specify an executable program in one of the object file formats understood by debug, along with a core_file. debug interprets the core_file as a record of the process state at the time of the death of the process associated with the object_file and lets the user examine the contents of the process stack, registers and data segments.
debug associates the name of each object (program name) with all processes derived from the current invocation of that object. This name may be used in any command that accepts a process list. If the object name matches the name of an already existing debugger-controlled program, the debugger will create a new name for the program. The default program name may be reset using the rename command (see below).
Several commands separated by semi-colons (``;'') may be given on a single line. A backslash (\) at the end of a line indicates that the command is continued on the following line. The output of a command may be redirected to a file or shell pipeline using the sh syntax of >, >> and |. (For example, symbols -g | pg). As in the shell, > and >> may appear anywhere within a command, but | must appear at the end of a debugger command, since the rest of the line is treated as a shell command that will receive the output of the debugger command. A sequence of debugger commands may be enclosed in curly braces ({}), forming a command block. The output of such a block may be redirected as a whole. A debugger comment is introduced by a pound sign (#). Any characters following a pound sign on a line will be ignored.
Many debugger commands have built-in aliases. These are one or two character names that may be used wherever the full command is used. The user can redefine any of the built-in aliases, or may define his or her own aliases. An alias can consist of any valid debugger command sequence and may take parameters. See alias under ``Commands'' for more details.
On-line help is available for all debugger commands and on many other topics, as well. See help for details.
User-defined variables are polymorphic, having either string or numeric values, according to the type of the last value assigned to them. Any variable, string or numeric, may be used where a string value is required, and any string-valued variable which is convertible to an integer via the strtol(3C) function may be used where a numeric value is required.
debug also supports the ksh fc command, which allows command history searching, editing, listing and rerunning.
Each process may consist of a single thread of control, or of multiple threads of control, all sharing a common address space. The threads abstraction is implemented by a set of library interfaces (see, for example, thr_create(3thread)). These interfaces are, in turn, built on top of an operating system abstraction known as light-weight processes, or LWPs.
debug provides control over both single and multiprocess applications and over both single and multithreaded processes. For each active process under its control, debug detects when the object program and shared library association changes and maintains current knowledge of the associations. In particular, processes may attach or detach shared objects into/from their address spaces using the interfaces dlopen(3C), dlclose(3C), dlsym(3C).
debug provides control of an arbitrary number of threads within a given process. These threads may be bound threads or multiplexed threads (see thr_create). The only restriction is that the user may not start (run or step) a multiplexed thread that is not currently running on an LWP. Note that debug provides control of multithreaded applications only via the library threads abstraction. It does not provide direct access to LWPs.
By default, debug detects when a new process is created by one of its controlled threads or processes and includes the new object in its set of controlled objects. The user can release such newly created objects from debugger control by using the release command (see below). The default behavior may be overridden by individual create or grab commands, or may be changed by setting the value of the built-in variable %follow. Legal values are:
debug assigns a unique identifier to each process and thread under its control. Process identifiers are in the form pid (p1, p2, p3, ...). Thread identifiers are in the form pid.id (p1.1, p1.2, p2.5, ...). debug maintains a record of the current process in the built-in variable %proc. The current thread is maintained in the built-in variable %thread. For all debugger commands that accept an optional list of threads and processes, the default action, if no such list is given, is to apply the command to the current thread (or the current process, if it is single-threaded).
When debug begins execution, the current process is set to the first process specified on the command line, whether a live process or one the debugger creates. The current thread is set to the first thread, for a process created by the debugger, and to an arbitrary thread for a grabbed process. The user may change the debugger's notion of the current thread or process by changing the contents of %thread or %proc with the set command.
When the user enters a command that sets a controlled object in motion, debug, by default, waits for that object to stop before returning control to the user. If the debugger built-in variable %wait is set to 0 or no, or background, the debugger does not wait for the affected object to stop. The default behavior may be re-asserted by setting %wait to 1 or yes, or foreground. This global behavior may be overridden by each command that sets a process in motion.
When the user creates a debugger-controlled object, debug does not, by default, attempt to intercept the input or output for the generated processes. Subject process output is unlabeled, and the subject competes with the debugger for the terminal input. If the debugger variable %redir is set to 1 or yes, the process or thread I/O is redirected to a pseudo-terminal. All output from that process or thread is labeled with an indication of which pseudo-terminal has been written. Subsequent input to the process or thread must be made through the input command (see below). The default behavior may be re-asserted by setting %redir to 0 or no. This global behavior may be overridden by an individual create command.
debug does not attempt to redirect the I/O of grabbed processes, or of the child processes of some created subject, since it cannot tell what those processes may have already done to redirect their own I/O. Note, too, that all of the processes and threads that result from a single create command read and write from/to the same pseudo-terminal.
The command language represents process lists as comma-separated lists of process names. A process name is defined as either:
These variables are reset whenever the thread or process that owns them stops for any reason. %frame may be explicitly set by the user to any active frame and changes the value of the other context variables accordingly. %func may be explicitly set to any function with a currently active frame and results in setting %frame to the most recent instance of that function. %db_lang, %file, %line, and %loc are read-only. If no debugging or symbolic information is available for the current function, %db_lang, %func, %file, %list_file, %line, and %list_line, may be null.
Certain commands allow the user to specify the quiet verbosity level, with a -q option, overriding the global %verbose setting.
Event triggers may apply to a given thread or process or to a set of threads and processes. The event fires if any of the specified objects encounter the trigger. Commands that create events apply, by default, to the current program, rather than the current thread.
With each event, the user may specify an optional debugger command block. This block is executed whenever the event triggers. Events and their associated commands can be deleted, or temporarily deactivated and then reactivated.
For each user-specified event, debug assigns a unique identifier in a common name space. This identifier may be used in the commands that delete, enable, disable and list events. The last event identifier assigned is maintained in the special variable %lastevent, which is updated automatically by the debugger. When an event triggers, debug executes the commands associated with the event, after setting the special variables %program, %proc, %thread, %file, %line, %func, %frame, %loc, %db_lang to indicate the context in which the event occurred, and %thisevent to the event number of the triggered event. These variables are set only for the execution of the commands associated with the triggering event. They revert to their previous values (or are updated to reflect the new debugger state) when those commands complete.
The default action for each event is to announce the occurrence of the event and display the current source line (or current instruction, if no line number information or source is available).
When a controlled process dies, debug remembers the events created for that process. If a new process is created for the same program, all events that applied to the entire program (the default) are re-instantiated for the new process. Events that were created to apply only to a single process within a multiprocess program or to a single thread, are not recreated. Similarly, when a process creates a new child process via fork(2), all events that apply to the entire program from which the parent process is derived are copied in the child process. Events that apply to the parent process only or to a single thread are not copied.
When a new thread is created within a process, all events that applied to the entire process or the entire program are copied in the sibling thread. Events that applied only to the original thread that created the new thread are not copied.
debug accepts expressions containing any combination of program variables or functions, qualified names, built-in debugger variables, and user-defined debugger variables. A qualified name specifies a program identifier that may not be visible in the current context. The syntax is:
[[thread id]@][[source file]@][[function]@][[line number]@]identifier or [[thread id]@][[source file]@][[header file]@]identifier or [[thread id]@]frame number@identifier or [[thread id]@]object name@[[source file]@][[header file]@]identifier
The qualified name is evaluated left to right, and may be disambiguated by supplying @'s as needed. frame number and function must refer to functions that are currently active. thread id may refer to a thread or single-threaded process. object name refers to any object (executable file or shared library) making up the process. header file may be used to find a static function or object defined in a header file. If header file is specified without specifying source file and the debugger cannot find the header within the current file, it will ask if the search should continue through all the compilation units making up the program. The search will stop when the first instance of header file is found.
Expressions beginning with a dash (-) or containing character sequences with special meanings to debug must be enclosed in parentheses, square brackets or curly braces. The special character sequences are: >, >>, |, ||, &&, #, `,', ;, newline.
debug evaluates C expressions using ANSI C semantics rather than
the pre-ANSI C (or transition mode) semantics.
The main effect is on type promotions involving unsigned
types,
where
ANSI C semantics are value preserving rather than unsigned preserving.
The debugger's behavior may differ from the behavior of programs compiled
with cc -Xt (for transition mode).
debug accepts and prints names as they appear in the C++ source, not as they appear in the object file.
The print and set commands have a verbose option (-v) that prints the function prototype for any functions the debugger calls in evaluating the expression. This is useful for understanding what's happening in expressions using overloaded functions or operators. The -v option to print will also display compiler-generated structure and class members, such as pointers to virtual function tables.
If given a pointer to a base class object with virtual functions, and if debug can determine that the type of the object pointed to is a class derived from the base class, the whatis command will display both the base class and the derived class. The print command will also display the object in terms of the derived type.
When printing the contents of a structure or class, the print command will display static class members, with the notation that they are static. Note that symbols -v does not display static members.
Breakpoints (stop events) may be set on:
A stop event may also be created on a specific object and member function combination, using the syntax:
stop pointer->function stop object.function
debug will stop the process or thread upon entering the function only if the ``this'' pointer matches the specified object. If the function is a virtual function, debug will set the breakpoint on the appropriate overriding function.
Events may also be created to take action when an exception of a specific type is thrown or caught. While an exception is in effect, the debugger variable %eh_object represents the thrown object. The print and whatis commands may be used to examine the value and type of the thrown object. If an exception is thrown while an expression is being evaluated, the debugger will abort the expression evaluation. Any side effects of the expression, such as objects created on the stack, will be left in an indeterminate state. Note that %eh.object will not be available in a multi-threaded core image or in a multi-threaded live process that was grabbed rather than created by debug.
[thread id@][object@]address[±constant] # includes debugger and user variables [thread id@][object@][source file@][header file@]func_name[±constant] [thread id@][object@][source file@][header file@]line_number
If the shell escape operator is given twice, with no arguments, that is, !!, debug re-executes the last shell escape specified.
Alias definitions may contain the special identifiers $1, $2, . . . Each such special identifier $n in an alias definition is replaced by the nth argument in an alias invocation, where the arguments are numbered beginning at 1. Each argument must be preceded by whitespace and is terminated by whitespace, a newline, the comment character (#) or the beginning of a block ({). The special identifiers $1, $2, . . . will not be replaced within a quoted string.
If an alias definition contains the special identifier $#, it will be replaced during invocation of the alias with the number of arguments actually used during the current alias invocation. If an alias definition contains the special identifier $*, it will be replaced during invocation of the alias with a list of all arguments passed during the current alias invocation, each separated from the next by a single space.
Aliases may be defined in terms of other aliases, but not recursively. At least 20 levels of nested alias definitions are supported.
If the name given is the same as any existing built-in command, a warning will be generated. Aliases take precedence over built-in commands.
The list of threads and processes to which the event is applied may be changed with the -p option.
The -q option specifies that debug will not announce the occurrence of the event. -v specifies that the event occurrence will be announced.
The -e and -x options work as in the syscall command, and specify whether the system call will be trapped on entry, exit or both entry and exit.
The -c option specifies the number of times the event must occur before it triggers. The -c option is valid only for stop and syscall events.
Alternate expressions, signals, system calls, exception type and/or an alternate command block, may be specified. For exception events, whether the event occurs on throws, catches or both may be specified.
The resulting event will have the same event number as event_num . Note that the change command does not allow the type of event: onstop, stop, signal syscall or exception, to be changed. Further note that the command list must be in the form of a block (that is, with enclosing braces) to distinguish it from a stop expression, system call, signal name or exception type.
debug creates a new controlled process for each command specified in cmd_line , taking care of any necessary redirections of input and output. The processes are set up to stop at the location specified by start_loc. If no start_loc is supplied, the processes are set up to start at the symbol main, if it exists, otherwise at the starting address specified by the object file. debug then exec's each command, passing each the specified arguments.
If no cmd_line is specified to create, debug re-executes the last create command issued, (first killing all processes created as a result of the last create command, if they still exist) in effect, re-running the last process (or processes) created with the same set of arguments.
If the -r option is specified, debug redirects the I/O of the resulting subjects to a pseudo-terminal, as described above. If the -d option is given no redirection is attempted. If neither -r nor -d is specified, the default is determined by the value of the debugger variable %redir.
debug resets its notion of the current program to the first executable specified on the cmd_line . The current process is reset to the process generated from that executable. The current thread is set to the first thread in that process, if the program uses the threads interfaces.
The -f option may be used to specify whether the debugger should take control of child processes, and overrides the default behavior of the debugger. The arguments to the -f option have the same meanings as do the legal values for the %follow built-in variable (see ``Process control'').
debug associates the name of each object (program name) with all processes derived from the current invocation of that object. This name may be used in any command that accepts a process list. If the command name matches the name of an already existing debugger-controlled program, debug creates a new name for the program. The default program name may be reset with the rename command (see below).
In the second form, all debugger events for the current thread or process (or all events associated with the optional proc_list ) are deleted. If an event_command (exception, onstop, stop, signal or syscall) is given, only events of the type specified are deleted.
If a location is given, dis begins disassembling at that address. If no location has been specified, and the context for the specified process or thread has not changed since the last dis invocation on that object, dis begins with the address following the last instruction displayed for that object. Otherwise, dis begins its display with the current location, as specified by the debugger variable %loc, which is reset whenever the context for the specified process or thread changes.
If an end_location is given, disassembly ends at the given location in each specified process. If -c and end_location are both supplied, then the closest value to location has precedence. end_location is ignored if it is a value before location.
If more than one thread or process is specified by the proc_list argument, the disassembly request is performed for each thread or process in turn.
The output of dis normally contains only the disassembled machine instructions. (This is also the behavior asserted by the -n option). If the -s option is specified, the debugger will also attempt to display the source line corresponding to the disassembled instructions. The source line will be displayed only if there is debugging information for the range of addresses being disassembled and if the debugger can find the corresponding source file. If neither the -n nor the -s options are specified, the output mode is governed by the value of the %dis_mode variable.
In the second form, all debugger events for the current thread or process (or all events associated with the optional proc_list) are disabled. If an event_command is given, only events of the type specified are disabled.
dump normally tries to organize its output into words, of a size appropriate for the target architecture. For little-endian architectures, this means that the hexadecimal values for each byte will appear in a different order than the values actually appear in memory. The -b option to dump suppresses this word organization. When -b is specified, dump will output each byte individually, as it is laid out in memory.
In the second form, all disabled debugger events for the current thread or process (or all events associated with the optional proc_list ) are enabled. If an event_command is given, only events of the type specified are enabled.
If a proc_list is specified, those events associated with the list of threads or processes are printed. If a list of event numbers is given, a more detailed record of the specified events is printed, including the full set of associated commands.
The exception command has two forms. When the -d option is given, the command sets up the default exception event behavior for the entire debugger. Each process created or grabbed by the debugger inherits this default exception event behavior. When the debugger starts up, the default action for all exceptions is set so that the debugger stops on each throw-point or exception handler as described above. The -i option with either throw or catch (or both) specifies that the debugger will ignore (not stop for or announce) exceptions that are thrown or caught, respectively. Issuing the command again without the -i option re-establishes the default action. If neither throw nor catch is given, exception -d displays the current default behavior.
Without the -d option, the exception command applies to the current program, or to the list of threads and processes given by the proc_list. Using exception in this way allows you to change the exception action for a given process without changing the default actions inherited by other processes.
Note that exception -d does not affect the default exception event behavior of any process already under the debugger's control.
The exception command without the -d option may also be used to specify debugger behavior when an exception of a particular type is thrown or caught. This form of the exception command establishes an event that may be deleted or enabled, as can stop, onstop, syscall, and signal events. The event action overrides the default behavior and stops the process or thread. Multiple events may be assigned for the same type. Deleting all events for a given exception type re-establishes the default debugger action for that exception type.
The actions for an event will apply to any thrown or caught assignment-compatible object, as specified by the C++ language definition. This includes derived classes and const-or-volatile qualified objects. The type given may be any valid C++ type, or an ellipsis (...) which matches any type.
The -q option specifies that the exception event will not be announced.
With no arguments, the exception command lists the exception event actions for the list of processes given by proc_list, or for the current program.
If first is not specified, the default is the previous command for editing and the previous 16 commands for listing. The -r option reverses the order of the commands; the -n option suppresses command numbers when listing.
In the second form, the command is re-executed after the substitution old=new is performed. If command is not supplied, the default is the previous command.
debug, by default, loads symbolic information for the process from the object file from which the process was created. The -l option specifies an alternate object_file from which to load symbolic information. If -l is used, only one live_object may be specified. This option is useful when debugging long running applications that have no symbol information.
The -f option may be used to specify whether the debugger should take control of child processes, and overrides the default behavior of the debugger. The arguments to the -f option have the same meanings as do the legal values for the %follow built-in variable (see ``Process control'')
In the second form of grab, the user specifies an executable program in one of the object file formats understood by the debugger. debug interprets the core_file as a kernel-created record of the process state at the time of the death of the process associated with the object_file and lets the user examine the contents of the process stack, registers and data segments.
debug associates the name of each object with all processes derived from the current invocation of that object. This name may be used in any command that accepts a process list. If the command name matches the name of an already existing debugger-controlled program, debug creates a new name for the program. The default program name may be reset using the rename command (see below).
expr can be any valid expression in the current language (see
The expression is evaluated, and if it evaluates to ``true'' in the semantics of the current language, the cmd associated with the if clause is executed. Otherwise, if there is an else clause, the cmd associated with it is executed.
The if construct is more likely to be used in commands associated with events, or in scripts, than to be typed interactively as a top-level command.
The first argument may be either the name of a single program or process (as specified in a process list), or the name of a pseudo-terminal, as used by debug to label process output. If a proc_name is specified, debug finds the pseudo-terminal (if any) associated with that program. If neither a program nor a pseudo-terminal is specified, debug attempts to find a pseudo-terminal associated with the current program.
debug sends the input string to the specified pseudo-terminal, after appending a new-line. If the -n option is given, no new-line is appended.
It is an error if the specified proc_name has no associated pseudo-terminal.
If no signal is specified, the default is SIGKILL. signal may be either a valid signal number (as defined in <sys/signal.h>) or a symbolic name, formed from the manifest constant name listed in <sys/signal.h>, with or without the SIG prefix. Case is ignored.
If no count argument is given, the list command displays %num_lines source lines. %num_lines starts out at 10 and may be reset by the user. If a count is given, list displays count lines, instead.
The starting place for the listing may be specified in several ways. If a regular expression is given, the current file is searched for the next occurrence of a line which matches the given reg_exp , beginning from the line immediately following the current line (preceding, if the reg_exp is surrounded by question marks). If a match is found, and no count is given, only the line containing the match is listed. If a count is given, the line containing the match begins the display. ed(1) syntax is used for regular expressions.
A function name as an argument causes the list command to begin its display at the first line of the named function. The function may be specified as in the location syntax: a name, the debugger built-in variable %func, or a qualified name ([source file@][header file@]func_name). A line number may be specified as in the location syntax: a single decimal constant, the debugger built-in variables %line or %list_line, or a qualified name ([source file@][header file@]line). List may be used to display the source of a header file, but header file must be specified in terms of a primary source file that includes it. If only one file name is given, the debugger looks first for a primary source file with that name, then for a header file within the current compilation unit. If neither is found, debug will ask if the search should continue through all the compilation units until it finds one that includes that header file.
If no starting location is specified, the list command begins the display with %list_file@%list_line. %list_file is set to the current file (%file) and %list_line is set to the current line (%line) whenever the current context changes. In addition, %list_line is set to the last line displayed each time list is invoked. Thus, if the current context has not changed and no starting location is specified, list begins with the last line displayed in the previous list invocation.
If no filename is given, the last filename used in a logon command is assumed, and new debugger commands and output are appended to that file.
Note that since all threads within a process share a common address space, the virtual memory map will be identical for each thread within a process.
cmd is a debugger command block. The commands are executed whenever the specified list of processes stops for any reason.
The -f option allows specification of a list of format expressions to be used when printing values. The fmt is a string enclosed in quotation marks ("") and may contain a subset of the format expressions accepted by printf [see fprintf(3S)]. A format expression may have the following form:
%[flags][width][.[precision]][conversion] specifier
The flags, width, precision, and conversion fields
have the same meanings as in the printf routine, with the exception
that positional parameters are not accepted. The specifier may be one of
the following
characters
(specifiers marked with an asterisk (*)
may not be available on all systems):
Any character in the fmt that is not part of a format expression is printed as given. The default format for a particular expression is determined by the expression evaluator for the current language. The expression evaluators will attempt to present information formatted in a way that is meaningful for the given language. For example, for C, a pointer to a character would be printed as a character string, a reference to an array variable would print all members of that array and dereferencing a pointer to a structure would print each member of that structure. Each expr may be any valid expression in the current language (see ``Expressions'').
Each expression in the list is converted to its printable representation, a newline is added, and the result displayed. This process is repeated for each object named in the proc_list . If a fmt is given, no terminating newline is printed unless specified in the fmt . The -v option specifies verbose mode. The debugger prints the function prototype of any function that was called as a result of evaluating the given expressions. This is particularly useful in evaluating C++ expressions to see how overloaded functions or operators are resolved. The -v option will also display compiler-generated structure and class members, such as pointers to virtual function tables.
If a user wishes to leave a grabbed process suspended, perhaps to be grabbed at a later time from a different invocation of the debugger, he or she should use the release command with the -s option before quitting.
Processes released in the halted state may be grabbed by the debugger in a different debug session.
release can be used on core images as well as live processes. The debugger deletes the core image and associated object file from the list of objects that can be examined.
The -f and -b options allow the global behavior set by the %wait debugger variable to be overridden. -f specifies foreground execution for the threads or processes. -b specifies background execution.
The -r option causes debug to continue execution of the given object until each returns from its current stack frame, that is, until the return address of the current function is reached (or until some other event causes execution to halt).
The -u option specifies that debug continues execution of the specified objects until the address specified by location is reached (or until some other event causes execution to halt).
A multiplexed thread that is not currently running on an LWP cannot be set running.
Scripts may nest; the debugger implementation does not place a limit on the number of nested scripts (although external limits, such as the number of open files supported by stdio, may apply).
While any valid language expression may be given, the typical use of the set command is to evaluate assignment expressions. The -v option specifies verbose mode. The debugger prints the function prototype of any function that was called as a result of evaluating the given expressions. This is particularly useful in evaluating C++ expressions to see how overloaded functions or operators are resolved.
In the second form of the command, set is used to change the value of a debugger built-in variable name or user-defined variable name. Debugger built-in variables may have special semantics associated with them, such as %path, which requires a string value having a particular structure, or %frame, which denotes a frame number and must be within the range of currently active frame numbers. Setting a built-in variable such as %frame, may cause the values of other built-in variables to change as well (for example, %line or %func). There is also an implied string concatenation operator. Any pair of string-valued expressions which appear separated by commas will be concatenated into a single string-valued expression before the assignment is performed.
The debug_or_user_var and expr are both evaluated in the context of the current thread or single-threaded process, unless one or more other threads or processes have been specified in the proc_list argument. If more than one thread or process is specified, the set command is evaluated in the context of each of the specified objects, in turn.
The signal command has two forms. When the -d option is given, the command sets up the default signal behavior for the entire debugger. Each process created or grabbed by the debugger inherits this default signal behavior. When the debugger starts up, the default action for all signals is set so that the debugger intercepts each signal as described above. The -i option with one or more signal names or numbers (see kill) specifies that the debugger will ignore those signals (not intercept them). A signal name may be given with or without the initial SIG prefix. Case is not significant. Specifying the signal again without the -i option re-establishes the default action for that signal. If no signal names are given, signal -d displays the current default signal settings for the debugger.
Without the -d option, the signal command applies to the current program, or to the list of threads and processes given by the proc_list. Using signal in this way allows you to change the signal action for a given process without changing the default actions inherited by other processes.
Note that signal -d does not affect the signal state of any process already under the debugger's control.
The signal command without the -d option may also be used to specify a list of commands to be executed when a signal is posted to a given process. The signal will be intercepted, even if the current setting for that signal is to ignore it.
If a command is given with a set of signals, the debugger establishes an event for that set. This event may be deleted, or enabled, as can stop, onstop, syscall or exception events. Multiple events may be assigned for the same signal. Deleting all events for a given signal re-establishes the current debugger action for that signal. That is, if a signal was being ingored for a given process, it will again be ignored once all events for that signal are deleted. If a signal was being intercepted, it will continue to be intercepted, even though all events relating to that signal have been deleted.
The -q option specifies that the signal event will not be announced.
With no arguments, the signal command lists the signal actions for the list of processes given by proc_list, or for the current program.
By default, frames are numbered from 0 for the top of the stack (most recent frame). Setting the debugger variable %frame_numbers to down causes the most recent frame to be the highest numbered, and the remaining frames to be numbered down to 0, for the initial frame. Setting %frame_numbers to up restores the default behavior.
The address and stack arguments may be used to specify beginning values for the program counter and/or stack pointer, respectively. This can be useful when attempting to print a stack trace for a process that has jumped to an illegal address or whose stack pointer has been corrupted. Both the address and stack arguments must be hexadecimal numbers.
The default is stepping at the source statement level. debug continues execution until the object reaches the next source statement as defined by the compiler-generated debugging information. If a count is specified, the debugger repeats the step command count times, or until execution is interrupted by some other event. An explicit count of zero is interpreted to mean ``step forever.''
The -o option specifies stepping over function calls. When the debugger encounters a subroutine call while stepping with the -o option, it will set a temporary breakpoint at the return point of the call and run at ``full speed'' until the temporary breakpoint is reached. Stepping over function calls is available with both the instruction and source level stepping.
The -f and -b options allow the global behavior set by the %wait debugger variable to be overridden. -f specifies foreground execution for the threads or processes. -b specifies background execution.
The -q option specifies quiet stepping: the debugger does not announce the step action nor the new source line.
A multiplexed thread that is not currently running on an LWP cannot be stepped.
A stop_expr consists of one or more stop events , joined by the special debugger conjunction (&&) or disjunction (||) operators. These operators are left-associative, and debug does not guarantee the order in which their operands are evaluated. A stop event can take one of three forms:
location * lvalue (expr)
Each type of stop event has some action that will cause the event to be noticed by the debugger. When such an action occurs, the entire stop_expr is evaluated for ``truth''. If true, the event triggers in the normal way (debug informs the user of the event and executes any associated commands).
A location is an address in the process's text where debug can set a breakpoint. When the thread or process reaches the specified location debug notices the event. For location stop events that refer to function names, the expression is true as long as that function is active. For location stop events that apply to a particular address or line number, the expression is true only when the thread or process is at that address or line.
lvalue may be any expression in the current language that would be valid on the left-hand side of an assignment statement in that language. The debugger notices this event when the contents of the location change. The change itself makes this kind of stop event true.
expr can be any valid expression in the current language. The debugger notices the stop event when any of the identifiers involved in the expression changes value. The entire expression is then evaluated in the context of the current language.
stop events are evaluated continuously while the thread or process is executing. The debugger is free to choose whatever means it has available to achieve this effect. This may include hardware support or may involve continuous single stepping of the object.
The optional count specifies the number of times the stop_expr must evaluate to true before the event triggers. After count times, the event triggers each time the stop_expr evaluates to true.
The -q option specifies that debug will not announce the occurrence of the event.
The stop command with no stop_expr arguments prints the list of user-specified stop expressions including the event identifier and current status (active or disabled).
The -g option displays only the names of global variables which are visible from the current location. This includes only those symbols defined within the current object (executable program or shared library). The -o option, in conjunction with -g, displays the names of global variables in the named object.
The -f option displays only the names of variables which are local to the current file ( %file) and are visible from the current location (%loc). If the -n option is used, the symbols local to filename are displayed instead.
The -d option displays the debugger built-in variables. The -u option displays the debugger-maintained, user-defined variables.
If a pattern is given, the display is further restricted to symbols which match the pattern. sh(1) syntax is used.
If the -v option is specified, the value of each symbol is displayed, along with its name. The -t option displays the type of the variable.
If more than one thread or process is specified by the proc_list argument, the symbols request is performed in the context of each object in turn.
Each call may be given as either a system call entry number, or as the name used in the C language interface to the call. The -e option specifies system call entry, and is the default. The -x option specifies system call exit. Both may be given on a single invocation of the syscall command. For each call listed, the debugger arranges for the specified objects to stop on entry to or exit from that call, or on both entry and exit. The resulting set of actions is then assigned a unique event identifier.
The optional count specifies the number of times the call must occur before the event triggers. After count times, the event triggers each time the call occurs.
The -q option specifies that debug will not announce the occurrence of the system call.
If no proc_list is given, the type of expr is evaluated in the context of the current thread or process. Otherwise, it is evaluated for each object specified by the proc_list, in turn.
If a variable is a structure or class type, whatis variable will display the name of the structure or class. whatis structure_tag_name or whatis type_name will display all known information about that type, including structure members or enumeration constants.
If given an unadorned identifier, whatis will print all objects, functions, or types with that name that are visible from the current scope, along with information about where they are defined.
If %db_lang is set to C++ and the expression given is a pointer to a base class object with virtual functions, if the debugger can determine that the type of the object pointed to is a class derived from the base class, whatis will print the names of both the base and derived classes.
expr can be any valid expression in the current language (see
The expression is evaluated, and if it evaluates to ``true'' in the semantics of the current language, the cmd is executed. The expression is then re-evaluated.
Unlike if, the while construct is often useful as a top-level command.
If debug cannot create or execute processes for any of the commands specified in cmd_line, it acts as if the entire cmd_line request had failed. In particular, any processes that had been created as part of the same cmd_line request are killed.
On the other hand, if debug cannot gain control of one or more of the live_objects specified in the second form of invocation, it continues to attempt to control the other objects specified.
If debug is invoked with the -i x option and cannot start the X Window based interface, it prints a diagnostic message and exits with a non-zero exit status.