Return to db CVS log

Up to [Plan 9 NeXT] / lucent / sys / man / 1

Annotation of lucent/sys/man/1/db, revision 1.1

1.1     ! root        1: .TH DB 1
        !             2: .SH NAME
        !             3: db \- debugger
        !             4: .SH SYNOPSIS
        !             5: .B db
        !             6: [
        !             7: .I option ...
        !             8: ]
        !             9: [
        !            10: .I textfile
        !            11: ]
        !            12: [
        !            13: .I pid
        !            14: ]
        !            15: .SH DESCRIPTION
        !            16: .I Db
        !            17: is a general purpose debugging program.
        !            18: It may be used to examine files and to provide
        !            19: a controlled environment for the execution
        !            20: of Plan 9 programs.
        !            21: .PP
        !            22: A
        !            23: .I textfile
        !            24: is a file containing the text and initialized
        !            25: data of an executable program.
        !            26: A
        !            27: .I memfile
        !            28: is the memory image of an executing process.  It is
        !            29: usually accessed via the process id
        !            30: .RI ( pid )
        !            31: of the process in
        !            32: .BI /proc/ pid /mem\f1.
        !            33: A
        !            34: .I memfile
        !            35: contains the text, data, and saved registers and
        !            36: process state.  A
        !            37: .I map
        !            38: associated with each
        !            39: .I textfile
        !            40: or
        !            41: .I memfile
        !            42: supports accesses to instructions and data in the file;
        !            43: see `Addresses'.
        !            44: .PP
        !            45: An argument consisting entirely of digits is assumed
        !            46: to be a process id; otherwise, it is the name of a
        !            47: .IR textfile .
        !            48: When a
        !            49: .I textfile
        !            50: is given, the textfile map
        !            51: is associated with it.
        !            52: If only a
        !            53: .I pid
        !            54: is given, the textfile map is
        !            55: associated with
        !            56: .BI /proc/ pid /text\f1.
        !            57: When a
        !            58: .I pid
        !            59: is given, the memfile map is associated with
        !            60: .BI /proc/ pid /mem\f1;
        !            61: otherwise it is undefined and accesses to the
        !            62: .I memfile
        !            63: are not permitted.
        !            64: .PP
        !            65: Commands to
        !            66: .I db
        !            67: are read from the standard input and
        !            68: responses are to the standard output.
        !            69: The options are
        !            70: .TP
        !            71: .BI -k
        !            72: Use the kernel stack of process
        !            73: .IR pid 
        !            74: to debug the executing kernel process.
        !            75: If
        !            76: .I textfile
        !            77: is not specified, file
        !            78: .BI / $cputype /9 type
        !            79: is used, where
        !            80: .I type
        !            81: is the second word in
        !            82: .BR $terminal .
        !            83: .TP
        !            84: .B -w
        !            85: Create
        !            86: .I textfile
        !            87: and
        !            88: .I memfile
        !            89: if they don't exist; open them for writing
        !            90: as well as reading.
        !            91: .TP
        !            92: .BI -I path
        !            93: Directory in which to look for relative path names in
        !            94: .B $<
        !            95: and
        !            96: .B $<<
        !            97: commands.
        !            98: .TP
        !            99: .BI -m machine
        !           100: Assume instructions are for the given CPU type
        !           101: (one of
        !           102: .BR 3210 ,
        !           103: .BR 386 ,
        !           104: .BR 68020 ,
        !           105: .BR 960 ,
        !           106: .BR mips ,
        !           107: .BR mipsco ,
        !           108: .BR sparc ,
        !           109: or
        !           110: .BR sunsparc )
        !           111: instead of using the magic number to select
        !           112: the CPU type.
        !           113: .PP
        !           114: Most
        !           115: .I  db
        !           116: commands have the following form:
        !           117: .IP
        !           118: .RI [ address ]
        !           119: .RB [ ,
        !           120: .IR count ]
        !           121: .RI [ command ]
        !           122: .PP
        !           123: If
        !           124: .I address
        !           125: is present then the current position, called `dot',
        !           126: is set to
        !           127: .IR address .
        !           128: Initially dot
        !           129: is set to 0.
        !           130: Most commands are repeated
        !           131: .I count
        !           132: times with
        !           133: dot advancing between repetitions.
        !           134: The default
        !           135: .I count
        !           136: is 1.
        !           137: .I Address
        !           138: and
        !           139: .I count
        !           140: are expressions.
        !           141: Multiple commands on one line must be separated by
        !           142: .LR ; .
        !           143: .SS Expressions
        !           144: Expressions are evaluated as long
        !           145: .IR ints .
        !           146: .TP 7.2n
        !           147: .B .
        !           148: The value of dot.
        !           149: .TP 7.2n
        !           150: .B +
        !           151: The value of dot
        !           152: incremented by the current increment.
        !           153: .TP 7.2n
        !           154: .B ^
        !           155: The value of dot
        !           156: decremented by the current increment.
        !           157: .TP 7.2n
        !           158: .B \&"
        !           159: The last
        !           160: .I address
        !           161: typed.
        !           162: .TP 7.2n
        !           163: .I integer
        !           164: A number, in decimal radix by default.
        !           165: The prefixes
        !           166: .L 0
        !           167: and
        !           168: .L 0o
        !           169: and
        !           170: .L 0O
        !           171: (zero oh) force interpretation
        !           172: in octal radix; the prefixes
        !           173: .L 0t
        !           174: and
        !           175: .L 0T
        !           176: force interpretation in
        !           177: decimal radix; the prefixes
        !           178: .LR 0x ,
        !           179: .LR 0X ,
        !           180: and
        !           181: .L #
        !           182: force interpretation in
        !           183: hexadecimal radix.
        !           184: Thus
        !           185: .LR 020 ,
        !           186: .LR 0o20 ,
        !           187: .LR 0t16 ,
        !           188: and
        !           189: .L #10 
        !           190: all represent sixteen.
        !           191: .TP 7.2n
        !           192: .IB integer . fraction
        !           193: A single-precision floating point number.
        !           194: .TP 7.2n
        !           195: .BI \' c\| \'
        !           196: The
        !           197: 16-bit
        !           198: value of a character.
        !           199: .L \e
        !           200: may be used to escape a
        !           201: .LR \' .
        !           202: .TP 7.2n
        !           203: .BI < name
        !           204: The value of
        !           205: .IR name ,
        !           206: which is a register name.
        !           207: The register names are
        !           208: those printed by the
        !           209: .B $r
        !           210: command.
        !           211: .TP 7.2n
        !           212: .I symbol
        !           213: A
        !           214: .I symbol
        !           215: is a sequence
        !           216: of upper or lower case letters, underscores or
        !           217: digits, not starting with a digit.
        !           218: .L \e
        !           219: may be used to escape other characters.
        !           220: The location of the
        !           221: .I symbol
        !           222: is calculated from the symbol table
        !           223: in
        !           224: .IR textfile .
        !           225: .TP 7.2n
        !           226: .IB routine . name
        !           227: The address of the variable
        !           228: .I name
        !           229: in the specified
        !           230: C or ALEF routine.
        !           231: Both
        !           232: .I routine
        !           233: and
        !           234: .I name
        !           235: are
        !           236: .IR symbols .
        !           237: If
        !           238: .I name
        !           239: is omitted the value is the address of the
        !           240: most recently activated stack frame
        !           241: corresponding to
        !           242: .IR routine ;
        !           243: if
        !           244: .I routine
        !           245: is omitted,
        !           246: the active procedure
        !           247: is assumed.
        !           248: .TP 7.2n
        !           249: .IB file : integer
        !           250: The address of the instruction corresponding
        !           251: to the source statement at the indicated
        !           252: line number of the file.  If the source line contains
        !           253: no executable statement, the address of the
        !           254: instruction associated with the nearest
        !           255: executable source line is returned.  Files
        !           256: begin at line 1.  If multiple files of the same
        !           257: name are loaded, an expression of this form resolves
        !           258: to the first file encountered in the symbol table.
        !           259: .TP 7.2n
        !           260: .BI ( exp )
        !           261: The value of the expression
        !           262: .IR exp .
        !           263: .LP
        !           264: .I  Monadic operators
        !           265: .RS
        !           266: .TP 7.2n
        !           267: .BI * exp
        !           268: The contents of the location addressed
        !           269: by
        !           270: .I exp
        !           271: in
        !           272: .IR memfile .
        !           273: .TP 7.2n
        !           274: .BI @ exp
        !           275: The contents of the location addressed by
        !           276: .I exp
        !           277: in
        !           278: .IR textfile .
        !           279: .TP 7.2n
        !           280: .BI - exp
        !           281: Integer negation.
        !           282: .TP 7.2n
        !           283: .BI ~ exp
        !           284: Bitwise complement.
        !           285: .TP 7.2n
        !           286: .BI % exp
        !           287: When used as an
        !           288: .IR address ,
        !           289: .I exp
        !           290: is an offset into the segment named
        !           291: .IR ublock ;
        !           292: see `Addresses'.
        !           293: .RE
        !           294: .LP
        !           295: .I "Dyadic\ operators"
        !           296: are left-associative
        !           297: and are less binding than monadic operators.
        !           298: .RS
        !           299: .TP 7.2n
        !           300: .IB e1 + e2
        !           301: Integer addition.
        !           302: .TP 7.2n
        !           303: .IB e1 - e2
        !           304: Integer subtraction.
        !           305: .TP 7.2n
        !           306: .IB e1 * e2
        !           307: Integer multiplication.
        !           308: .TP 7.2n
        !           309: .IB e1 % e2
        !           310: Integer division.
        !           311: .TP 7.2n
        !           312: .IB e1 & e2
        !           313: Bitwise conjunction.
        !           314: .TP 7.2n
        !           315: .IB e1 | e2
        !           316: Bitwise disjunction.
        !           317: .TP 7.2n
        !           318: .IB e1 # e2
        !           319: .I E1
        !           320: rounded up to the next multiple of
        !           321: .IR e2 .
        !           322: .RE
        !           323: .DT
        !           324: .SS Commands
        !           325: Most commands have the following syntax:
        !           326: .TP .5i
        !           327: .BI ? f
        !           328: Locations starting at
        !           329: .I address
        !           330: in
        !           331: .I  textfile
        !           332: are printed according to the format
        !           333: .IR f .
        !           334: .TP
        !           335: .BI / f
        !           336: Locations starting at
        !           337: .I address
        !           338: in
        !           339: .I  memfile
        !           340: are printed according to the format
        !           341: .IR f .
        !           342: .TP
        !           343: .BI = f
        !           344: The value of
        !           345: .I address
        !           346: itself is printed according to the format
        !           347: .IR f .
        !           348: .PP
        !           349: A
        !           350: .I format
        !           351: consists of one or more characters that specify a style
        !           352: of printing.
        !           353: Each format character may be preceded by a decimal integer
        !           354: that is a repeat count for the format character.
        !           355: If no format is given then the last format is used.
        !           356: .PP
        !           357: Most format letters fetch some data,
        !           358: print it,
        !           359: and advance (a local copy of) dot
        !           360: by the number of bytes fetched.
        !           361: The total number of bytes in a format becomes the
        !           362: .I current increment\f1.
        !           363: .ta 2.5n .5i
        !           364: .RS
        !           365: .TP
        !           366: .PD 0
        !           367: .B o
        !           368: Print two-byte integer in octal.
        !           369: .TP
        !           370: .B O
        !           371: Print four-byte integer in octal.
        !           372: .TP
        !           373: .B q
        !           374: Print two-byte integer in signed octal.
        !           375: .TP
        !           376: .B Q
        !           377: Print four-byte integer in signed octal.
        !           378: .TP
        !           379: .B d
        !           380: Print two-byte integer in decimal.
        !           381: .TP
        !           382: .B D
        !           383: Print four-byte integer in decimal.
        !           384: .TP
        !           385: .B x
        !           386: Print two-byte integer in hexadecimal.
        !           387: .TP
        !           388: .B X
        !           389: Print four-byte integer in hexadecimal.
        !           390: .TP
        !           391: .B u
        !           392: Print two-byte integer in unsigned decimal.
        !           393: .TP
        !           394: .B U
        !           395: Print four-byte integer in unsigned decimal.
        !           396: .TP
        !           397: .B f
        !           398: Print
        !           399: as a single-precision floating point number.
        !           400: .TP
        !           401: .B F
        !           402: Print double-precision floating point.
        !           403: .TP
        !           404: .B b
        !           405: Print the addressed byte in hexadecimal.
        !           406: .TP
        !           407: .B c
        !           408: Print the addressed byte as an
        !           409: .SM ASCII
        !           410: character.
        !           411: .TP
        !           412: .B C
        !           413: Print the addressed byte as a character.
        !           414: Printable
        !           415: .SM ASCII
        !           416: characters
        !           417: are represented normally; others
        !           418: are printed in the form
        !           419: .BR \exnn .
        !           420: .TP
        !           421: .B s
        !           422: Print the addressed characters, as a
        !           423: .SM UTF
        !           424: string, until a zero byte
        !           425: is reached.
        !           426: Advance dot
        !           427: by the length of the string,
        !           428: including the zero terminator.
        !           429: .TP
        !           430: .B S
        !           431: Print a string using 
        !           432: the escape convention (see
        !           433: .B C
        !           434: above).
        !           435: .TP
        !           436: .B r
        !           437: Print as UTF the addressed two-byte integer (rune).
        !           438: .TP
        !           439: .B R
        !           440: Print as UTF the addressed two-byte integers as runes
        !           441: until a zero rune is reached.
        !           442: Advance dot
        !           443: by the length of the string,
        !           444: including the zero terminator.
        !           445: .TP
        !           446: .B Y
        !           447: Print a four-byte integer in date format (see
        !           448: .IR ctime (2)).
        !           449: .TP
        !           450: .B i
        !           451: Print as machine instructions.  Dot is
        !           452: incremented by the size of the instruction.
        !           453: .TP
        !           454: .B I
        !           455: As
        !           456: .B i
        !           457: above, but print the machine instructions in
        !           458: an alternate form if possible:
        !           459: .B sunsparc
        !           460: and
        !           461: .B mipsco
        !           462: reproduce the manufacturers' syntax.
        !           463: .TP
        !           464: .B M
        !           465: Print the addressed machine instruction in a
        !           466: machine-dependent hexadecimal form.
        !           467: .TP
        !           468: .B a
        !           469: Print the value of dot
        !           470: in symbolic form.
        !           471: Dot is unaffected.
        !           472: .TP
        !           473: .B A
        !           474: Print the value of dot
        !           475: in hexadecimal.
        !           476: Dot is unaffected.
        !           477: .TP
        !           478: .B z
        !           479: Print the function name, source file, and line number
        !           480: corresponding to dot (textfile only). Dot is unaffected.
        !           481: .TP
        !           482: .B p
        !           483: Print the addressed value in symbolic form.
        !           484: Dot is advanced by the size of a machine address.
        !           485: .TP
        !           486: .B t
        !           487: When preceded by an integer, tabs to the next
        !           488: appropriate tab stop.
        !           489: For example,
        !           490: .B 8t 
        !           491: moves to the next 8-space tab stop.
        !           492: Dot is unaffected.
        !           493: .TP
        !           494: .B n
        !           495: Print a newline.
        !           496: Dot is unaffected.
        !           497: .tr '"
        !           498: .TP
        !           499: .BR ' ... '
        !           500: Print the enclosed string.
        !           501: Dot is unaffected.
        !           502: .br
        !           503: .tr ''
        !           504: .TP
        !           505: .B ^
        !           506: Dot is decremented by the current increment.
        !           507: Nothing is printed.
        !           508: .TP
        !           509: .B +
        !           510: Dot is incremented by 1.
        !           511: Nothing is printed.
        !           512: .TP
        !           513: .B -
        !           514: Dot is decremented by 1.
        !           515: Nothing is printed.
        !           516: .RE
        !           517: .PD
        !           518: .LP
        !           519: Other commands include:
        !           520: .TP
        !           521: newline
        !           522: Update dot by the current increment.
        !           523: Repeat the previous command with a
        !           524: .I count
        !           525: of 1.
        !           526: .TP
        !           527: .RB [ ?/ ] l "\fI value mask\fR"
        !           528: Words starting at dot
        !           529: are masked with
        !           530: .I mask
        !           531: and compared with
        !           532: .I value
        !           533: until
        !           534: a match is found.
        !           535: If
        !           536: .B l
        !           537: is used,
        !           538: the match is for a two-byte integer;
        !           539: .B L
        !           540: matches four bytes.
        !           541: If no match is found then dot
        !           542: is unchanged; otherwise dot
        !           543: is set to the matched location.
        !           544: If
        !           545: .I mask
        !           546: is omitted then ~0 is used.
        !           547: .TP
        !           548: .RB [ ?/ ] w "\fI value ...\fR"
        !           549: Write the two-byte
        !           550: .I value
        !           551: into the addressed
        !           552: location.
        !           553: If the command is
        !           554: .BR W ,
        !           555: write four bytes.
        !           556: .TP
        !           557: .RB [ ?/ ] "m\fI s b e f \fP" [ ?\fR]
        !           558: .br
        !           559: New values for
        !           560: .RI ( b,\ e,\ f )
        !           561: in the segment named
        !           562: .I s
        !           563: are recorded.  Valid segment names are
        !           564: .IR text ,
        !           565: .IR data ,
        !           566: or 
        !           567: .IR ublock .
        !           568: If less than three address expressions are given,
        !           569: the remaining parameters are left unchanged.
        !           570: If the list is terminated by
        !           571: .L ?
        !           572: or
        !           573: .L /
        !           574: then the file
        !           575: .RI ( textfile
        !           576: or
        !           577: .I memfile
        !           578: respectively) is used
        !           579: for subsequent requests.
        !           580: For example,
        !           581: .L /m?
        !           582: causes
        !           583: .L /
        !           584: to refer to
        !           585: .IR textfile .
        !           586: .TP
        !           587: .BI > name
        !           588: Dot is assigned to the variable or register named.
        !           589: .TP
        !           590: .B !
        !           591: The rest of the line is passed to
        !           592: .IR rc (1)
        !           593: for execution.
        !           594: .TP
        !           595: .BI $ modifier
        !           596: Miscellaneous commands.
        !           597: The available 
        !           598: .I modifiers 
        !           599: are:
        !           600: .RS
        !           601: .TP
        !           602: .PD 0
        !           603: .BI < f
        !           604: Read commands from the file
        !           605: .IR f .
        !           606: If this command is executed in a file, further commands
        !           607: in the file are not seen.
        !           608: If
        !           609: .I f
        !           610: is omitted, the current input stream is terminated.
        !           611: If a
        !           612: .I count
        !           613: is given, and is zero, the command is ignored.
        !           614: .TP
        !           615: .BI << f
        !           616: Similar to
        !           617: .B <
        !           618: except it can be used in a file of commands without
        !           619: causing the file to be closed.
        !           620: There is a (small) limit to the number of
        !           621: .B <<
        !           622: files that can be open at once.
        !           623: .br
        !           624: .ns
        !           625: .TP
        !           626: .BI > f
        !           627: Append output to the file
        !           628: .IR f ,
        !           629: which is created if it does not exist.
        !           630: If
        !           631: .I f
        !           632: is omitted, output is returned to the terminal.
        !           633: .TP
        !           634: .B ?
        !           635: Print process id, the condition which caused stopping or termination,
        !           636: the registers and the instruction addressed by
        !           637: .BR pc .
        !           638: This is the default if
        !           639: .I modifier
        !           640: is omitted.
        !           641: .TP
        !           642: .B r
        !           643: Print the general registers and
        !           644: the instruction addressed by
        !           645: .BR pc .
        !           646: Dot is set to
        !           647: .BR pc .
        !           648: .TP
        !           649: .B R
        !           650: Like
        !           651: .BR $r ,
        !           652: but include miscellaneous processor control registers
        !           653: and floating point registers.
        !           654: .TP
        !           655: .B f
        !           656: Print floating-point register values as
        !           657: single-precision floating point numbers.
        !           658: .TP
        !           659: .B F
        !           660: Print floating-point register values as
        !           661: double-precision floating point numbers.
        !           662: .TP
        !           663: .B b
        !           664: Print all breakpoints
        !           665: and their associated counts and commands.  `B' produces the same results.
        !           666: .TP
        !           667: .B c
        !           668: Stack backtrace.
        !           669: If
        !           670: .I address
        !           671: is given, it specifies the address of a pair of 32-bit
        !           672: values containing the
        !           673: .B sp
        !           674: and
        !           675: .B pc
        !           676: of an active process.  This allows selecting
        !           677: among various contexts of a multi-threaded
        !           678: process.
        !           679: If
        !           680: .B C
        !           681: is used, the names and (long) values of all
        !           682: parameters,
        !           683: automatic
        !           684: and static variables are printed for each active function.
        !           685: If
        !           686: .I count
        !           687: is given, only the first
        !           688: .I count
        !           689: frames are printed.
        !           690: .TP
        !           691: .B a
        !           692: Attach to the running process whose pid
        !           693: is contained in
        !           694: .IR address .
        !           695: .TP
        !           696: .B e
        !           697: The names and values of all
        !           698: external variables are printed.
        !           699: .TP
        !           700: .B w
        !           701: Set the page width for output to
        !           702: .I address
        !           703: (default 80).
        !           704: .TP
        !           705: .B q
        !           706: Exit from
        !           707: .IR db .
        !           708: .TP
        !           709: .B m
        !           710: Print the address maps.
        !           711: .TP
        !           712: .B k
        !           713: Simulate kernel memory management.
        !           714: .TP
        !           715: .BI M machine
        !           716: Set the
        !           717: .I machine
        !           718: type used for disassembling instructions.
        !           719: .PD
        !           720: .RE
        !           721: .TP
        !           722: .BI : modifier
        !           723: Manage a subprocess.
        !           724: Available modifiers are:
        !           725: .RS
        !           726: .TP
        !           727: .PD 0
        !           728: .BI h
        !           729: Halt
        !           730: an asynchronously running process to allow breakpointing.
        !           731: Unnecessary for processes created under
        !           732: .IR db ,
        !           733: e.g. by
        !           734: .BR :r .
        !           735: .TP
        !           736: .BI b c
        !           737: Set breakpoint at
        !           738: .IR address .
        !           739: The breakpoint is executed
        !           740: .IR count \-1
        !           741: times before
        !           742: causing a stop.
        !           743: Also, if a command
        !           744: .I c
        !           745: is given it is executed at each
        !           746: breakpoint and if it sets dot to zero
        !           747: the breakpoint causes a stop.
        !           748: .TP
        !           749: .B d
        !           750: Delete breakpoint at
        !           751: .IR address .
        !           752: .TP
        !           753: .B r
        !           754: Run
        !           755: .I textfile
        !           756: as a subprocess.
        !           757: If
        !           758: .I address
        !           759: is given the
        !           760: program is entered at that point; otherwise
        !           761: the standard entry point is used.
        !           762: .I Count
        !           763: specifies how many breakpoints are to be
        !           764: ignored before stopping.
        !           765: Arguments to the subprocess may be supplied on the
        !           766: same line as the command.
        !           767: An argument starting with < or > causes the standard
        !           768: input or output to be established for the command.
        !           769: .TP
        !           770: .BI c s
        !           771: The subprocess is continued.
        !           772: If
        !           773: .I s
        !           774: is omitted
        !           775: or nonzero,
        !           776: the subprocess
        !           777: is sent the note that caused it to stop.
        !           778: If 0
        !           779: is specified,
        !           780: no note is sent.
        !           781: (If the stop was due to a breakpoint or single-step,
        !           782: the corresponding note is elided before continuing.)
        !           783: Breakpoint skipping is the same
        !           784: as for
        !           785: .BR r .
        !           786: .TP
        !           787: .BI s s
        !           788: As for
        !           789: .B c
        !           790: except that
        !           791: the subprocess is single stepped for
        !           792: .I count
        !           793: machine instructions.
        !           794: If a note is pending,
        !           795: it is received
        !           796: before the first instruction is executed.
        !           797: If there is no current subprocess then
        !           798: .I textfile
        !           799: is run
        !           800: as a subprocess as for
        !           801: .BR r .
        !           802: In this case no note can be sent; the remainder of the line
        !           803: is treated as arguments to the subprocess.
        !           804: .TP
        !           805: .BI S s
        !           806: Identical to
        !           807: .B s
        !           808: except the subprocess is single stepped for
        !           809: .I count
        !           810: lines of C source.  In optimized code, the correspondence
        !           811: between C source and the machine instructions is
        !           812: approximate at best.
        !           813: .TP
        !           814: .BI x
        !           815: The current subprocess, if any, is released by
        !           816: .I db
        !           817: and allowed to continue executing normally.
        !           818: .TP
        !           819: .B k
        !           820: The current subprocess, if any, is terminated.
        !           821: .TP
        !           822: .BI n c
        !           823: Display the pending notes for the process.
        !           824: If
        !           825: .I c
        !           826: is specified, first delete
        !           827: .I c'th
        !           828: pending note.
        !           829: .PD
        !           830: .RE
        !           831: .SS Addresses
        !           832: The location in a file or memory image associated with
        !           833: an address is calculated from a map
        !           834: associated with the file.
        !           835: Each map contains one or more quadruples
        !           836: .RI ( "t, b, e, f" ),
        !           837: defining a segment named
        !           838: .I t
        !           839: (usually, 
        !           840: .IR text ,
        !           841: .IR data ,
        !           842: or
        !           843: .IR ublock )
        !           844: mapping addresses in the range
        !           845: .I b
        !           846: through
        !           847: .I e
        !           848: to the part of the file
        !           849: beginning at
        !           850: offset
        !           851: .IR f .
        !           852: The memory model of a Plan 9 process assumes
        !           853: that segments are disjoint.  There
        !           854: can be more than one segment of a given type (e.g., a process
        !           855: may have more than one text segment) but segments
        !           856: may not overlap.
        !           857: An address
        !           858: .I a
        !           859: is translated
        !           860: to a file address
        !           861: by finding a segment
        !           862: for which
        !           863: .IR b ≤ a < e ;
        !           864: the location in the file
        !           865: is then
        !           866: .IR address + f \- b .
        !           867: .PP
        !           868: Usually,
        !           869: the text and initialized data of a program
        !           870: are mapped by segments called 
        !           871: .I text
        !           872: and
        !           873: .IR data .
        !           874: Since a program file does not contain bss, stack or ublock data,
        !           875: these data are
        !           876: not mapped by the data segment.
        !           877: The text segment is mapped similarly in
        !           878: a normal (i.e., non-kernel)
        !           879: .IR memfile .
        !           880: However, the segment called 
        !           881: .I data
        !           882: maps memory from the beginning of the program's data space to
        !           883: the base of the ublock.
        !           884: This region contains the program's static data, the bss, the
        !           885: heap and the stack.  A segment
        !           886: called
        !           887: .I ublock
        !           888: maps the page containing its registers and process state.
        !           889: .PP
        !           890: Sometimes it is useful to define a map with a single segment
        !           891: mapping the region from 0 to 0xFFFFFFFF; a map of this type
        !           892: allows the entire file to be examined
        !           893: without address translation.
        !           894: .PP
        !           895: Registers are saved at a machine-dependent offset in the ublock.
        !           896: It is usually not necessary to know this offset; the
        !           897: .BR $r ,
        !           898: .BR $R ,
        !           899: .BR $f ,
        !           900: and
        !           901: .BR $F
        !           902: commands calculate it and display the register contents.
        !           903: .PP
        !           904: The
        !           905: .B $m
        !           906: command dumps the currently active maps.  The
        !           907: .B ?m
        !           908: and
        !           909: .B /m
        !           910: commands modify the segment parameters in the
        !           911: .I textfile
        !           912: and
        !           913: .I memfile
        !           914: maps, respectively.
        !           915: .SH EXAMPLES
        !           916: To set a breakpoint at the beginning of
        !           917: .B write()
        !           918: in extant process 27:
        !           919: .IP
        !           920: .EX
        !           921: % db 27
        !           922: :h
        !           923: write:b
        !           924: :c
        !           925: .EE
        !           926: .PP
        !           927: To examine the Plan 9 kernel stack for process 27:
        !           928: .IP
        !           929: .EX
        !           930: % db -k 27
        !           931: $C
        !           932: .EE
        !           933: .PP
        !           934: Similar, but using a kernel named
        !           935: .BR test :
        !           936: .IP
        !           937: .EX
        !           938: % db -k test 27
        !           939: $C
        !           940: .EE
        !           941: .PP
        !           942: To set a breakpoint at the entry of function
        !           943: .B parse
        !           944: when the local variable
        !           945: .B argc
        !           946: in
        !           947: .B main
        !           948: is equal to 1:
        !           949: .IP
        !           950: .EX
        !           951: parse:b *main.argc-1=X
        !           952: .EE
        !           953: .PP
        !           954: This prints the value of
        !           955: .B argc-1
        !           956: which as a side effect sets dot; when
        !           957: .B argc
        !           958: is one the breakpoint will fire.
        !           959: Beware that local variables may be stored in registers; see the
        !           960: BUGS section.
        !           961: .PP
        !           962: Debug process 127 on remote machine
        !           963: .BR kremvax :
        !           964: .IP
        !           965: .EX
        !           966: % import kremvax /proc
        !           967: % db 127
        !           968: $C
        !           969: .EE
        !           970: .SH FILES
        !           971: .B /proc/*/text
        !           972: .br
        !           973: .B /proc/*/mem
        !           974: .br
        !           975: .B /proc/*/ctl
        !           976: .br
        !           977: .B /proc/*/note
        !           978: .SH "SEE ALSO"
        !           979: .IR acid (1),
        !           980: .IR nm (1),
        !           981: .IR proc (3)
        !           982: .SH SOURCE
        !           983: .B /sys/src/cmd/db
        !           984: .SH DIAGNOSTICS
        !           985: Exit status is null, unless the last command failed or
        !           986: returned non-null status.
        !           987: .SH BUGS
        !           988: Examining a local variable with
        !           989: .I routine.name
        !           990: returns the contents of the memory allocated for the variable, but
        !           991: with optimization (suppressed by the
        !           992: .B -N
        !           993: compiler flag) variables often reside in registers.
        !           994: Also, on some architectures, the first argument is always
        !           995: passed in a register.
        !           996: .PP
        !           997: Variables and parameters that have been
        !           998: optimized away do not appear in the
        !           999: symbol table, returning the error 
        !          1000: .IR "bad local variable"
        !          1001: when accessed by
        !          1002: .IR db .
        !          1003: .PP
        !          1004: Because of alignment incompatibilities, Motorola 68000
        !          1005: series machines can not be debugged remotely from a
        !          1006: processor of a different type.
        !          1007: .PP
        !          1008: Breakpoints should not be set on instructions scheduled
        !          1009: in delay slots.  When a program stops on such a breakpoint,
        !          1010: it is usually impossible to continue its execution.

This archive runs on limited infrastructure. Preserving old code on modern bandwidth. Automated agents are requested to crawl responsibly.