From adc93f6097615f16d57e8a24a256302f2144ec4e Mon Sep 17 00:00:00 2001 From: rsc Date: Fri, 14 Jan 2005 17:37:50 +0000 Subject: cut out the html - they're going to cause diffing problems. --- man/man1/db.html | 548 ------------------------------------------------------- 1 file changed, 548 deletions(-) delete mode 100644 man/man1/db.html (limited to 'man/man1/db.html') diff --git a/man/man1/db.html b/man/man1/db.html deleted file mode 100644 index eed2c3f9..00000000 --- a/man/man1/db.html +++ /dev/null @@ -1,548 +0,0 @@ - -db(1) - Plan 9 from User Space - - - - -
-
-
DB(1)DB(1) -
-
-

NAME
- -
- - db – debugger
- -
-

SYNOPSIS
- -
- - db [ option ... ] [ textfile ] [ pid | corefile ]
- -
-

DESCRIPTION
- -
- - Db is a general purpose debugging program. It may be used to examine - files and to provide a controlled environment for the execution - of programs. -
- - A textfile is a file containing the text and initialized data - of an executable program. A pid or corefile specifies the memory - image of a process. A pid gives the id of an executing process - to be accessed via ptrace(2). A corefile specifies the name of - a core dump (see core(5) on your system of choice) containing - the - memory image of a terminated process. This manual refers to the - memory image specified by pid or corefile as a memfile. -
- - A map associated with each textfile or memfile supports accesses - to instructions and data in the file; see ‘Addresses’. -
- - An argument consisting entirely of digits is assumed to be a process - id; otherwise, it is the name of a textfile or corefile. When - a textfile is given, the textfile map is associated with it. If - only a memfile is given, the textfile map is derived from the - corresponding textfile, if it can be determined (this varies from - system to - system). When a memfile is given, the memfile map is associated - with it; otherwise the map is undefined and accesses to it are - not permitted. -
- - Commands to db are read from the standard input and responses - are to the standard output. The options are
- −w    Open textfile and memfile for writing as well as reading.
- −Ipath
- -
- - Directory in which to look for relative path names in $< and $<< - commands.
- -
- −mmachine
- -
- - Assume instructions are for the given CPU type (possible names - include 386 and powerpc; adding the suffix −co as in 386−co and - powerpc−co selects disassembly in the manufacturer’s syntax, if - available, rather than the default Plan 9 syntax). -
- - -
- Most db commands have the following form:
- -
- - [address] [, count] [command] -
- - -
- If address is present then the current position, called ‘dot’, - is set to address. Initially dot is set to 0. Most commands are - repeated count times with dot advancing between repetitions. The - default count is 1. Address and count are expressions. Multiple - commands on one line must be separated by ;. -

Expressions
- Expressions are evaluated as long ints.
- .     The value of dot.
- +     The value of dot incremented by the current increment.
- ^     The value of dot decremented by the current increment.
- "     The last address typed.
- integer
- -
- - A number, in decimal radix by default. The prefixes 0 and 0o and - 0O (zero oh) force interpretation in octal radix; the prefixes - 0t and 0T force interpretation in decimal radix; the prefixes - 0x, 0X, and # force interpretation in hexadecimal radix. Thus - 020, 0o20, 0t16, and #10 all represent sixteen. - -
- integer.fraction
- -
- - A single-precision floating point number.
- -
- 'c'   The 16-bit value of a character. \ may be used to escape a - '.
- <name
- -
- - The value of name, which is a register name. The register names - are those printed by the $r command.
- -
- symbol
- -
- - A symbol is a sequence of upper or lower case letters, underscores - or digits, not starting with a digit. \ may be used to escape - other characters. The location of the symbol is calculated from - the symbol table in textfile.
- -
- routine.name
- -
- - The address of the variable name in the specified C routine. Both - routine and name are symbols. If name is omitted the value is - the address of the most recently activated stack frame corresponding - to routine; if routine is omitted, the active procedure is assumed.
- -
- file:integer
- -
- - The address of the instruction corresponding to the source statement - at the indicated line number of the file. If the source line contains - no executable statement, the address of the instruction associated - with the nearest executable source line is returned. Files begin - at line 1. If multiple files of the same name - are loaded, an expression of this form resolves to the first file - encountered in the symbol table.
- -
- (exp)
- -
- - The value of the expression exp. -
- - -
- Monadic operators
- -
- - *exp   The contents of the location addressed by exp in memfile.
- @exp   The contents of the location addressed by exp in textfile.
- −exp   Integer negation.
- ~exp   Bitwise complement.
- %exp   When used as an address, exp is an offset into the segment - named ublock; see ‘Addresses’.
- -
- - -
- Dyadic operators are left-associative and are less binding than - monadic operators.
- -
- - e1+e2Integer addition.
- e1−e2Integer subtraction.
- e1*e2Integer multiplication.
- e1%e2Integer division.
- e1&e2Bitwise conjunction.
- e1|e2Bitwise disjunction.
- e1#e2E1 rounded up to the next multiple of e2.
- -
-

