Section 13.2. MDB Command Syntax
13.2. MDB Command SyntaxThe MDB debugger lets us interact with the target program and the memory image of the target. The syntax is an enhanced form of that used with debuggers like adb, in which basic form is expressed as value and a command. [value] [,count ] command The language syntax is designed around the concept of computing the value of an expression (typically a memory address in the target), and applying a command to that expression. A command in MDB can be of several forms. It can be a macro file, a metacharacter, or a dcmd pipeline. A simple command is a metacharacter or dcmd followed by a sequence of zero or more blank-separated words. The words are typically passed as arguments. Each command returns an exit status that indicates it succeeded, failed, or was invoked with invalid arguments. For example, if we wanted to display the contents of the word at address fec4b8d0, we could use the / metacharacter with the word X as a format specifier, and optionally a count specifying the number of iterations. > fec4b8d0 /X lotsfree: lotsfree: f5e > fec4b8d0,4 /X lotsfree: lotsfree: f5e 7af 3d7 28 MDB retains the notion of dot (.) as the current address or value, retained from the last successful command. A command with no supplied expression uses the value of dot for its argument. > /X lotsfree: lotsfree: f5e > . /X lotsfree: lotsfree: f5e A pipeline is a sequence of one or more simple commands separated by |. Unlike the shell, dcmds in MDB pipelines are not executed as separate processes. After the pipeline has been parsed, each dcmd is invoked in order from left to right. The full definition of a command involving pipelines is as follows. [expr] [,count ] pipeline [words...] Each dcmd's output is processed and stored as described in "dcmd Pipelines" in Section 13.2.8. After the left-hand dcmd is complete, its processed output is used as input for the next dcmd in the pipeline. If any dcmd does not return a successful exit status, the pipeline is aborted. For reference, Table 13.1 lists the full set of expression and pipeline combinations that form commands.
13.2.1. ExpressionsArithmetic expansion is performed when an MDB command is preceded by an optional expression representing a numerical argument for a dcmd. A list of common expressions is summarized in Tables 13.2, 13.3, and 13.4.
An example of a simple expression is adding an integer to an address. > d7c662e0+0t8/X 0xd7c662e8: d2998b80 > d7c662e0+0t8::print int 0xd7c662e8: d2998b80 13.2.2. SymbolsMDB can reference memory or objects according to the value of a symbol of the target. A symbol is the name of either a function or a global variable in the target. For example, you compute the address of the kernel's global variable lotsfree by entering it as an expression, and display it by using the = metacharacter. You display the value of the lotsfree symbol by using the / metacharacter. > lotsfree=X fec4b8d0 > lotsfree/D lotsfree: lotsfree: 3934 Symbol names can be resolved from kernel and userland process targets. In the kernel, the resolution of the symbol names can optionally be defined with a scope by specifying the module or object file name. In a process, symbols' scope can be defined by library or object file names. They take the form shown in Table 13.5.
The target typically searches the primary executable's symbol tables first, then one or more of the other symbol tables. Notice that ELF symbol tables contain only entries for external, global, and static symbols; automatic symbols do not appear in the symbol tables processed by MDB. Additionally, MDB provides a private user-defined symbol table that is searched before any of the target symbol tables are searched. The private symbol table is initially empty and can be manipulated with the ::nmadd and ::nmdel dcmds. The ::nm -P option displays the contents of the private symbol table. The private symbol table allows the user to create symbol definitions for program functions or data that were either missing from the original program or stripped out. > ::nm Value Size Type Bind Other Shndx Name 0x00000000|0x00000000|NOTY |LOCL |0x0 |UNDEF | 0xfec40038|0x00000000|OBJT |LOCL |0x0 |14 |_END_ 0xfe800000|0x00000000|OBJT |LOCL |0x0 |1 |_START_ 0xfec00000|0x00000000|NOTY |LOCL |0x0 |10 |__return_from_main ... These definitions are then used whenever MDB converts a symbolic name to an address, or an address to the nearest symbol. Because targets contain multiple symbol tables and each symbol table can include symbols from multiple object files, different symbols with the same name can exist. MDB uses the backquote "`" character as a symbol-name scoping operator to allow the programmer to obtain the value of the desired symbol in this situation. 13.2.3. Formatting MetacharactersThe /, \, ?, and = metacharacters denote the special output formatting dcmds. Each of these dcmds accepts an argument list consisting of one or more format characters, repeat counts, or quoted strings. A format character is one of the ASCII characters shown in Table 13.6.
13.2.4. Formatting CharactersFormat characters read or write and format data from the target. They are combined with the formatting metacharacters to read, write, or search memory. For example, if we want to display or set the value of a memory location, we could represent that location by its hexadecimal address or by its symbol name. Typically, we use a metacharacter with a format or a dcmd to indicate what we want MDB to do with the memory at the indicated address. In the following example, we display the address of the kernel's lotsfree symbol. We use the = metacharacter to display the absolute value of the symbol, lotsfree and the X format to display the address in 32-bit hexadecimal notation. > lotsfree=X fec4b8d0 In a more common example, we can use the / metacharacter to format for display the value at the address of the lotsfree symbol. > lotsfree/D lotsfree: lotsfree: 4062 Optionally, a repeat count can be supplied with a format. A repeat count is a positive integer preceding the format character and is always interpreted in base 10 (decimal). A repeat count can also be specified as an expression enclosed in square brackets preceded by a dollar sign ($[ ]). A string argument must be enclosed in double-quotes (" "). No blanks are necessary between format arguments. > lotsfree/4D lotsfree: lotsfree: 3934 1967 983 40 If MDB is started in writable (-w) mode, then write formats are enabled. Note that this should be considered MDB's dangerous mode, especially if operating on live kernels or applications. For example, if we wanted to rewrite the value indicated by lotsfree to a new value, we could use the W write format with a valid MDB value or arithmetic expression as shown in the summary at the start of this section. For example, the W format writes the 32-bit value to the given address. In this example, we use an integer value, represented by the 0t arithmetic expression prefix. > lotsfree/W 0t5000 lotsfree: lotsfree: f5e A complete list of format strings can be found with the ::formats dcmd. > ::formats + - increment dot by the count (variable size) - - decrement dot by the count (variable size) B - hexadecimal int (1 byte) C - character using C character notation (1 byte) D - decimal signed int (4 bytes) E - decimal unsigned long long (8 bytes) ... A summary of the common formatting characters and the required metacharacters is shown in Table 13.7 through Table 13.9.
13.2.5. dcmdsThe metacharacters we explored in the previous section are actually forms of dcmds. The more general form of a dcmd is ::name, where name is the command name, as summarized by the following: ::{module`}d expr>var write the value of expr into var A list of dcmds can be obtained with ::dcmds. Alternatively, the ::dmods command displays information about both dcmds and walkers, conveniently grouped per MDB module. > ::dmods -l genunix ... dcmd pfiles - print process file information dcmd pgrep - pattern match against all processes dcmd pid2proc - convert PID to proc_t address dcmd pmap - print process memory map dcmd project - display kernel project(s) dcmd prtconf - print devinfo tree dcmd ps - list processes (and associated thr,lwp) dcmd ptree - print process tree ... Help on individual dcmds is available with the help dcmd. Yes, almost everything in MDB is implemented as a dcmd! > ::help ps NAME ps - list processes (and associated thr,lwp) SYNOPSIS ::ps [-fltzTP] ATTRIBUTES Target: kvm Module: genunix Interface Stability: Unstable For example, we can optionally use ::ps as a simple dcmd with no arguments. > ::ps S PID PPID PGID SID UID FLAGS ADDR NAME R 0 0 0 0 0 0x00000001 fffffffffbc23640 sched R 3 0 0 0 0 0x00020001 ffffffff812278f8 fsflush R 2 0 0 0 0 0x00020001 ffffffff81228520 pageout R 1 0 0 0 0 0x42004000 ffffffff81229148 init R 1782 1 1782 1782 1 0x42000000 ffffffff8121cc38 lockd R 524 1 524 524 0 0x42000000 ffffffff8b7fd548 dmispd R 513 1 513 513 0 0x42010000 ffffffff87bd2878 snmpdx R 482 1 7 7 0 0x42004000 ffffffff87be90b8 intrd R 467 1 466 466 0 0x42010000 ffffffff87bd8020 smcboot Optionally, we could use the same ::ps dcmd with an address supplied in hexadecimal. > ffffffff87be90b8::ps S PID PPID PGID SID UID FLAGS ADDR NAME R 482 1 7 7 0 0x42004000 ffffffff87be90b8 intrd > ffffffff87be90b8::ps -ft S PID PPID PGID SID UID FLAGS ADDR NAME R 482 1 7 7 0 0x42004000 ffffffff87be90b8 /usr/perl5/bin/perl / usr/lib/intrd T 0xffffffff8926d4e0 <TS_SLEEP> 13.2.6. WalkersA walker is used to traverse a connect set of data. Walkers are a type of plugin that is coded to iterate over the specified type of data. In addition to the ::dcmds dcmd, the ::walkers dcmd lists walkers. > ::walkers Client_entry_cache - walk the Client_entry_cache cache DelegStateID_entry_cache - walk the DelegStateID_entry_cache cache File_entry_cache - walk the File_entry_cache cache HatHash - walk the HatHash cache ... For example, the ::proc walker could be used to traverse set of process structures (proc_ts). Many walkers also have a default data item to walk if none is specified. > ::walk proc fffffffffbc23640 ffffffff812278f8 ffffffff81228520 ... There are walkers to traverse common generic data structure indexes. For example, simple linked lists can be traversed with the ::list walker, and AVL trees with the ::avl walker. > ffffffff9a647ae0::walk avl ffffffff9087a990 fffffe85ad8aa878 fffffe85ad8aa170 ... > fffffffffbc23640::list proc_t p_prev fffffffffbc23640 ffffffff81229148 ffffffff81228520 ... 13.2.7. MacrosMDB provides a compatibility mode that can interpret macros built for adb. A macro file is a text file containing a set of commands to execute. Macro files typically automate the process of displaying a simple data structure. These older macros can therefore be used with either tool. The development of macros is discouraged, since they are difficult to construct and maintain. Following is an example of using a macro to display a data structure. > d8126310$<ce ce instance structure 0xd8126310: dip instance dev_regs d8c8e840 d84b65c8 d2999900 ... 13.2.8. PipelinesWalkers and dcmds can build on each other, combining to do more powerful things by placement into an mdb "pipeline." The purpose of a pipeline is to pass a list of values, typically virtual addresses, from one dcmd or walker to another. Pipeline stages might map a pointer from one type of data structure to a pointer to a corresponding data structure, sort a list of addresses, or select the addresses of structures with certain properties. MDB executes each dcmd in the pipeline in order from left to right. The leftmost dcmd executes with the current value of dot or with the value specified by an explicit expression at the start of the command. When a | operator is encountered, MDB creates a pipe (a shared buffer) between the output of the dcmd to its left and the MDB parser, and an empty list of values. To give you a taste of the power of pipelines, here's an example, running against the live kernel. The ::pgrep dcmd allows you to find all processes matching a pattern, the thread walker walks all of the threads in a process, and the ::findstack dcmd gets a stack trace for a given thread. Connecting them into a pipeline, you can yield the stack traces of all sshd threads on the system (note that the middle one is swapped out). MDB pipelines are quite similar to standard UNIX pipelines and afford debugger users a similar level of power and flexibility. > ::pgrep sshd S PID PPID PGID SID UID FLAGS ADDR NAME R 100174 1 100174 100174 0 0x42000000 0000030009216790 sshd R 276948 100174 100174 100174 0 0x42010000 000003002d9a9860 sshd R 276617 100174 100174 100174 0 0x42010000 0000030013943010 sshd > ::pgrep sshd | ::walk thread 3000c4f0c80 311967e9660 30f2ff2c340 > ::pgrep sshd | ::walk thread | ::findstack stack pointer for thread 3000c4f0c80: 2a10099d071 [ 000002a10099d071 cv_wait_sig_swap+0x130() ] 000002a10099d121 poll_common+0x530() 000002a10099d211 pollsys+0xf8() 000002a10099d2f1 syscall_trap32+0x1e8() stack pointer for thread 311967e9660: 2a100897071 [ 000002a100897071 cv_wait_sig_swap+0x130() ] stack pointer for thread 30f2ff2c340: 2a100693071 [ 000002a100693071 cv_wait_sig_swap+0x130() ] 000002a100693121 poll_common+0x530() 000002a100693211 pollsys+0xf8() 000002a1006932f1 syscall_trap32+0x1e8() The full list of built-in dcmds can be obtained with the ::dmods dcmd. > ::dmods -l mdb mdb dcmd $< - replace input with macro dcmd $<< - source macro dcmd $> - log session to a file dcmd $? - print status and registers dcmd $C - print stack backtrace ... 13.2.9. Piping to UNIX CommandsMDB can pipe output to UNIX commands with the ! pipe. A common task is to use grep to filter output from a dcmd. We've shown the output from ::ps for illustration; actually, a handy ::pgrep command handles this common task. > ::ps !grep inet R 255 1 255 255 0 0x42000000 ffffffff87be9ce0 inetd 13.2.10. Obtaining Symbolic Type InformationThe MDB environment exploits the Compact Type Format (CTF) information in debugging targets. This provides symbolic type information for data structures in the target; such information can then be used within the debugging environment. Several dcmds consume CTF information, most notably ::print. The ::print dcmd displays a target data type in native C representation. The following example shows ::print in action. /* process ID info */ struct pid { unsigned int pid_prinactive :1; unsigned int pid_pgorphaned :1; unsigned int pid_padding :6; /* used to be pid_ref, now an int */ unsigned int pid_prslot :24; pid_t pid_id; struct proc *pid_pglink; struct proc *pid_pgtail; struct pid *pid_link; uint_t pid_ref; }; See sys/proc.h > ::print -t "struct pid" { unsigned pid_prinactive :1 unsigned pid_pgorphaned :1 unsigned pid_padding :6 unsigned pid_prslot :24 pid_t pid_id struct proc *pid_pglink struct proc *pid_pgtail struct pid *pid_link uint_t pid_ref } The ::print dcmd is most useful to print data structures in their typed format. For example, using a pipeline we can look up the address of the p_pidp member of the supplied proc_t structure and print its structure's contents. > ::pgrep inet S PID PPID PGID SID UID FLAGS ADDR NAME R 1595 1 1595 1595 0 0x42000400 d7c662e0 inetd > d7c662e0::print proc_t p_pidp |::print -t "struct pid" { unsigned pid_prinactive :1 = 0 unsigned pid_pgorphaned :1 = 0x1 unsigned pid_padding :6 = 0 unsigned pid_prslot :24 = 0xae pid_t pid_id = 0x63b struct proc *pid_pglink = 0xd7c662e0 struct proc *pid_pgtail = 0xd7c662e0 struct pid *pid_link = 0 uint_t pid_ref = 0x3 } The ::print command also understands how to traverse more complex data structures. For example, here we traverse an element of an array. > d7c662e0::print proc_t p_user.u_auxv[9] { p_user.u_auxv[9].a_type = 0x6 p_user.u_auxv[9].a_un = { a_val = 0x1000 a_ptr = 0x1000 a_fcn = 0x1000 } } Several other dcmds, listed below, use the CTF information. Starting with Solaris 9, the kernel is compiled with CTF information, making type information available by default. Starting with Solaris 10, CTF information is also available in userland, and by default some of the core system libraries contain CTF. The CTF-related commands are summarized in Table 13.10.
13.2.11. VariablesA variable is a variable name, a corresponding integer value, and a set of attributes. A variable name is a sequence of letters, digits, underscores, or periods. A variable can be assigned a value with > dcmd and read with < dcmd. Additionally, the variable can be the ::typeset dcmd, and its attributes can be manipulated with the ::typeset dcmd. Each variable's value is represented as a 64-bit unsigned integer. A variable can have one or more of the following attributes:
The following examples shows assigning and referencing a variable. > 0t27>myvar > <myvar=D 27 > $v myvar = 1b . = 1b 0 = f5e b = fec00000 d = 85737 e = fe800000 m = 464c457f t = 1a3e70 The CPU's registers are also exported as variables. > ::vars uesp = 0 eip = 0 myvar = 1b cs = 0 savfp = 0 ds = 0 trapno = 0 es = 0 . = 1b 0 = f5e 1 = 0 2 = 0 ss = 0 9 = 0 fs = 0 gs = 0 _ = 0 eax = 0 b = fec00000 d = 85737 e = fe800000 eflags = 0 ebp = 0 m = 464c457f ebx = 0 t = 1a3e70 ecx = 0 hits = 0 edi = 0 edx = 0 err = 0 esi = 0 esp = 0 savpc = 0 thread = 0 Commands for working with variables are summarized in Table 13.11.
13.2.12. Walkers, Variables, and Expressions CombinedVariables can be combined with arithmetic expressions and evaluated to construct more complex pipelines, in which data is manipulated between stages. In a simple example, we might want to iterate only over processes that have a uid of zero. We can easily iterate over the processes by using a pipeline consisting of a walker and type information, which prints the cr_uids for every process. > ::walk proc | ::print proc_t p_cred->cr_uid cr_uid = 0 cr_uid = 0x19 cr_uid = 0x1 cr_uid = 0 ... Adding an expression allows us to select only those that match a particular condition. The ::walk dcmd takes an optional variable name, in which to place the value of the walk. In this example, the walker sets the value of myvar and also pipes the output of the same addresses into ::print, which extracts the value of proc_t->p_cred->cr_uid. The ::eval dcmd prints the variable myvar only when the expression is true; in this case when the result of the previous dcmd (the printed value of cr_uid) is equal to 1. The statement given to ::eval to execute retrieves the value of the variable myvar and formats it with the K format (uint_ptr_t). > ::walk proc myvar |::print proc_t p_cred->cr_uid |::grep .==1 |::eval <myvar=K fec1d280 d318d248 d318daa8 d318e308 ... > ::walk proc myvar | ::print proc_t p_cred->cr_uid |::grep .==1 |::eval <myvar=K |::print -d proc_t p_pidp->pid_id p_pidp->pid_id = 0t4189 p_pidp->pid_id = 0t4187 p_pidp->pid_id = 0t4067 p_pidp->pid_id = 0t4065 ... | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
EAN: 2147483647
Pages: 180