Linux and UNIX Man Pages

Linux & Unix Commands - Search Man Pages

ladebug(1) [osf1 man page]

ladebug(1)						      General Commands Manual							ladebug(1)

NAME
ladebug - Invokes the Ladebug debugger SYNOPSIS
ladebug [-c file ] [-gui] [-i file ] [-I directory ] [-k] [-line serial_line] [-nosharedobjs] [-pid process_id [executable_file]] [-prompt string] [-remote] [-rp remote_debug_protocol] [-tty terminal_device] [-V] [executable_file [core_file]] DESCRIPTION
The Ladebug debugger is a symbolic source code debugger that debugs programs compiled by the DEC C, ACC, DEC C++, DEC Ada, DEC COBOL, DEC Fortran 90, and DEC Fortran 77 compilers. For full source-level debugging, compile the source code with the compiler option that includes the symbol table information in the compiled executable file. Command-Line Options and Parameters Specifies an initialization command file. The default initialization file is By default, the debugger searches for this file during startup, first in the current directory; if it is not there, the debugger searches your home directory for the file. This file is pro- cessed after the Ladebug debugger has connected to the application being debugged. Activates the Ladebug debugger's graphical user inter- face (GUI) as well as the command-line interface. Specifies a pre-initialization command file. The default pre-initialization file is By default, the debugger searches for this file during startup, first in the current directory; if it is not there, the debugger searches your home directory for the file. This file is processed before the Ladebug debugger has connected to the application being debugged, so that commands such as "set $stoponattach = 1" will have taken effect when the connection is made. Specifies the directory containing the source code for the target program, in a manner parallel to the use command. Use multiple -I options to specify more than one directory. The debugger searches directories in the order in which they were specified on the command line. Enables local kernel debugging. Specifies the serial line for remote kernel debugging. This must be used with -rp kdebug. Prevents the reading of symbol table information for any shared objects loaded when the program executes. Later in the debug session, the user can enter the readsharedobj command to read in the symbol table information for a specified object. Specifies the process ID of the process to be debugged. You may optionally also specify the binary file for that process. This option cannot be used with any remote or kernel debugging flags. Specifies a debugger prompt. The default debugger prompt is "(ladebug) ". If the prompt argument contains spaces or special characters, enclose the argument in quotes (" "). Enables remote kernel debugging; for use with the kdebug kernel debugger. Specifies the remote debug protocol. Currently only kdebug is supported. -rp kdebug enables remote kernel debugging. Specifies the terminal device for remote kernel debugging. This must be used with -rp kdebug. Causes the Ladebug debugger to print its version number and exit without starting a debugging session. Specifies the program executable file. If the file is not in the current directory, specify the full pathname. Specifies the core file. If the core file is not in the current directory, specify the full pathname. Entering Commands At the debugger prompt, you may enter more than one command on the same line by separating each command with a semicolon. Commands are exe- cuted in the same order in which they are entered in the command line. Continue command input to another line by entering a backslash at the end of each line. The maximum command-line length is 100,000 charac- ters. In Ladebug debugger commands, the words thread, in, at, state, if, policy, priority, and with are command language keywords and must be surrounded by parentheses in expressions that use them as variables or type names. Task-related Command Sets The following section lists the Ladebug debugger commands in task-related sets: Starting and stopping programs in the debugger: attach, detach, kill, load, quit, rerun, run, unload For examples, enter help start. Stopping your program at specific locations: delete, disable, enable, status, stop, stopi, when, wheni For examples, enter help breakpoint. Controlling the execution of your program: call, cont, conti, goto, next, nexti, return, step, stepi For examples, enter help execution. Saving the current state of the debuggee process in a snapshot: save snapshot, clone snapshot, delete snapshot, show snapshot For examples, enter help snapshot. Reading and writing memory, variables, and registers: assign, dump, examine_address, print, printf, printregs, trace, tracei, watch For examples, enter help variable, help memory, or help register. Looking at the call stack: down, pop, up, where For examples, enter help stack. Showing the source for the program: /, ?, file, edit, list, unuse, use, map source directory, unmap source directory, show source directory For examples, enter help listing. Examining or changing the current scope under investigation: class, down, file, func, process, thread Manipulating processes: attach, detach, kill, process, show process Manipulating threads and thread-specific objects: show condition, show mutex, show thread, thread Learning specifics about program variables: whatis, whereis, which Manipulating shared objects: delsharedobj, listobj, readsharedobj Controlling signal handling: catch, ignore Changing or understanding your Ladebug environment: alias, set, help, unalias, unset For a complete list of debugger variables, enter help $variable. Changing or showing the current system environment: export, printenv, setenv, sh, unsetenv Logging the results of Ladebug debugger commands and replaying a log: #, playback, record, source Recalling previously-used commands: !, history Debugging UNIX kernels: kps, patch There are also a number of kernel debugging command aliases such as tlist and tstack available. Enter alias for a complete list of command aliases. Command Descriptions startaddress , endaddress / mode startaddress / count mode You can display stored values as character strings, machine instructions, or decimal, octal, hexadecimal, or real numbers. Specify the address and the number of words or bytes (count) information in hexadecimal, octal, or decimal. The display mode must be specified along with the address range. The modes are: b Print a byte in hexadecimal. c Print a byte as a character. d Print a short word in decimal. D Print a long word in decimal. dd Print a 32-bit (4 byte) decimal display. f Print a single-precision real number. g Print a double-precision real number. i Disassemble machine instructions. L Print a long double precision real number o Print a short word in octal. O Print a long word in octal. oo Print a 32-bit (4 byte) octal display. s Print a string of characters (a C-style string that ends in null). u Print a short word in unsigned decimal. U Print a long word in unsigned decimal. uu Print a 32-bit (4 byte) unsigned decimal display. x Print a short word in hexadecimal. X Print a long word in hexadecimal. xx Print a 32-bit (4 byte) hexadecimal display. Note that you must enter a space between "count" and "mode" if the language of the program being debugged is COBOL. # comment When the debugger encounters the # command, it ignores all inputs until the end of the line. The # command must be the first identifier on the command line. (White space can precede this command.) !! or ![-]integer or !text To repeat the last command line, enter two exclamation points or press the Return key. You can also enter !-1. To repeat a command line entered during the current debugging session, enter an exclamation point followed by the integer associated with the command line. (Use the history command to see a list of commands used.) For example, to repeat the seventh command used in the cur- rent debugging session, enter !7. Enter !-3 to repeat the third-to-last command. To repeat the most recent command starting with a string, use the last form of the command. For example, to repeat a command that started with bp, enter !bp. / [string] or ? [string] Use the string search commands / and ? to locate text in the source code. The / character invokes a forward search; the ? character invokes a backwards search. Enter / or ? without an argument to find the next location of the previously specified text. The search begins from the current position of the program counter. If no program counter exists for the current source file, the search begins after the last source line displayed by the debugger. alias [aliasname] alias aliasname [(argument ,...)] "string" unalias aliasname Enter the alias command without an argument to display all aliases and their definitions. Specify an alias name to display the definition for that alias. Use the second form to define a new alias or to redefine an existing alias. The definition can contain the name of another alias, if the nested alias is the first identifier in the definition. For example, you can define a nested alias and invoke the alias as follows: (ladebug) alias begin "stop in main; run" (ladebug) alias pv(x) "begin; print(x)" (ladebug) pv(i) The definition can contain a string in quotation marks, specified with backslashes before the quotation marks, as in the following example: (ladebug) alias x "set $lang="C++"" (ladebug) alias x x set $lang="C++" Invoke the alias by entering the alias name, including any arguments specified in the alias definition. Use the unalias command to delete an alias. Alias commands cannot contain more than 56 arguments. The following predefined aliases are included with the debugger: a assign att attach b stop at bp stop in c cont d delete det detach e file f func g goto h history j status l list li $cursrcpc/10i; set $cursrcpc=$cursrcpc+40 n next ni nexti p print pi playback input plist show process all pr printregs ps printf "%s", q quit r rerun ri record input ro record output s step S next si stepi Si nexti sw switch switch process t where tlist show thread all (show thread when the kernel debugging option is used) ts where thread all tset thread tstack where thread all u list $curline-9:10 w list $curline-5:10 W list $curline - 10:20 wi ($curpc-20)/10i wm watch memory wv watch variable assign target = expression Use the assign command to change the value of a variable, memory address, or expression that is accessible according to the scope and visi- bility rules of the language. The expression can be any expression that is valid in the current context. For C++: assign [classname::]member = ["filename"]`expression assign [object.]member = ["filename"]`expression For C++, use the assign command to modify static and object data members in a class, and variables declared as reference types, type const, or type static. The address referred to by a reference type cannot be changed, but the value at that address can be changed. attach process_id [image_file] Use the attach command to connect to a running process. Supply the process ID number; the image file name is optional. call function ([parameters]) Use the call command to execute a single function. Specify the function as if you were calling it from within the program. If the function has no parameters, specify empty parentheses. You can nest called functions by setting a breakpoint in a function and executing it using the call command. When execution suspends at the breakpoint, use the call command to execute the nested function. For multithreaded applications, the call is made in the context of the current thread. For C++: When you set the $overloadmenu debugger variable to 1 and call an overloaded function, the debugger lists the overloaded functions and calls the function you specify. catch [signal] Enter the catch command without an argument to see which operating system signals the debugger currently traps. Use the catch command fol- lowed by an argument to trap the specified signal. Only one signal at a time can be added to the list of trapped signals. The catch command operates on a per-program basis; you must first load a program (using the load command) or attach to a process (using the attach command). catch unaligned Enter the catch unaligned command to instruct the debugger to stop when unaligned data access occurs in the debuggee process. The debugger stops at the instruction following the instruction where the unaligned access occurs, and issues a message. The default is ignore unaligned. class [classname] For C++ only: Use the class command without an argument to display the current class scope. Specify an argument to change the class scope. Once the class scope is set, refer to members of the class omitting the classname:: prefix. Setting the class scope nullifies the function scope. clone snapshot [integer] Use the clone snapshot command to clone (copy) the snapshot specified by the integer argument. If no integer is specified, the most recently saved existing snapshot is cloned. There are two side-effects to cloning a snapshot. First, the snapshots in the future of the cloned snapshot are deleted. For example, suppose four snapshots are saved from a process. Cloning the second snapshot results in the deletion of the third and fourth snapshots. Second, the current process is killed and replaced by the cloned process. Thus if you enter show process after cloning a snapshot, you will see that the process ID of the current process has changed to that of the cloned process. See also save snapshot, delete snapshot, and show snapshot. Limitations: The state saved in a snapshot doesn't cover I/O and forks. In other words, when you clone a snapshot, the I/O that has been done since the snapshot was saved is not undone; likewise, child processes that have been spawned since the snapshot was saved are not killed. [count] cont [signal] [to-linenumber] [in-function] conti to-address Use the cont command without an argument value to resume program execution until a breakpoint, a signal, an error, or the end of the pro- gram is encountered. Specify the count argument to cause the debugger to automatically repeat the command count times. Specify a signal parameter value to send an operating system signal to the program continuing execution. Specify the linenumber argument to halt program execution when that line number is reached. Specify the in-function argument to halt the program when the named function is reached. Use the conti form of the command to halt program execution when the specified code address is executed. When you use the cont command, the Ladebug debugger resumes execution of the entire process. The signal parameter value can be either a signal number or a string name (for example, SIGSEGV). The default is 0, which allows the pro- gram to continue execution without specifying a signal. If you specify a signal parameter value, the program continues execution with that signal. If both a count and a signal are specified, the signal will only be sent on the first continuation. The linenumber argument is used to resume execution and then halt when the specified source line is reached. The form of the optional linenumber argument must be either linenumber, a positive numeric, which indicates the line number of the current source file where execution is to be halted, or "filename":linenumber, which explicitly identifies both the source file and the line number where execution is to be halted. The function argument is used to continue until the named function is reached. If the function name is overloaded and the user does not resolve the scope of the function in the command line, the debugger prompts the user with the list of overloaded functions bearing that name from which to choose. The form of the optional function argument must be a valid function name. delete integer ,... delete all delete * Enter the delete command followed by the number or numbers associated with a breakpoint, trace, or watch (as listed by the status command) to remove the specified breakpoint, tracepoint, or watchpoint. Enter the delete all command or the delete * command to remove all breakpoints, tracepoints, or watchpoints. This command operates on a per-program basis; you must first load a program (using the load command) or attach to a process (using the attach command). delete snapshot * delete snapshot all delete snapshot [integer ,...] The first two forms of this command delete all the snapshots that have been saved from the current process. The last form deletes the snapshots specified. If no snapshots are specified, the most recently saved existing snapshot is deleted. See also save snapshot, clone snapshot, and show snapshot. delsharedobj shared_object Use the delsharedobj command to remove the symbol table information for the specified shared object from the debugger. detach [process_id ,...] Use the detach command with process IDs to detach from the specified running process or processes. Use the show process all or show process * command to display a list of processes running under debugger control. If you do not specify a process ID, the debugger detaches from the current process. Detaching from a process disables your ability to debug that process. disable integer ,... disable all disable * Enter the disable command followed by the number or numbers associated with a breakpoint, trace, or watch (as listed by the status command) to disable the breakpoint, tracepoint, or watchpoint. Enter the disable all command or the disable * command to disable all breakpoints, tracepoints, or watchpoints. The disabled breakpoint is displayed in response to the status command, but is ignored during execution. Disabled breakpoints remain dis- abled until they are explicitly reactivated or deleted. This command operates on a per-program basis; you must first load a program (using the load command) or attach to a process (using the attach command). down [number] Use the up command or the down command without an argument to change the function scope to the function located one level up or down the stack. Enter a number argument to change the function scope to the function up or down the specified number of levels. If the number of levels exceeds the number of active functions on the stack, the function scope moves up or down as many levels as possible and the debugger issues a warning message. When the function scope changes, the debugger displays the source line corresponding to the last point of execution in that function. dump [function] dump. Use the dump command without an argument to list the parameters and local variables in the current function. To list the parameters and local variables in an active function, specify it as an argument. Enter the dump. command (include the dot) to list the parameters and local variables for all functions active on the stack. edit [filename] Enter the edit command without an argument to edit the current source file. Include the filename argument to edit the specified file. The Ladebug debugger will use the value of the EDITOR environment variable to pick the editor to invoke. The default is vi. enable integer ,... enable all enable * Enter the enable command followed by the number or numbers associated with a breakpoint, trace, or watch (as listed by the status command) to enable a breakpoint, tracepoint, or watchpoint. Enter the enable all command or the enable * command to activate all previously disabled breakpoints, tracepoints, and watchpoints. This command operates on a per-program basis; you must first load a program (using the load command) or attach to a process (using the attach command). export [env_variable [=value]] Sets the value of the specified environment variable. If no variable is specified, the command displays the values of all environment variables. If a variable is specified but no value is specified, the variable is set to NULL. This command is not for the current debuggee's environment, but for the environment of any debuggees created with subsequent run or rerun commands. Note that export and setenv are synonyms. file [filename] Enter the file command without an argument to display the name of the current file scope. Include the filename argument to change the file scope. Change the file scope to set a breakpoint in a function not in the file currently being executed. To see source code for a function not in the file currently being executed, use the file command to set the file scope and the use command to direct the search for the sources of that file. func [function] func [integer] Use the func command without an argument to display the current function scope. To change the function scope to a function currently active on the stack, specify either the name of the function or the number corresponding to the stack activation level. (Enter the where command to display the stack trace.) When the function scope is changed, the debugger displays the source line corresponding to the last point of execution in that function. goto linenumber Use the goto command to branch to a line located in the function where execution is suspended. When you branch to a line, the source code between the line where execution suspended and the specified line is not executed. help [command] [ladebug] Enter the help command without an argument to display a list of debugger help topics. Include a command argument to display a description of that command. Include a ladebug argument to display a task-oriented list of commands. history [integer] Enter the history command without an argument to display previously executed commands. The debugger displays the number of command lines defined for the $historylines debugger variable. (The default is 20 lines of user input.) Include an integer argument to display that num- ber of previous commands. ignore [signal] Enter the ignore command without an argument to see which operating system signals the debugger currently ignores. Use the ignore command followed by an argument to ignore the specified signal. Only one signal at a time can be removed from, the list of ignored signals. The ignore command operates on a per-program basis; you must first load a program (using the load command) or attach to a process (using the attach command). ignore unaligned Enter the ignore unaligned command (the default) to instruct the debugger not to stop when unaligned access occurs. (See also the catch unaligned command.) kill Use the kill command to terminate the current program process and leave the debugger running. When a process terminates, breakpoints and traces previously set are retained. You can later rerun the program. kps Use the kps command to list all system processes. (This command is valid for local kernel debugging only.) list list startline [,endline ] list startline [:count] list function The list command displays source-code lines beginning with the source line corresponding to the position of the program counter, the last line listed if multiple list commands are issued, or the line number specified as the first argument to the list command. Specify the exact range of source-code lines by including either the endline or the number of lines you want to display. The arguments can be expressions that evaluate to integer values. To display the source code for a particular function, enter the function as an argument. listobj Use the listobj command to list all loaded objects, including the main image and the shared libraries. For each object, the information listed consists of the full object name (with pathname), the starting address for the text, the size of the text region, and whether the symbol table information has been read by the debugger. load image_file [core_file] unload process_id ,... unload image_file The load command loads an image file and optionally a core file. After loading an image file, enter the run command to start program exe- cution. The unload command removes all related symbol table information that the debugger associated with the process being debugged, specified by either a process ID or image file. next [expression] Use the next and the step commands to execute a line of source code. When the next line to be executed contains a function call, the next command executes the function being called and returns to the line immediately after the function call. The step command steps into the function and executes only the first line of the function. For multithreaded applications, use these commands to step the current thread while putting all other threads on hold. If the optional expression argument is supplied, the debugger evaluates the expression as a positive integer that specifies the number of times to execute the command. The expression can be any expression that is valid in the current context. nexti [expression] Use the stepi command and the nexti command to execute a machine instruction. When the instruction contains a function call, the stepi com- mand steps into the function being called, and the nexti command executes the function being called. For multithreaded applications, use these commands to step the current thread while putting all other threads on hold. If the optional expression argument is supplied, the debugger evaluates the expression as a positive integer that specifies the number of times to execute the command. The expression can be any expression that is valid in the current context. map source directory directory1 directory2 Use the map source directory command to tell the Ladebug debugger that the source files in directory directory1 is now to be found in directory2. See also show source directory and unmap source directory for displaying and unsetting source directory mapping. patch expression1 = expression2 Use the patch command to correct bad data or instructions in executable disk files. The text, initialized data, or read-only data areas can be patched. The bss segment, as well as stack and register locations, cannot be patched because they do not exist on disk files. Use this command exclusively when you need to change the on-disk binary. Use the assign command when you need only to modify debuggee mem- ory. If the image is executing when you issue the patch command, the corresponding location in the debuggee address space is updated as well. (The debuggee is updated regardless of whether the patch to disk succeeded, as long as the source and destination expressions can be pro- cessed by the assign command.) If the user program is loaded but not yet started, the patch to disk is performed without the corresponding assign to memory. playback input filename Use the source command and the playback input command to execute debugger commands contained within a file. (Note that you can also exe- cute debugger commands when you invoke the debugger by creating an initialization file named .dbxinit. By default, the debugger searches for this file during startup, first in the current directory; if it is not there, the debugger searches your home directory for the file.) Format commands as if they were entered at the debugger prompt. When a command file is executed the value of the $pimode debugger variable determines whether the commands are echoed. If the $pimode vari- able is set to 1, commands are echoed; if $pimode is set to 0 (the default), commands are not echoed. The debugger output resulting from the commands is always echoed. pop [number_of_frames] The pop command removes one or more execution frames from the call stack, terminating the actions of the called functions coresponding to those frames immediately. The optional argument is the number of execution frames to remove from the call stack. If you do not specify the argument, one frame is removed. If specified, the number must be a positive integer less than or equal to the number of frames currently on the call stack. print [expression ,...] print @linenumber The print command displays the current value of a variable or expression that is visible in the current context, as defined by the scope and visibility rules of the program language. The expression can be any expression that is valid in the current context. The print @ command displays the address of the specified line number. For example, print @10 displays the address of line number 10. For C++: print *this print object print [object.]member print *(derived_class*)object For C++, use the print command to display the value of an object, including inherited members and the value of data members in an object. Type casts can be used to interpret a base class object as a derived class object, or to interpret a derived class object as a base class object. To interpret a base class type object as the derived type, use the last form of the print command. Set the $usedynamictypes debugger variable to 1 to display dynamic information; set it to 0 to display static information. The default is dynamic. Use printx, printd or printo to temporarily set the display radix to hex, decimal or octal when printing. printenv [env_variable] Displays the value of the specified environment variable. If none is specified, the command displays the values of all environment vari- ables. This command does not reflect the current debuggee's environment, but the environment of any debuggees which might now be created with run or rerun commands. printf [format [,expression ,...]] Use the printf command to format and display a complex structure. The format argument is a string expression of characters and conversion specifications, using the same format specifiers as the printf C function. printregs Use the printregs command to display the contents of all machine registers for the current thread. Register values are given in both deci- mal and hexadecimal, depending on the value of the $hexints variable. The list of registers displayed by the debugger is machine depen- dent. process [process_id | image_file | debugger_variable] Specify a specific process using the process ID number or the name of the image. The Ladebug debugger sets the current process context to the process ID or the process that runs the binary image. If there is more than one process running the same binary image, the Ladebug debugger warns you and leaves the process context unchanged. The debugger variables $childprocess and $parentprocess can also be specified in place of the process ID. (the Ladebug debugger automatically sets these variables when an application forks a child process.) quit Use the quit command to end the debugging session and return to the operating system prompt. readsharedobj shared_object Use the readsharedobj command to read in the symbol table information for a specified shared object. This object must be a shared library or loadable kernel module. The command can be used only when a debuggee program is specified; that is, either the Ladebug debugger has been invoked with it, or the debuggee program was loaded by the load command. record input [filename] record output [filename] record io [filename] Use the record input command to save all the debugger commands to a file. The commands in the file can be executed using the source command or the playback input command. The record output command saves all debugger output to a file. The output is simultaneously echoed to the screen. (The program output is not saved.) The record io command saves both input to and output from the debugger. To stop recording debugger input or output, enter record input /dev/null or record output /dev/null, respectively. If no file is specifed, the Ladebug debugger will create a file with a random file name in /tmp as the record file. return [function] Use the return command without an argument to continue execution of the current function until it returns to its caller. If you include a function name, execution continues until control is returned to the specified function. The function must be active on the call stack. run [program_arguments] [io_redirection] rerun [program_arguments] [io_redirections] Use the run and rerun commands to start program execution. Enter program flags, options, and input and output redirections as arguments. If the rerun command is specified without arguments, the arguments entered with the previous run command are used. If the last modification time and size of the binary file or any of the shared objects used by the binary file have changed since the last run command was issued, the Ladebug debugger automatically rereads the symbol table information. If this happens, the old breakpoint set- tings may no longer be valid after the new symbol table information is read. Environment variables and (~-names in the program arguments are evaluated in the same manner as in a command shell. save snapshot Use the save snapshot command to save the current state of the debuggee process in a snapshot. By doing this, you can conveniently return to that state at a later time as opposed to re-running the program and re-entering the debugger command sequence that brought you to that state. Conceptually, this feature is similar to the "undo" function in text editors, except that with snapshots you control the granular- ity of each undo. Snapshots are numbered sequentially starting from 1. See also clone snapshot, delete snapshot, and show snapshot. set [variable = definition] unset variable To examine the definitions of all debugger variables, enter the set command without arguments. (Use the print command to display the defi- nition of a single debugger variable.) To define a debugger variable, enter the set command followed by a variable name, an equal sign, and a definition. Enclose string defini- tions in quotes. The definition can be any expression allowed by the language of the program being debugged. Use the unset command to delete a variable. If you want to remove an environment variable, or all environment variables, use the unsetenv command, not the unset command. The debugger contains many predefined variables to describe the current state of the debugger, and to enable you to customize the debugger environment. You can delete and redefine the predefined debugger variables in the same way you define your own variables. If you delete a predefined debugger variable, the debugger uses the default value for that variable. The settings on the predefined variables apply to all debugging processes. The debugger has the following predefined variables: $ascii With the default value of 1, enables the print command to print character-type data as ASCII characters, only when the bit value is that of a printable 7-bit subset ASCII character. (Other bit values are printed as octal numbers.) With a value of 0, all printable ISO Latin-1 characters are printed as characters. $beep With the default value of 1, causes a beep to sound when a user attempts to perform an illegal action while editing the debugger com- mand line (for example, moving the cursor past the end of the line, or "yanking" -- pasting -- from an empty cut buffer). $childprocess Can be specified in place of the process ID. (the Ladebug debugger automatically sets this variable when an application forks a child process.) $catchexecs When set to 1, instructs the debugger to notify the user and stop the program when a program execs. The default is 0. $catchforks When set to 1, instructs the debugger to notify the user when a program forks a child process. The child process stops and is brought under debugger control. (By default, the parent process is not stopped. See the $stopparentonfork description.) The default is 0. $catchforkinfork When set to 1, instructs the debugger to catch a fork as soon as possible during the fork call, rather than waiting until the fork call returns to the user's program. Requires $stopparentonfork or $catchforks to be set to take effect. The default is 0. $curevent Set to the event number of the current event at the start of an event, allowing its use within the expression of an event. $curfile Specifies the current source-code file. $curfilepath Specifies the full path used by the debugger to access the current source-code file. $curline Specifies the current line in the source file. $curpc Specifies the current value of the Program Counter (PC). The $curpc variable is used by the wi alias. $curprocess Specifies the pid of the current process being debugged. $cursrcline Specifies the line number of the last line of source code listed, plus one. $cursrcpc Specifies the current value of the address being listed as machine code. The $curpc variable is used by the li alias. $curthread Indicates the thread ID of the current thread within the current process. You can change to a different thread by setting $curthread. $dbxouputformat When set to 1, the result of the print command is formatted in a manner similar to the one used by dbx. The default is 0. $dbxuse When set to 1, the use command replaces the use list with the new items. When set to 0, the use command appends the new items to the existing list. The default is 1. $decints When set to 1, all integers printed by the debugger are displayed as decimal numbers. The default is 0. $doverbosehelp When set to 1, help messages will be verbose. When set to 0, help messages will be terse. The default is 1. $editline With the default of 1, enables the command-line editing features. For backward compatibility, you can set this variable to 0. $eventecho With the default of 1, echoes events (such as breakpoints) with event numbers when executed. $funcsig With the default of 1, causes display of the function signature when the breakpoint-hit message is printed. When set to 0, causes only the function name to be displayed. The default is 1. $giveladebughints When set to 1, the debugger may give hints to remind the user of possibly useful commands. The default is 1. $hasmeta For international users. When set to 1, causes any 8-bit character to be interpreted as the corresponding 7-bit character plus the Meta character (which is the ALT key whose MSB bit represents a Meta modifier). This could be used for binding editing functions to ALT plus key sequences. The default depends on several factors, including the locale and whether the terminal has Meta capability. In the United States, the default is usually 0. $hexints When set to 1, all integers are displayed as hexadecimal numbers. The default is 0. $historylines Specifies the number of previously input commands listed in response to the history command. The default is 20. $indent With the default of 1, specifies that structures will be printed with added indentation to render them more readable. $lang Specifies the programming language used in the program being debugged. For mixed-language programs, $lang is set to the language cor- responding to the current frame. The variable is updated when the program execution stops. $lasteventmade Set to the event number of the most recently created event at the time of the event's creation, allowing users to record event numbers for use in scripts. $listwindow Specifies how many lines the list command displays. The default is 20. $main Specifies the name of the function that the debugger enters first. The default is main(), but this can be set to any function. This variable is useful when debugging languages whose primary function is called something other than main(). $maxstrlen Specifies the maximum number of characters to print when the value of a string is printed. The default is 128. $octints When set to 1, the debugger prints all integers as octal numbers. The default is 0. $overloadmenu When debugging C++ programs only, if this variable is set to 1, a menu of overloaded functions is displayed so you can select the desired function from the list of type signatures of the function. When set to 0, no menu is displayed, and you must disambiguate overloaded functions by providing the full type signature. The default is 1. $page Controls debugger output pagination. When set, the debugger generated terminal output will be paginated. Default value is 1 (ON) for command-line interface and 0 (OFF) for the GUI. $pagewindow Determines the number of lines per page to be displayed when output pagination is turned on. Default value is 0 which means the debugger dynamically adjusts the page size to the user's window size. $parentprocess Can be specified in place of the process ID in commands that take a process ID as an argument. (The debugger automatically sets this variable when an application forks a child process.) $pid Indicates the process ID of the current process. Only for use in kernel debugging (either local or remote). $pimode Specifies whether the playback input command echoes input. If set to 1, commands from the script file are echoed. If set to 0, com- mands are not echoed. The default is 0. $prompt Specifies the debugger prompt. The default is (ladebug). $repeatmode With the default of 1, causes the debugger to repeat the previous command if you press the Return key at the (ladebug) prompt. $showlineonstartup When set to 1, causes the debugger to show the first line of "main" on startup. When set to 0, causes the line not to be shown. The default is 1. $showwelcomemsg When set to 1, causes the debugger to show the welcome message on startup. When set to 0, causes the welcome message not to be shown. The default is 1. $stackargs With the default of 1, causes the values of arguments to be included in the output of the where, up, down, and dump commands. When large or complex values are passed by value, the output can be voluminous. You can set $stackargs to 0 to suppress the output of argument values. The default is 1. $statusargs With the default of 1, causes the values of arguments to be included in the output of the status command and in the status-line printed by default each time the target stops. When large or complex values are passed by value, the output can be voluminous. You can set $statusargs to 0 to suppress the output of argument values. The default is 1. $stepg0 With the default of 0, causes the debugger to step over calls to routines that are compiled without symbol information. When set to 1, the debugger steps into these calls. $stoponattach When set to 1, causes the debugger to stop a running process right after attaching to it. When set to 0, causes the debugger to allow the process to run to completion; in this case, to interrupt the process, enter Ctrl/C. The default is 0. $stopparentonfork When set to 1, instructs the debugger to stop the parent process when a program forks a child process. (See also the $catchforks description.) The default is 0. $threadlevel Enables the Ladebug debugger to determine whether you are working with DECthreads or native threads. The default is "decthreads" if the application is multithreaded and is using DECthreads. Otherwise, the default is "native". You can switch from one mode to another by setting $threadlevel. In kernel mode, $threadlevel is always "native". $tid Indicates the thread ID of the current thread within the current process. You can change to a different thread by setting $tid. Only for use in kernel debugging (either local or remote). $usedynamictypes With the default of 1, instructs the debugger to display dynamic type information. When set to 0, static type information is dis- played. Output of the print, trace, tracei, and whatis commands is affected. $verbose When set to 1, specifies whether debugger output should include all possible program information, including base pointers and virtual function pointers (for C++ programs only). The default is 0. setenv [env_variable [value]] Sets the value of the specified environment variable. If no variable is specified, the command displays values of all the environment variables. If a variable is specified but no value is specified, the variable is set to NULL. This command does not change the environment of the current debuggee. It is used to set the environment for any debuggees subsequently created with run or rerun commands. Note that export and setenv are synonyms. sh command Use the sh command to execute a Bourne shell command. Do not enclose the shell command and its arguments in quotations. For example: (ladebug) sh ls -l sample.c show condition [condition_identifier_list] show condition [condition_identifier_list] with state == wait For DECthreads only: Use the show condition command to list information about currently available DECthreads condition variables. If you supply one or more condition identifiers, the debugger displays information about the condition variables that you specify, provided that the list matches the identity of currently available condition variables. If you omit the condition variable specification, the debugger displays information about all the condition variables currently available. Use the show condition with state == wait command to display information only for condition variables that have one or more threads wait- ing. If $verbose is set to 1, the sequence numbers of the threads waiting on the condition variables are displayed. show mutex [mutex_identifier_list] show mutex [mutex_identifier_list] with state == locked For DECthreads only: Use the show mutex command to list information about currently available mutexes. If you specify one or more mutex identifiers, the debugger displays information about only those mutexes you specified, provided that the list matches the identity of cur- rently available mutexes. If you omit the mutex identifier specification, the debugger displays information about all mutexes currently available. Use the show mutex with state == locked command to display information exclusively for locked mutexes. If $verbose is set to 1, the sequence numbers of the threads locking the mutexes are displayed. show process show process * show process all Use the show process command to display information for the current process. The second and third forms of the command display information for all processes. show snapshot * show snapshot all show snapshot [integer [, integer]* ] The first two forms of the show snapshot * command display all the snapshots that have been saved from the current process. The last form displays the snapshots specified. If no snapshots are specified, the most recently saved existing snapshot is displayed. See also save snapshot, clone snapshot, and delete snapshot. show source directory [directory] show all source directory [directory] Use the show source directory command to display the source directory mapping information of directory and its child directories. If directory is not specified, the Ladebug debugger displays the mapping information of all the source directories whose parent is not a source directory. The command show all source directory is identical to show source directory except that the mapping information of all the descendants of directory is displayed. See also map source directory and unmap source directory for setting and unsetting source directory mapping. show thread [thread_identifier_list] show thread [thread_identifier_list] with state == ready show thread thread_identifier_list] with state == blocked show thread [thread_identifier_list] with state == running show thread [thread_identifier_list] with state == terminated show thread [thread_identifier_list] with state == detached show thread [thread_identifier_list] with state == stopped Use the show thread command to list all the threads known to the debugger. If you specify one or more thread identifiers, the debugger displays information about the threads you specify, if the thread matches what you specified in the list. If you omit a thread specifica- tion, the debugger displays information for all threads. Use the show thread command to list threads that have specific characteristics, such as threads that are currently blocked. To display lists of thread characteristics, use one of the alternate syntaxes listed. The valid state values for DECthreads are ready, blocked, running, terminated, and detached. The valid state values for native threads are stopped, running, and terminated. source filename Use the source command and the playback input command to execute debugger commands contained within a file. (Note that you can also exe- cute debugger commands when you invoke the debugger by creating an initialization file named .dbxinit. By default, the debugger searches for this file during startup, first in the current directory; if it is not there, the debugger searches your home directory for the file.) Format commands as if they were entered at the debugger prompt. When a command file is executed, the value of the $pimode debugger variable determines whether the commands are echoed. If the $pimode variable is set to 1, commands are echoed; if $pimode is set to 0 (the default), commands are not echoed. The debugger output resulting from the commands is always echoed. status The status command lists all breakpoints, tracepoints, and watchpoints, the reference number associated with each, and whether they are disabled. All settings are on a per-process basis. step [expression] Use the next and the step commands to execute a line of source code. When the next line to be executed contains a function call, the next command executes the function being called and returns to the line immediately after the function call. The step command executes only the first line of the function. For multithreaded applications, use these commands to step the current thread while putting all other threads on hold. If the optional expression argument is supplied, the debugger evaluates the expression as a positive integer that specifies the number of times to execute the command. The expression can be any expression that is valid in the current context. stepi [expression] Use the stepi command and the nexti command to execute a machine instruction. When the instruction contains a function call, the stepi com- mand steps into the function being called, and the nexti command executes the function being called. For multithreaded applications, use these commands to step the current thread while putting all other threads on hold. If the optional expression argument is supplied, the debugger evaluates the expression as a positive integer that specifies the number of times to execute the command. The expression can be any expression that is valid in the current context. stop [quiet] detector [thread thread_identifier_list] [if expression] [{command[;...]}] Enter the stop command to create a breakpoints which suspends the debuggee and executes the commands in the command list argument (if given) when the specified detector is triggered and both thread and if conditions (if given) evaluate to true. If quiet is specified, the Ladebug debugger will suppress the status reporting message when the breakpoint is hit. detector can be one of the following: o at line_number This detector is triggered on execution of the line. o in function This detector is triggered on calls to the function. o in all function This detector is triggered on calls to all the functions named function. o pc address This detector is triggered when PC == address. o watched_memory [access] [within function] This detector is triggered on the specified access on the region of memory specified by watched_memory. If within function is given, the detector is triggered only when the access occurs in the specified function. watched_memory can be one of the following: * variable lvalue This form specifies the variable lvalue. * memory start_address This form specifies the 8-byte memory at start_address. * memory start_address, end_address This form specifies the memory region from start_address to end_address (inclusively). * memory start_address:size This form specifies the memory region of size-bytes starting from start_address. access can be one of the following: * write * read * changed This mode detects writes that change the contents of the memory. * any This mode detects both read and write. If no access argument is specified, write is assumed. o signal signal ,... This detector is triggered on reception of any of the signals specified. o unaligned This detector is triggered on unaligned access. o every proc entry This detector is triggered on every procedure call. o every instruction This detector is triggered on every program counter change. o expression If expression is a function name, then this detector is the same as in expression. Otherwise, it is the same as at expression. For example, stop 57 if ($i == 10) { print var; set $i = 0; } creates a reflex which, when the execution is at line 57 of the current file and $i is equal to 10, stops the debuggee, prints the content of the variable var and sets $i to zero, Note: For C++ the following forms of function name are acceptable in addition to the usual simple identifiers. [class::]class_or_function[(type_signature)] object . function object_pointer_expression -> function To set a breakpoint in a specific version of an overloaded function, either set $overloadmenu to 1, and enter the command stop in function, and choose the appropriate function from the menu, or specify the function and the type signature as arguments to the command. If the overloaded function has no parameters, void may be explicitly specified. stopi variable stopi [variable] if expression stopi [variable] at address [if expression] Enter the stopi command with a variable to suspend execution when the variable value changes. Specify if with an expression to suspend execution when the expression evaluates to true. When you specify both a variable and an expres- sion, execution suspends only if the specified expression evaluates to true and the variable has changed. To suspend execution when an address is encountered, use the third syntax form. If you specify a variable, execution suspends only if the variable has changed when the address is encountered. If you specify an expression, execution suspends only if the expression evaluates to true when the address is encountered. If you specify both a variable and an expression, execution suspends only if the variable has changed and the expression evaluates to true when the address is encountered. The stopi command is different from the stop command because the debugger checks the breakpoint set with the stopi command after executing each machine instruction. Thus, debugger performance is affected when you use the stopi command. thread [thread_identifier] Use the thread command to identify or set the current thread context. If you supply a thread identifier, the debugger sets the current context to the thread you specify. If you omit the thread identification, the debugger displays the current thread context. The debugger interprets the thread identifier as a DECthreads or kernel thread identifier, depending on the value of the debugger variable $threadlevel. trace [variable] [if expression] trace [variable] at linenumber [if expression] trace [variable] in function [if expression] trace [variable] [thread thread_identifier_list] [at linenumber] [if expression] trace [variable] [thread thread_identifier_list] [in function] [if expression] When you use the trace command without an argument, the debugger prints a message, but does not suspend program execution when each func- tion is entered. Specify a variable to print a message when the variable value changes. Specify if with an expression to print a message when an expression evaluates to true. When you specify both a variable and an expression, a message is printed only if the expression eval- uates to true and the variable has changed. To print a message when a line or function is encountered, use the second or third syntax form. If you specify a variable, a message is printed only if the variable has changed when the line or function is encountered. If you specify an expression, a message is printed only if the expression evaluates to true when the line or function is encountered. If you specify both a variable and an expression, a message is printed only if the variable has changed and the expression evaluates to true when the line or function is encountered. The following example traces the variable f when the program is executing the function main: (ladebug) trace f in main Use the trace thread command to set tracepoints in specific threads. If you list one or more thread identifiers, the debugger sets a tra- cepoint only in those threads you specify. If you omit the thread identifier specification, the debugger sets a tracepoint in all the threads of the application. For C++: Use the $usedynamictypes variable to control whether the debugger displays static (value = 0) or dynamic(value = 1) information. The default is dynamic. tracei [variable] [if expression] tracei [variable] at address [if expression] tracei [variable] in function [if expression] tracei [variable] [thread thread_identifier_list] [at linenumber] [if expression] tracei [variable] [thread thread_identifier_list] [in function] [if expression] When you use the tracei command, the debugger prints a message, but does not suspend program execution. Specify a variable to print a mes- sage when the variable value changes. Specify an expression to print a message when an expression evaluates to true. When you specify both a variable and an expression, a message is printed only if the expression evaluates to true and the variable has changed. To print a message when an address or function is encountered, use the second or third syntax form. If you specify a variable, a message is printed only if the variable has changed when the address or function is encountered. If you specify an expression, a message is printed only if the expression evaluates to true when the address or function is encountered. If you specify both a variable and an expression, a message is printed only if the variable has changed and the expression evaluates to true when the address or function is encountered. The tracei command differs from the trace command in that the debugger evaluates the tracepoint set with the tracei command after the debugger executes each machine instruction. Thus, when you use the tracei command, debugger performance is affected. In the following example, a breakpoint is set to print a message every time the function factorial is entered: (ladebug) tracei factorial Use the tracei thread command to set tracepoints in specific threads. If you list one or more thread identifiers, the debugger sets a tra- cepoint only in those threads you specify. If you omit the thread identifier specification, the debugger sets a tracepoint in all threads of the application. For C++: Use the $usedynamictypes variable to control whether the debugger displays static (value = 0) or dynamic (value = 1) information. The default is dynamic. unsetenv [env_variable] Removes the specified environment variable. If no variable is specified, all environment variables are removed. This command has no effect on the environment of the current debuggee. It changes the environment of any debuggees subsequently created with run or rerun commands. up [number] Use the up command or the down command without an argument to change the function scope to the function located one level up or down the stack. Enter a number argument to change the function scope to the function up or down the specified number of levels. If the number of levels exceeds the number of active functions on the stack, the debugger issues a warning message. When the function scope changes, the debugger displays the source line corresponding to the last point of execution in that function. unmap source directory [directory] Enter the unmap source directory command removes the mapping of directory if there was one. See also map source directory and show source directory for setting and displaying source directory mapping. use [directory ,...] unuse [directory ,...] unuse * Enter the use command without an argument to list the directories the debugger searches for source-code files. Specify a directory argu- ment to make source-code files in that directory available to the debugger. (You can also use the ladebug command -I option to specify search directories.) The debugger control variable $dbxuse effects the semantics of this command. Enter the unuse command without an argument to set the search list to the default, the home directory, the current directory, and the directory containing the executable file. Include the name of a directory to remove it from the search list. The asterisk (*) argument removes all directories from the search list. watch memory start-address [, end_address | :size_expression] [any | changed | read | write] [thread id_list] [in function] [if expression] [{command[;...]}] watch variable variable [any | changed | read | write] [thread id_list] [in function] [if expression] [{command[;...]}] The watch command suspends program execution, prints the watchpoint event, prints the instruction that accessed the watched memory, dis- plays old and new values, and prints the first line of source code that will be executed when program execution continues. Write accesses are detected by default. Use the watch memory command to indicate the address or address range to be watched. Addresses can be given in any base. If neither the optional end_address nor size_expression arguments are specified, the debugger defaults to a data size of 8 bytes. The size_expression argument can be any expression that is valid in the current context and language. Use the watch variable command to indicate the variable to be watched. A variable can be located in global memory, on a stack, or in a register. Local variables are defined only within a function scope. Setting watchpoints on local variables is valid only when they are in scope. The variable must be a variable name or other expression which can be used as a target of an assignment in the current language. To detect accesses other than default write access, use the any, changed, or read options. The any option detects any access. The changed option detects any change in the value of the contents of the watched memory. The read option detects only read access. Use the thread id_list option to suspend execution when access occurs in a certain thread. Use the in function option to suspend execution when access occurs in a certain function. Use the if expression option to suspend execution at a point at which the expression is true. Use the command option to specify command to execute when a watchpoint suspends execution. Commands must be enclosed in braces. Separate multiple commands with semicolons. whatis expression The whatis command prints the type of the specified expression. The expression can be any expression that follows the syntax, scope, and visibility rules of the program language. For C++: whatis classname whatis [classname::]member whatis [classname::]function whatis classname::classname The first syntax form of the whatis command displays the class type. The second syntax form displays the type of a member function or data member. To display all versions of an overloaded function, use the third syntax form. To use this command as a constructor only, use the last syntax form. Use the $usedynamictypes variable to control whether the debugger displays static (value = 0) or dynamic (value = 1) information. The default is dynamic. when [quiet] detector [thread thread_identifier_list] [if expression] [command[;...]] Enter the when command to create a breakpoint which executes the commands in th ecommand list (if any) when the detector is triggered and both thread and if conditions (if given) evaluate to true. The difference between stop and when is that a breakpoint created using stop suspends the execution when hit whereas one created using when does not. See also the description for stop for details on how to create a breakpoint. wheni {command[;...]} wheni if expression {command[;...]} wheni at linenumber [if expression] {command[;...]} wheni in function [if expression] {command[;...]} wheni [thread thread_identifier_list] [at linenumber] [if expression] {command[;...]} wheni [thread thread_identifier_list] [in function] [if expression] {command[;...]} Use the wheni command to execute the specified command. (The wheni command does not suspend program execution.) The debugger command must be enclosed in braces. Separate multiple commands with semicolons. To execute a command when an expression evaluates to true, use the second syntax form. To execute a command when an address or function is encountered, use the third or fourth syntax form. If you specify an expression, the command is executed only if the expression evaluates to true when the address or function is encountered. The wheni command differs from the when command in that the debugger evaluates the tracepoint set with the wheni command after each machine instruction is executed. Thus, using the wheni command affects performance. For example, the following command stops program execution, lists ten lines of source code, and displays the stack trace when the value of the variable i is equal to 3 in the function main: (ladebug) wheni in main if i == 3 {wi;where} Use the wheni thread command to set tracepoints in specific threads. If you list one or more thread identifiers, the debugger sets a tra- cepoint only in those threads you specify. If you omit the thread identifier specification, the debugger sets a tracepoint in all the threads of the application. where [number] where [number] thread [thread_identifier_list] where [number] thread all where [number] thread * The where command displays the stack trace of currently active functions for the current thread. The second form of the command displays the stack traces of the specified threads. The third form and the fourth form of the command are equivalent; they display the stack traces of all threads. Include the optional number argument to list that number of levels at the top of the stack. (Each active function is designated by a number that can be used as an argument to the func command. The top level on the stack is 0; if you enter the command where 3, you will see lev- els of 0, 1, and 2.) If you do not specify the number argument, you will see all levels. whereis expression The whereis command shows all declarations of the expression. Each declaration is fully qualified with scope information. which expression The which command shows the fully qualified scope information for the instance of the specified expression in the current scope. If avail- able to the debugger, the name of the source file containing the function in which the expression is declared, the name of the function, and the name of the expression are included. The syntax of the output is "filename"`function`variable. RESTRICTIONS
The maximum command-line length is 100,000 characters. Alias commands cannot contain more than 56 arguments. FILES
Default object file name. Default core dump file name. Initialization file. By default, the debugger searches for this file at startup, first in the current directory; if it is not there, the debugger searches your home directory. Pre-initialization file. By default, the debugger searches for this file at startup, first in the current directory; if it is not there, the debugger searches your home directory. RELATED INFORMATION
ada(1), c89(1), cc(1), cxx(1), cobol(1), dbx(1), f77(1), f90(1), printf(1), signal(3). Ladebug Debugger Manual. Ladebug Web Page at http://www.unix.digital.com/ladebug/ Ladebug Debugger Manual as web pages at file:/usr/doc/ladebug/ladebug_debugger_manual.html Ladebug Debugger Advanced Topics as web pages at file:/usr/doc/ladebug/ladebug_debug- ger_advanced_topics.html delim off ladebug(1)

Featured Tech Videos