.TH DB 1.SH NAMEdb \- debugger.SH SYNOPSIS.B db[.I option ...][.I textfile][.I pid].SH DESCRIPTION.I Dbis a general purpose debugging program.It may be used to examine files and to providea controlled environment for the executionof Plan 9 programs..PPA.I textfileis a file containing the text and initializeddata of an executable program.A.I memfileis the memory image of an executing process. It isusually accessed via the process id.RI ( pid )of the process in.BI /proc/ pid /mem\f1.A.I memfilecontains the text, data, and saved registers andprocess state. A.I mapassociated with each.I textfileor.I memfilesupports accesses to instructions and data in the file;see `Addresses'..PPAn argument consisting entirely of digits is assumedto be a process id; otherwise, it is the name of a.IR textfile .When a.I textfileis given, the textfile mapis associated with it.If only a.I pidis given, the textfile map isassociated with.BI /proc/ pid /text\f1.When a.I pidis given, the memfile map is associated with.BI /proc/ pid /mem\f1;otherwise it is undefined and accesses to the.I memfileare not permitted..PPCommands to.I dbare read from the standard input andresponses are to the standard output.The options are.TP.BI -kUse the kernel stack of process.IR pid to debug the executing kernel process.If.I textfileis not specified, file.BI / $cputype /9 typeis used, where.I typeis the second word in.BR $terminal ..TP.B -wCreate.I textfileand.I memfileif they don't exist; open them for writingas well as reading..TP.BI -I pathDirectory in which to look for relative path names in.B $<and.B $<<commands..TP.BI -m machineAssume instructions are for the given CPU type(any standard architecture name, such as.B alphaor.BR 386 ,plus.B mipscoand.BR sunsparc ,which cause disassembly to the manufacturer's syntax)instead of using the magic number to selectthe CPU type..PPMost.I dbcommands have the following form:.IP.RI [ address ].RB [ ,.IR count ].RI [ command ].PPIf.I addressis present then the current position, called `dot',is set to.IR address .Initially dotis set to 0.Most commands are repeated.I counttimes withdot advancing between repetitions.The default.I countis 1..I Addressand.I countare expressions.Multiple commands on one line must be separated by.LR ; ..SS ExpressionsExpressions are evaluated as long.IR ints ..TP 7.2n.B .The value of dot..TP 7.2n.B +The value of dotincremented by the current increment..TP 7.2n.B ^The value of dotdecremented by the current increment..TP 7.2n.B \&"The last.I addresstyped..TP 7.2n.I integerA number, in decimal radix by default.The prefixes.L 0and.L 0oand.L 0O(zero oh) force interpretationin octal radix; the prefixes.L 0tand.L 0Tforce interpretation indecimal radix; the prefixes.LR 0x ,.LR 0X ,and.L #force interpretation inhexadecimal radix.Thus.LR 020 ,.LR 0o20 ,.LR 0t16 ,and.L #10 all represent sixteen..TP 7.2n.IB integer . fractionA single-precision floating point number..TP 7.2n.BI \' c\| \'The16-bitvalue of a character..L \emay be used to escape a.LR \' ..TP 7.2n.BI < nameThe value of.IR name ,which is a register name.The register names arethose printed by the.B $rcommand..TP 7.2n.I symbolA.I symbolis a sequenceof upper or lower case letters, underscores ordigits, not starting with a digit..L \emay be used to escape other characters.The location of the.I symbolis calculated from the symbol tablein.IR textfile ..TP 7.2n.IB routine . nameThe address of the variable.I namein the specifiedC routine.Both.I routineand.I nameare.IR symbols .If.I nameis omitted the value is the address of themost recently activated stack framecorresponding to.IR routine ;if.I routineis omitted,the active procedureis assumed..TP 7.2n.IB file : integerThe address of the instruction correspondingto the source statement at the indicatedline number of the file. If the source line containsno executable statement, the address of theinstruction associated with the nearestexecutable source line is returned. Filesbegin at line 1. If multiple files of the samename are loaded, an expression of this form resolvesto the first file encountered in the symbol table..TP 7.2n.BI ( exp )The value of the expression.IR exp ..LP.I Monadic operators.RS.TP 7.2n.BI * expThe contents of the location addressedby.I expin.IR memfile ..TP 7.2n.BI @ expThe contents of the location addressed by.I expin.IR textfile ..TP 7.2n.BI - expInteger negation..TP 7.2n.BI ~ expBitwise complement..TP 7.2n.BI % expWhen used as an.IR address ,.I expis an offset into the segment named.IR ublock ;see `Addresses'..RE.LP.I "Dyadic\ operators"are left-associativeand are less binding than monadic operators..RS.TP 7.2n.IB e1 + e2Integer addition..TP 7.2n.IB e1 - e2Integer subtraction..TP 7.2n.IB e1 * e2Integer multiplication..TP 7.2n.IB e1 % e2Integer division..TP 7.2n.IB e1 & e2Bitwise conjunction..TP 7.2n.IB e1 | e2Bitwise disjunction..TP 7.2n.IB e1 # e2.I E1rounded up to the next multiple of.IR e2 ..RE.DT.SS CommandsMost commands have the following syntax:.TP .5i.BI ? fLocations starting at.I addressin.I textfileare printed according to the format.IR f ..TP.BI / fLocations starting at.I addressin.I memfileare printed according to the format.IR f ..TP.BI = fThe value of.I addressitself is printed according to the format.IR f ..PPA.I formatconsists of one or more characters that specify a styleof printing.Each format character may be preceded by a decimal integerthat is a repeat count for the format character.If no format is given then the last format is used..PPMost format letters fetch some data,print it,and advance (a local copy of) dotby the number of bytes fetched.The total number of bytes in a format becomes the.IR current increment ..ta 2.5n .5i.RS.TP.PD 0.B oPrint two-byte integer in octal..TP.B OPrint four-byte integer in octal..TP.B qPrint two-byte integer in signed octal..TP.B QPrint four-byte integer in signed octal..TP.B dPrint two-byte integer in decimal..TP.B DPrint four-byte integer in decimal..TP.B VPrint eight-byte integer in decimal..TP.B ZPrint eight-byte integer in unsigned decimal..TP.B xPrint two-byte integer in hexadecimal..TP.B XPrint four-byte integer in hexadecimal..TP.B YPrint eight-byte integer in hexadecimal..TP.B uPrint two-byte integer in unsigned decimal..TP.B UPrint four-byte integer in unsigned decimal..TP.B fPrintas a single-precision floating point number..TP.B FPrint double-precision floating point..TP.B bPrint the addressed byte in hexadecimal..TP.B cPrint the addressed byte as an.SM ASCIIcharacter..TP.B CPrint the addressed byte as a character.Printable.SM ASCIIcharactersare represented normally; othersare printed in the form.BR \exnn ..TP.B sPrint the addressed characters, as a.SM UTFstring, until a zero byteis reached.Advance dotby the length of the string,including the zero terminator..TP.B SPrint a string using the escape convention (see.B Cabove)..TP.B rPrint as.SM UTFthe addressed two-byte integer (rune)..TP.B RPrint as.SM UTFthe addressed two-byte integers as runesuntil a zero rune is reached.Advance dotby the length of the string,including the zero terminator..TP.B iPrint as machine instructions. Dot isincremented by the size of the instruction..TP.B IAs.B iabove, but print the machine instructions inan alternate form if possible:.B sunsparcand.B mipscoreproduce the manufacturers' syntax..TP.B MPrint the addressed machine instruction in amachine-dependent hexadecimal form..TP.B aPrint the value of dotin symbolic form.Dot is unaffected..TP.B APrint the value of dotin hexadecimal.Dot is unaffected..TP.B zPrint the function name, source file, and line numbercorresponding to dot (textfile only). Dot is unaffected..TP.B pPrint the addressed value in symbolic form.Dot is advanced by the size of a machine address..TP.B tWhen preceded by an integer, tabs to the nextappropriate tab stop.For example,.B 8t moves to the next 8-space tab stop.Dot is unaffected.Lines 1–500 of 1018. Load more
.TH DB 1 .SH NAME db \- debugger .SH SYNOPSIS .B db [ .I option ... ] [ .I textfile ] [ .I pid ] .SH DESCRIPTION .I Db is a general purpose debugging program. It may be used to examine files and to provide a controlled environment for the execution of Plan 9 programs. .PP A .I textfile is a file containing the text and initialized data of an executable program. A .I memfile is the memory image of an executing process. It is usually accessed via the process id .RI ( pid ) of the process in .BI /proc/ pid /mem\f1. A .I memfile contains the text, data, and saved registers and process state. A .I map associated with each .I textfile or .I memfile supports accesses to instructions and data in the file; see `Addresses'. .PP An argument consisting entirely of digits is assumed to be a process id; otherwise, it is the name of a .IR textfile . When a .I textfile is given, the textfile map is associated with it. If only a .I pid is given, the textfile map is associated with .BI /proc/ pid /text\f1. When a .I pid is given, the memfile map is associated with .BI /proc/ pid /mem\f1; otherwise it is undefined and accesses to the .I memfile are not permitted. .PP Commands to .I db are read from the standard input and responses are to the standard output. The options are .TP .BI -k Use the kernel stack of process .IR pid to debug the executing kernel process. If .I textfile is not specified, file .BI / $cputype /9 type is used, where .I type is the second word in .BR $terminal . .TP .B -w Create .I textfile and .I memfile if they don't exist; open them for writing as well as reading. .TP .BI -I path Directory in which to look for relative path names in .B $< and .B $<< commands. .TP .BI -m machine Assume instructions are for the given CPU type (any standard architecture name, such as .B alpha or .BR 386 , plus .B mipsco and .BR sunsparc , which cause disassembly to the manufacturer's syntax) instead of using the magic number to select the CPU type. .PP Most .I db commands have the following form: .IP .RI [ address ] .RB [ , .IR count ] .RI [ command ] .PP If .I address is present then the current position, called `dot', is set to .IR address . Initially dot is set to 0. Most commands are repeated .I count times with dot advancing between repetitions. The default .I count is 1. .I Address and .I count are expressions. Multiple commands on one line must be separated by .LR ; . .SS Expressions Expressions are evaluated as long .IR ints . .TP 7.2n .B . The value of dot. .TP 7.2n .B + The value of dot incremented by the current increment. .TP 7.2n .B ^ The value of dot decremented by the current increment. .TP 7.2n .B \&" The last .I address typed. .TP 7.2n .I integer A number, in decimal radix by default. The prefixes .L 0 and .L 0o and .L 0O (zero oh) force interpretation in octal radix; the prefixes .L 0t and .L 0T force interpretation in decimal radix; the prefixes .LR 0x , .LR 0X , and .L # force interpretation in hexadecimal radix. Thus .LR 020 , .LR 0o20 , .LR 0t16 , and .L #10 all represent sixteen. .TP 7.2n .IB integer . fraction A single-precision floating point number. .TP 7.2n .BI \' c\| \' The 16-bit value of a character. .L \e may be used to escape a .LR \' . .TP 7.2n .BI < name The value of .IR name , which is a register name. The register names are those printed by the .B $r command. .TP 7.2n .I symbol A .I symbol is a sequence of upper or lower case letters, underscores or digits, not starting with a digit. .L \e may be used to escape other characters. The location of the .I symbol is calculated from the symbol table in .IR textfile . .TP 7.2n .IB routine . name The address of the variable .I name in the specified C routine. Both .I routine and .I name are .IR symbols . If .I name is omitted the value is the address of the most recently activated stack frame corresponding to .IR routine ; if .I routine is omitted, the active procedure is assumed. .TP 7.2n .IB 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. .TP 7.2n .BI ( exp ) The value of the expression .IR exp . .LP .I Monadic operators .RS .TP 7.2n .BI * exp The contents of the location addressed by .I exp in .IR memfile . .TP 7.2n .BI @ exp The contents of the location addressed by .I exp in .IR textfile . .TP 7.2n .BI - exp Integer negation. .TP 7.2n .BI ~ exp Bitwise complement. .TP 7.2n .BI % exp When used as an .IR address , .I exp is an offset into the segment named .IR ublock ; see `Addresses'. .RE .LP .I "Dyadic\ operators" are left-associative and are less binding than monadic operators. .RS .TP 7.2n .IB e1 + e2 Integer addition. .TP 7.2n .IB e1 - e2 Integer subtraction. .TP 7.2n .IB e1 * e2 Integer multiplication. .TP 7.2n .IB e1 % e2 Integer division. .TP 7.2n .IB e1 & e2 Bitwise conjunction. .TP 7.2n .IB e1 | e2 Bitwise disjunction. .TP 7.2n .IB e1 # e2 .I E1 rounded up to the next multiple of .IR e2 . .RE .DT .SS Commands Most commands have the following syntax: .TP .5i .BI ? f Locations starting at .I address in .I textfile are printed according to the format .IR f . .TP .BI / f Locations starting at .I address in .I memfile are printed according to the format .IR f . .TP .BI = f The value of .I address itself is printed according to the format .IR f . .PP A .I 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. .PP 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 .IR current increment . .ta 2.5n .5i .RS .TP .PD 0 .B o Print two-byte integer in octal. .TP .B O Print four-byte integer in octal. .TP .B q Print two-byte integer in signed octal. .TP .B Q Print four-byte integer in signed octal. .TP .B d Print two-byte integer in decimal. .TP .B D Print four-byte integer in decimal. .TP .B V Print eight-byte integer in decimal. .TP .B Z Print eight-byte integer in unsigned decimal. .TP .B x Print two-byte integer in hexadecimal. .TP .B X Print four-byte integer in hexadecimal. .TP .B Y Print eight-byte integer in hexadecimal. .TP .B u Print two-byte integer in unsigned decimal. .TP .B U Print four-byte integer in unsigned decimal. .TP .B f Print as a single-precision floating point number. .TP .B F Print double-precision floating point. .TP .B b Print the addressed byte in hexadecimal. .TP .B c Print the addressed byte as an .SM ASCII character. .TP .B C Print the addressed byte as a character. Printable .SM ASCII characters are represented normally; others are printed in the form .BR \exnn . .TP .B s Print the addressed characters, as a .SM UTF string, until a zero byte is reached. Advance dot by the length of the string, including the zero terminator. .TP .B S Print a string using the escape convention (see .B C above). .TP .B r Print as .SM UTF the addressed two-byte integer (rune). .TP .B R Print as .SM 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. .TP .B i Print as machine instructions. Dot is incremented by the size of the instruction. .TP .B I As .B i above, but print the machine instructions in an alternate form if possible: .B sunsparc and .B mipsco reproduce the manufacturers' syntax. .TP .B M Print the addressed machine instruction in a machine-dependent hexadecimal form. .TP .B a Print the value of dot in symbolic form. Dot is unaffected. .TP .B A Print the value of dot in hexadecimal. Dot is unaffected. .TP .B z Print the function name, source file, and line number corresponding to dot (textfile only). Dot is unaffected. .TP .B p Print the addressed value in symbolic form. Dot is advanced by the size of a machine address. .TP .B t When preceded by an integer, tabs to the next appropriate tab stop. For example, .B 8t moves to the next 8-space tab stop. Dot is unaffected.