|
|
The description of each debugger variable will include some or all of the following information:
Name: | Name of the debugger variable. |
Used by: | Commands or features affected by this variable. |
Set by: | Actions or events that change the value of the variable. |
User settable: | If yes, may be changed directly with set; otherwise read-only. |
Values: | Range of valid values. |
Object specific: | If yes, a separate version of the variable is maintained for each thread or single-threaded process. If no, there is only one version that affects the entire debugging session. |
Related to: | This variable is inter-connected with the other variables listed. |
Description: | What it means and how it is used. |
Name: | %db_lang |
Used by: | Expression evaluation (print, if, language specific stop expressions) |
Set by: | Event trigger, setting %frame |
User settable: | No |
Values: | Any supported language (currently C, C++, and none) |
Object specific: | Yes |
Related to: | %frame, %lang |
Description: |
Language used for expression evaluation,
if not overridden by the user-specified language in %lang.
%db_lang is set to the source language of the current frame
on an event trigger or when %frame is changed.
%db_lang will default to C if debug cannot
determine the source language (usually when the file was compiled without
-g).
%db_lang is always set automatically by debug and is not user-settable. %lang is user-settable (and is never set by debug) and provides a way for the user to override %db_lang. |
Name: | %dis_mode |
Used by: | dis |
User settable: | Yes |
Values: | source or nosource |
Object specific: | No |
Description: | Controls the output of the dis command if neither -n nor -s is given on the command line. If set to nosource (the default) the output contains only the disassembled machine instructions. If set to source, 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. |
Name: | %eh_object |
User settable: | No |
Object specific: | Yes |
Description: | The object that is thrown and/or caught during exception handling. The value of %eh_object may be displayed with the print command and its type displayed with the whatis command. %eh_object is available only for a C++ program that is between a throw-point and the end of a handler. |
Name: | %file |
Used by: | list |
Set by: | Event trigger, setting %frame |
User settable: | No |
Values: | Any valid source file name, or null |
Object specific: | Yes |
Related to: | %frame |
Description: |
Source file associated with the current frame.
%file is set to the name of the source file associated
with the current frame whenever an event triggers or %frame
is changed.
The first list after %frame is set
will display source from %file if no file name is specified.
If the current source file is from an included file, the value of %file will include the names of both the compilation unit and the included file (e.g., ``"primary_source.c@header.h"''). |
Name: | %follow |
Used by: | create, grab |
User settable: | Yes |
Values: | all, procs, or none |
Object specific: | No |
Description: | Default debugger behavior when a controlled process forks. If all (the initial value) or procs, the debugger will also take control over the child processes of any process that forks. If none, no child processes will be controlled. The default behavior may be overridden by the -f option to the individual create and grab commands. Also, any controlled process may be released from control with the release command. |
Name: | %frame |
Used by: | Expression evaluation, dis, list, regs, symbols |
Set by: | Event trigger, setting %func |
User settable: | Yes |
Values: | Any number within the range of frames in the current object's stack |
Object specific: | Yes |
Related to: | %func, %file, %line, %db_lang, list_file, %list_line, %loc |
Description: | Stack frame that determines the context for symbol lookup, expression evaluation, and source listing. Setting %frame resets all the related debugger variables for a consistent view of the new context. |
Name: | %frame_numbers |
Used by: | stack |
User settable: | Yes |
Values: | up or down |
Object specific: | No |
Description: |
Determines the direction of stack frame numbering.
When set to up,
the stack command numbers stack frames from 0 for the top of the stack
(the most recent frame).
The initial frame is the highest numbered.
If set to down, the most recent frame is the highest numbered
and the initial frame is numbered 0.
When set to down, the stack command must determine the highest numbered frame before displaying any stack frames (since the most recent frame will have the highest number). This can cause the stack command to fail for lack of memory without producing any output for processes that have huge stacks. |
Name: | %func |
Used by: | symbols |
Set by: | Event trigger, setting %frame |
User settable: | Yes |
Values: | Any active function in the current object |
Object specific: | Yes |
Related to: | %frame |
Description: | Name of the function given by %frame. %frame and %func work in tandem; setting %frame sets %func to the name of the function for that stack frame. Setting %func sets %frame (and, indirectly, the other variables related to %frame) to the number of the most recently called (highest numbered) frame for that function. %func cannot be set to a function that is not active (does not have a corresponding frame in the stack). |
Name: | %global_path |
Used by: | list, Event notification |
User settable: | Yes |
Values: | Colon-separated list of directories, or null. |
Object specific: | No |
Related to: | %path |
Description: | Search path for source files used by all programs; the directories listed are searched after the program specific directories listed in %path. %global_path may be set on the command line invoking debug (with the -s option) or interactively. If not set by the user, %global_path defaults to null. |
Name: | %lang |
Used by: | Expression evaluation |
(print, if, language specific stop expressions, etc.) | |
User settable: | Yes |
Values: | Any supported language (currently C or C++) or the null string |
Object specific: | No |
Related to: | %db_lang |
Description: | If set, overrides %db_lang and specifies the language used for expression evaluation. If null (the default) debug uses %db_lang, the source language specified in the object file's debugging information, for expression evaluation. |
Name: | %lastevent |
Set by: | Event commands |
User settable: | No |
Values: | Non-negative integer |
Object specific: | No |
Description: | Number of the last event defined. |
Name: | %line |
Used by: | list |
Set by: | Event trigger, setting %frame |
User settable: | No |
Values: | Any source location (file@line) or null |
Object specific: | Yes |
Related to: | %file, %frame, %list_line |
Description: | Source line being executed in the current frame. The first list after an event trigger or after %frame is reset will display source starting at %line if no location is specified. %line will be null if the function was not compiled with debugging information. |
Name: | %list_file |
Used by: | list |
Set by: | list, Event trigger, setting %frame |
User settable: | Yes |
Values: | Any valid source file name, or null |
Object specific: | Yes |
Related to: | %frame, %file, %list_line |
Description: |
Last file displayed by the list command.
Subsequent lists display source from the same file.
%list_file is set whenever list is executed,
and is also reset to the current file %file whenever
an event triggers or %frame is changed.
If the source file is an included file, the value of %list_file will include the names of both the compilation unit and the included file (e.g., ``"primary_source.c@header.h"''). |
Name: | %list_line |
Used by: | list |
Set by: | list, Event trigger, setting %frame |
User settable: | Yes |
Values: | Any line number or null |
Object specific: | Yes |
Related to: | %list_file, %line, %frame |
Description: | Last source line displayed by the list command. Subsequent lists will continue from %list_line. %list_line is set whenever list is executed, and is also reset to the current line (%line) in the current frame(%frame) whenever an event triggers or %frame is changed. |
Name: | %loc |
Used by: | dis |
Set by: | Event trigger, setting %frame |
User settable: | No |
Values: | Any text address |
Object specific: | Yes |
Related to: | %frame |
Description: | Location counter (address of the current instruction) in the current frame. The first dis after an event trigger or after %frame is reset will start at %loc if no location is specified on the command line. Subsequent dis commands will continue from the location where the last one left off, independent of %loc, until the next event occurs or %frame is changed. |
Name: | %mode |
Used by: | Command line editing facility |
User settable: | Yes |
Values: | emacs, vi, or null |
Object specific: | No |
Description: | Determines the editing mode used. The initial value is derived from the environment variables VISUAL and EDITOR. |
Name: | %num_bytes |
Used by: | dump |
User settable: | Yes |
Values: | Any positive integer |
Object specific: | No |
Description: | Number of bytes for the dump command to display if no count is given on the command line. The initial value is 256. |
Name: | %num_lines |
Used by: | dis, list |
User settable: | Yes |
Values: | Any positive integer |
Object specific: | No |
Description: | Number of lines of disassembly or source to display if no count is given on the command line. The initial value is 10. |
Name: | %path |
Used by: | list, Event notification |
User settable: | Yes |
Values: | Colon-separated list of directories, or null |
Object specific: | Program-specific |
Related to: | %global_path |
Description: | Program-specific search path for finding source files; searched before the directories specified in %global_path. %path defaults to null if not set by the user. |
Name: | %proc |
Used by: | Nearly everything |
Set by: | create, grab, Event trigger |
User settable: | Yes |
Values: | Process identifier of any controlled process |
Related to: | %program, %thread, all object-specific debugger variables (%db_lang, %file, %frame, %func, %line, %list_file, %list_line, %loc, and %path) |
Description: | Current process. Nearly all commands apply only to the current process or current thread (%thread) if the process is multi-threaded (unless specified otherwise with -p). Setting %proc will reset all the process-specific variables. %program will also be reset if the new process is in a different program. If the process is multi-threaded, setting %proc will also reset %thread to a random thread in the new process. |
Name: | %program |
Set by: | create, grab, Event trigger |
User settable: | Yes |
Values: | Any program name displayed by ps |
Related to: | %proc, %thread |
Description: | Current program. Encompasses all processes belonging to that program. Setting %program will also reset %proc and %thread (and indirectly, all object-specific variables) to a random process and thread in the new program. |
Name: | %prompt |
Used by: | Command line interpreter |
User settable: | Yes |
Values: | Any string |
Object specific: | No |
Description: | The string echoed to prompt the user for another command. May be reset to customize the user interface; probably most useful for debugging debug. |
Name: | %redir |
Used by: | create |
User settable: | Yes |
Values: | yes (or 1), no (or 0) |
Object specific: | No |
Description: | Mode for handling I/O in debugger-created processes. If yes, the I/O of newly-created processes will be redirected to a pseudo-terminal. If no (the default value) the debugger does not redirect the processes' I/O. The default behavior may be overridden on individual create commands by the -r and -d options (for redirection and default behavior, respectively). |
Name: | %result |
Set by: | Every command |
User settable: | No |
Values: | Integer |
Object specific: | No |
Description: | Result state of previous command. Zero (0) indicates successful execution; non-zero indicates failure. |
Name: | %thisevent |
Set by: | Event trigger |
User settable: | No |
Values: | Positive integer, in the range of active events |
Object specific: | No |
Description: | Number of the most recent event that triggered. |
Name: | %thread |
Used by: | Nearly everything |
Set by: | create, grab, Event trigger |
User settable: | Yes |
Values: | Thread identifier of the form pinteger.integer |
Related to: | %program, %proc, all object-specific debugger variables (%db_lang, %file, %frame, %func, %line, %list_file, %list_line, %loc, %path, and %proc) |
Description: | Current thread. Nearly all commands apply only to the current thread (unless specified otherwise with -p). Setting %thread will reset all the object-specific variables. %proc (and indirectly, %program) will also be reset if the new thread is in a different process. |
Name: | %thread_change |
User settable: | Yes |
Values: | ignore, announce, stop (default) |
Object specific: | No |
Description: | Controls the debugger behavior when a thread is created, exits, is suspended or continued, gives up its LWP or is picked up by an LWP. If set to stop, the debugger will print a message announcing the state change and will stop the thread. If set to announce, the message will be printed but the thread will not be stopped. If set to ignore, neither the message will be printed nor the thread stopped. |
Name: | %verbose |
Used by: | Event trigger |
User settable: | Yes |
Values: | quiet, source, events, reason, all |
Object specific: | No |
Description: | Level of event notification verbosity. If set to all (the initial value) or reason, the debugger prints out the reason for the stop, the process id, and the next source line whenever the process stops. If set to events, the debugger prints the source line, but prints the reason only if an event caused the process to stop. It does not print the reason for halts and steps. If set to source, only the current source line is displayed. If set to quiet, no output is generated when a process stops. The default behavior may be overridden with the -q option to the commands that create events. |
Name: | %wait |
Used by: | run, step |
User settable: | Yes |
Values: | foreground (or 1, or yes), background (or 0, or no) |
Object specific: | No |
Description: | Default behavior for commands (run and step) that start processes or threads in motion. If foreground (the initial value), the debugger waits for the object to stop before prompting the user for another command. If background, the debugger will prompt the user again immediately, without waiting for the object to stop. The default behavior may be overridden by the -b and -f (background and foreground, respectively) options to the individual run and step commands. |