Debugger variable description

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.