Commands
- Most commands have the following syntax:
- ?f    Locations starting at address in textfile are printed according - to the format f.
- /f    Locations starting at address in memfile are printed according - to the format f.
- =f    The value of address itself is printed according to the format - f. -
- - A format consists of one or more characters that specify a style - of printing. Each format character may be preceded by a decimal - integer that is a repeat count for the format character. If no - format is given then the last format is used. -
- - Most format letters fetch some data, print it, and advance (a - local copy of) dot by the number of bytes fetched. The total number - of bytes in a format becomes the currentincrement.
- -
- - o     Print two-byte integer in octal.
- O     Print four-byte integer in octal.
- q     Print two-byte integer in signed octal.
- Q     Print four-byte integer in signed octal.
- d     Print two-byte integer in decimal.
- D     Print four-byte integer in decimal.
- V     Print eight-byte integer in decimal.
- Z     Print eight-byte integer in unsigned decimal.
- x     Print two-byte integer in hexadecimal.
- X     Print four-byte integer in hexadecimal.
- Y     Print eight-byte integer in hexadecimal.
- u     Print two-byte integer in unsigned decimal.
- U     Print four-byte integer in unsigned decimal.
- f     Print as a single-precision floating point number.
- F     Print double-precision floating point.
- b     Print the addressed byte in hexadecimal.
- c     Print the addressed byte as an ASCII character.
- C     Print the addressed byte as a character. Printable ASCII characters - are represented normally; others are printed in the form \xnn.
- s     Print the addressed characters, as a UTF string, until a zero - byte is reached. Advance dot by the length of the string, including - the zero terminator.
- S     Print a string using the escape convention (see C above).
- r     Print as UTF the addressed two-byte integer (rune).
- R     Print as UTF the addressed two-byte integers as runes until a - zero rune is reached. Advance dot by the length of the string, - including the zero terminator.
- i     Print as machine instructions. Dot is incremented by the size - of the instruction.
- I     As i above, but print the machine instructions in an alternate - form if possible.
- M     Print the addressed machine instruction in a machine-dependent - hexadecimal form.
- a     Print the value of dot in symbolic form. Dot is unaffected.
- A     Print the value of dot in hexadecimal. Dot is unaffected.
- z     Print the function name, source file, and line number corresponding - to dot (textfile only). Dot is unaffected.
- p     Print the addressed value in symbolic form. Dot is advanced by - the size of a machine address.
- t     When preceded by an integer, tabs to the next appropriate tab - stop. For example, 8t moves to the next 8-space tab stop. Dot - is unaffected.
- n     Print a newline. Dot is unaffected.
- "..."   Print the enclosed string. Dot is unaffected.
- ^     Dot is decremented by the current increment. Nothing is printed.
- +     Dot is incremented by 1. Nothing is printed.
- −     Dot is decremented by 1. Nothing is printed.
- -
- - -
- Other commands include:
- newline
- -
- - Update dot by the current increment. Repeat the previous command - with a count of 1.
- -
- [?/]l value mask
- -
- - Words starting at dot are masked with mask and compared with value - until a match is found. If l is used, the match is for a two-byte - integer; L matches four bytes. If no match is found then dot is - unchanged; otherwise dot is set to the matched location. If mask - is omitted then ~0 is used. - -
- [?/]w value ...
- -
- - Write the two-byte value into the addressed location. If the command - is W, write four bytes.
- -
- [?/]m s b e f [?]
- -
- - New values for (b, e, f) in the segment named s are recorded. - Valid segment names are text, data, or ublock. If less than three - address expressions are given, the remaining parameters are left - unchanged. If the list is terminated by ? or / then the file (textfile - or memfile respectively) is used for subsequent - requests. For example, /m? causes / to refer to textfile.
- -
- >name
- -
- - Dot is assigned to the variable or register named.
- -
- !     The rest of the line is passed to rc(1) for execution.
- $modifier
- -
- - Miscellaneous commands. The available modifiers are:
- <f    Read commands from the file f. If this command is executed in - a file, further commands in the file are not seen. If f is omitted, - the current input stream is terminated. If a count is given, and - is zero, the command is ignored.
- <<f   Similar to < except it can be used in a file of commands without - causing the file to be closed. There is a (small) limit to the - number of << files that can be open at once.
- >f    Append output to the file f, which is created if it does not - exist. If f is omitted, output is returned to the terminal.
- ?     Print process id, the condition which caused stopping or termination, - the registers and the instruction addressed by pc. This is the - default if modifier is omitted.
- r     Print the general registers and the instruction addressed by - pc. Dot is set to pc.
- R     Like $r, but include miscellaneous processor control registers - and floating point registers.
- f     Print floating-point register values as single-precision floating - point numbers.
- F     Print floating-point register values as double-precision floating - point numbers.
- b     Print all breakpoints and their associated counts and commands. - ‘B’ produces the same results.
- c     Stack backtrace. If address is given, it specifies the address - of a pair of 32-bit values containing the sp and pc of an active - process. This allows selecting among various contexts of a multi-threaded - process. If C is used, the names and (long) values of all parameters, - automatic and static variables are - -
- - printed for each active function. If count is given, only the - first count frames are printed.
- -
- a     Attach to the running process whose pid is contained in address.
- e     The names and values of all external variables are printed.
- w     Set the page width for output to address (default 80).
- q     Exit from db.
- m     Print the address maps.
- k     Simulate kernel memory management.
- Mmachine
- -
- - Set the machine type used for disassembling instructions.
- -
- -
- :modifier
- -
- - Manage a subprocess. Available modifiers are:
- h     Halt an asynchronously running process to allow breakpointing. - Unnecessary for processes created under db, e.g. by :r.
- bc    Set breakpoint at address. The breakpoint is executed count–1 - times before causing a stop. Also, if a command c is given it - is executed at each breakpoint and if it sets dot to zero the - breakpoint causes a stop.
- d     Delete breakpoint at address.
- r     Run textfile as a subprocess. If address is given the program - is entered at that point; otherwise the standard entry point is - used. Count specifies how many breakpoints are to be ignored before - stopping. Arguments to the subprocess may be supplied on the same - line as the command. An argument - -
- - starting with < or > causes the standard input or output to be established - for the command.
- -
- cs    The subprocess is continued. If s is omitted or nonzero, the - subprocess is sent the note that caused it to stop. If 0 is specified, - no note is sent. (If the stop was due to a breakpoint or single-step, - the corresponding note is elided before continuing.) Breakpoint - skipping is the same as for r. - ss    As for c except that the subprocess is single stepped for count - machine instructions. If a note is pending, it is received before - the first instruction is executed. If there is no current subprocess - then textfile is run as a subprocess as for r. In this case no - note can be sent; the remainder of the line is - -
- - treated as arguments to the subprocess.
- -
- Ss    Identical to s except the subprocess is single stepped for count - lines of C source. In optimized code, the correspondence between - C source and the machine instructions is approximate at best.
- x     The current subprocess, if any, is released by db and allowed - to continue executing normally.
- k     The current subprocess, if any, is terminated.
- nc    Display the pending notes for the process. If c is specified, - first delete c’th pending note.
- -
-

