dcmd Pipelines

dcmds can be composed into a pipeline using the | operator. 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 be used to map a pointer from one type of data structure to a pointer to a corresponding data structure, to sort a list of addresses, or to select the addresses of structures with certain properties.

MDB executes each dcmd in the pipeline in order from left to right. The left-most dcmd is executed using the current value of dot, or using 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.

As the dcmd executes, its standard output is placed in the pipe and then consumed and evaluated by the parser, as if MDB were reading this data from standard input. Each line must consist of an arithmetic expression terminated by a NEWLINE or semicolon (;). The value of the expression is appended to the list of values associated with the pipe. If a syntax error is detected, the pipeline is aborted.

When the dcmd to the left of a | operator completes, the list of values associated with the pipe is then used to invoke the dcmd to the right of the | operator. For each value in the list, dot is set to this value and the right-hand dcmd is executed. Only the rightmost dcmd in the pipeline has its output printed to standard output. If any dcmd in the pipeline produces output to standard error, these messages are printed directly to standard error and are not processed as part of the pipeline.

Formatting dcmds

The /, \, ?, and = metacharacters are used to 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 the table below.

Format characters are used to read and format data from the target. A repeat count is a positive integer preceding the format character that 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.

The formatting dcmds are:

/	Display data from the target's virtual address space starting at the virtual address specified by dot.
\	Display data from the target's physical address space starting at the physical address specified by dot.
?	Display data from the target's primary object file starting at the object file location corresponding to the virtual address specified by dot.
=	Display the value of dot itself in each of the specified data formats. The = dcmd is therefore useful for converting between bases and performing arithmetic.

In addition to dot, MDB keeps track of another global value called the increment. The increment represents the distance between dot and the address following all the data read by the last formatting dcmd.

For example, if a formatting dcmd is executed with dot equal to address A, and displays a 4-byte integer, then after this dcmd completes, dot is still A, but the increment is set to 4. The + character, described in "Arithmetic Expansion", would now evaluate to the value A + 4, and could be used to reset dot to the address of the next data object for a subsequent dcmd.

Most format characters increase the value of the increment by the number of bytes corresponding to the size of the data format, shown in the table. The table of format characters can be displayed from within MDB using the ::formats dcmd.

The format characters are:

+	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)
F	Double (8 bytes)
G	Octal unsigned long long (8 bytes)
H	Swap bytes and shorts (4 bytes)
I	Address and disassembled instruction (variable size)
J	Hexadecimal long long (8 bytes)
K	Hexadecimal uintptr_t (4 or 8 bytes)
N	Newline
O	Octal unsigned int (4 bytes)
P	Symbol (4 or 8 bytes)
Q	Octal signed int (4 bytes)
R	Binary int (8 bytes)
S	String using C string notation (variable size)
T	Horizontal tab
U	Decimal unsigned int (4 bytes)
V	Decimal unsigned int (1 byte)
W	Default radix unsigned int (4 bytes)
X	Hexadecimal int (4 bytes)
Y	Decoded time32_t (4 bytes)
Z	Hexadecimal long long (8 bytes)
^	Decrement dot by increment * count (variable size)
a	Dot as symbol+offset
b	Octal unsigned int (1 byte)
c	Character (1 byte)
d	Decimal signed short (2 bytes)
e	Decimal signed long long (8 bytes)
f	Float (4 bytes)
g	Octal signed long long (8 bytes)
h	Swap bytes (2 bytes)
i	Disassembled instruction (variable size)
n	Newline
o	Octal unsigned short (2 bytes)
p	Symbol (4 or 8 bytes)
q	Octal signed short (2 bytes)
r	Whitespace
s	Raw string (variable size)
t	Horizontal tab
u	Decimal unsigned short (2 bytes)
v	Decimal signed int (1 byte)
w	Default radix unsigned short (2 bytes)
x	Hexadecimal short (2 bytes)
y	Decoded time64_t (8 bytes)