Addresses
- The location in a file or memory image associated with an address - is calculated from a map associated with the file. Each map contains - one or more quadruples (t, f, b, e, o), defining a segment named - t (usually, text, data, or core) in file f mapping addresses in - the range b through e to the part of the file beginning at - offset o. If segments overlap, later segments obscure earlier - ones. An address a is translated to a file address by finding - the last segment in the list for which b≤a<e; the location in the - file is then address+f–b. -
- - Usually, the text and initialized data of a program are mapped - by segments called text, data, and bss. Since a program file does - not contain stack data, this data is not mapped. The text segment - is mapped similarly in a normal (i.e., non-kernel) memfile. However, - one or more segments called data provide access to - process memory. This region contains the program’s static data, - the bss, the heap and the stack. -
- - Sometimes it is useful to define a map with a single segment mapping - the region from 0 to 0xFFFFFFFF; a map of this type allows an - entire file to be examined without address translation. -
- - The $m command dumps the currently active maps. The ?m and /m - commands modify the segment parameters in the textfile and memfile - maps, respectively.
- -

-

EXAMPLES
- -
- - To set a breakpoint at the beginning of write() in extant process - 27:
- -
- - % db 27
- :h
- write:b
- :c
- -
- - -
- To set a breakpoint at the entry of function parse when the local - variable argc in main is equal to 1:
- -
- - parse:b *main.argc−1=X
- -
- - -
- This prints the value of argc−1 which as a side effect sets dot; - when argc is one the breakpoint will fire. Beware that local variables - may be stored in registers; see the BUGS section.
- -
-

SEE ALSO
- -
- - acid(1)
- -
-

SOURCE
- -
- - /usr/local/plan9/src/cmd/db
- -
-

DIAGNOSTICS
- -
- - Exit status is 0, unless the last command failed or returned non-zero - status.
- -
-

BUGS
- -
- - Examining a local variable with routine.name returns the contents - of the memory allocated for the variable, but with optimization, - variables often reside in registers. Also, on some architectures, - the first argument is always passed in a register. -
- - Variables and parameters that have been optimized away do not - appear in the symbol table, returning the error bad local variable - when accessed by db. -
- - Breakpoints should not be set on instructions scheduled in delay - slots. When a program stops on such a breakpoint, it is usually - impossible to continue its execution.
- -
- -

 -
-
- - -
-
-
-Space Glenda -
-
- - -- cgit v1.2.3