Return to db.1 CVS log

Up to [Research Unix] / researchv10dc / dist / man / v4 / man1

Annotation of researchv10dc/dist/man/v4/man1/db.1, revision 1.1

1.1     ! root        1: .th DB I 8/20/73
        !             2: .sh NAME
        !             3: db \*- debug
        !             4: .sh SYNOPSIS
        !             5: .bd db
        !             6: [ core [ namelist ] ] [
        !             7: .bd \*-
        !             8: ]
        !             9: .sh DESCRIPTION
        !            10: Unlike
        !            11: many debugging packages (including DEC's ODT, on
        !            12: which
        !            13: .it db
        !            14: is loosely based),
        !            15: .it db
        !            16: is not loaded as part of the
        !            17: core image which it is used to examine; instead it examines files.
        !            18: Typically, the file will be either a core image produced
        !            19: after a fault or the binary output of
        !            20: the assembler.
        !            21: .it Core
        !            22: is the file being debugged; if omitted \fBcore\fR is assumed.
        !            23: .it Namelist
        !            24: is a file containing a symbol table.
        !            25: If it is omitted,
        !            26: the symbol table is obtained from the
        !            27: file being debugged,
        !            28: or if not there from
        !            29: .bd a.out.
        !            30: If no appropriate name list file
        !            31: can be found,
        !            32: .it db
        !            33: can still be used but some of its symbolic
        !            34: facilities become unavailable.
        !            35: .s3
        !            36: For the meaning of the optional third argument, see
        !            37: the last paragraph below.
        !            38: .s3
        !            39: The format for most
        !            40: .it db
        !            41: requests is an address followed
        !            42: by a one character command.
        !            43: Addresses are expressions built up as follows:
        !            44: .s3
        !            45: .lp +4 3
        !            46: 1.     A name has the value assigned to it
        !            47: when the input file was assembled.
        !            48: It may be relocatable or not depending
        !            49: on the use of the name during the assembly.
        !            50: .s3
        !            51: .lp +4 3
        !            52: 2.     An octal number is an absolute quantity with the appropriate
        !            53: value.
        !            54: .s3
        !            55: .lp +4 3
        !            56: 3.     A decimal number immediately followed by `\fB.\fR' is
        !            57: an absolute quantity with the appropriate value.
        !            58: .s3
        !            59: .lp +4 3
        !            60: 4.     An octal number immediately followed by \fBr\fR is a relocatable
        !            61: quantity with the appropriate value.
        !            62: .s3
        !            63: .lp +4 3
        !            64: 5.     The symbol \fB.\fR indicates the current pointer
        !            65: of \fIdb\fR.
        !            66: The current pointer is set by many
        !            67: \fIdb\fR
        !            68: requests.
        !            69: .s3
        !            70: .lp +4 3
        !            71: 6.     A \fB*\fR before
        !            72: an expression forms an expression whose value is the
        !            73: number in the word addressed by the first expression.
        !            74: A \fB*\fR alone is equivalent to `\fB*.\fR'.
        !            75: .s3
        !            76: .lp +4 3
        !            77: 7.     Expressions separated by \fB+\fR or blank are expressions
        !            78: with value equal to the sum of the components.  At most
        !            79: one of the components may be relocatable.
        !            80: .s3
        !            81: .lp +4 3
        !            82: 8.     Expressions separated by \fB\*-\fR form an expression
        !            83: with value equal to the difference to the components.
        !            84: If the right component is relocatable, the left component
        !            85: must be relocatable.
        !            86: .s3
        !            87: .lp +4 3
        !            88: 9.     Expressions are evaluated left to right.
        !            89: .s3
        !            90: .in \n(inu
        !            91: Names for registers are
        !            92: built in:
        !            93: .s3
        !            94: .bd "   r0 ... r5"
        !            95: .bd "   sp"
        !            96: .bd "   pc"
        !            97: .bd "   fr0 ... fr5"
        !            98: .s3
        !            99: These may be examined.
        !           100: Their values are deduced from the contents
        !           101: of the stack in a core image file.  They are meaningless
        !           102: in a file that is not a core image.
        !           103: .s3
        !           104: If no address is given for a command, the current address
        !           105: (also specified by ``\fB.\fR'') is assumed.  In general, ``\fB.\fR''
        !           106: points to the last word or byte printed by
        !           107: .it db.
        !           108: .s3
        !           109: There are
        !           110: .it db
        !           111: commands for examining locations
        !           112: interpreted as numbers, machine instructions,
        !           113: ASCII characters, and addresses.
        !           114: For numbers and characters, either bytes
        !           115: or words may be examined.
        !           116: The following commands are used to examine the specified file.
        !           117: .s3
        !           118: .lp +4 3
        !           119: /      The addressed word is printed in octal.
        !           120: .s3
        !           121: .lp +4 3
        !           122: \\     The addressed byte is printed in octal.
        !           123: .s3
        !           124: .lp +4 3
        !           125: "      The addressed word is printed as two ASCII characters.
        !           126: .s3
        !           127: .if t .tr '\(aa\`\(ga
        !           128: .lp +4 3
        !           129: .li
        !           130: '      The addressed byte is printed as an ASCII character.
        !           131: .s3
        !           132: .lp +4 3
        !           133: `      The addressed word is printed in decimal.
        !           134: .s3
        !           135: .lp +4 3
        !           136: ?      The addressed word is interpreted as a machine
        !           137: instruction and a symbolic form of the instruction,
        !           138: including symbolic addresses, is printed.
        !           139: Often, the result will appear exactly as it was written
        !           140: in the source program.
        !           141: .s3
        !           142: .lp +4 3
        !           143: &      The addressed word is interpreted as a symbolic address
        !           144: and is printed as the name of the symbol whose value is closest
        !           145: to the addressed word, possibly followed by a signed offset.
        !           146: .s3
        !           147: .tr ''``
        !           148: .lp +4 3
        !           149: <nl>   (i. e., the character ``new line'')  This command advances
        !           150: the current location counter ``\fB.\fR'' and prints the resulting
        !           151: location in the mode last specified by
        !           152: one of the above requests.
        !           153: .s3
        !           154: .lp +4 3
        !           155: ^      This character decrements ``\fB.\fR'' and prints the
        !           156: resulting location in the mode last selected
        !           157: one of the above requests.  It is a converse to <nl>.
        !           158: .s3
        !           159: .lp +4 3
        !           160: %      Exit.
        !           161: .s3
        !           162: .in \n(inu
        !           163: Odd addresses to word-oriented commands are rounded
        !           164: down.
        !           165: The incrementing and decrementing
        !           166: of ``\fB.\fR'' done by the
        !           167: .bd <nl>
        !           168: and
        !           169: .bd ^
        !           170: requests is by one or
        !           171: two depending on whether the last command
        !           172: was word or byte oriented.
        !           173: .s3
        !           174: The address portion of any of the above commands
        !           175: may be followed by a comma and then by an
        !           176: expression.  In this case that number of sequential
        !           177: words or bytes specified by the expression is printed.
        !           178: ``\fB.\fR'' is advanced so that it points at the
        !           179: last thing printed.
        !           180: .s3
        !           181: There are two commands to interpret the value
        !           182: of expressions.
        !           183: .s3
        !           184: .lp +4 3
        !           185: =      When preceded by an expression, the value of the expression
        !           186: is typed in octal.
        !           187: When not preceded by an expression, the value of ``\fB.\fR'' is
        !           188: indicated.
        !           189: This command does not change the value of ``\fB.\fR''.
        !           190: .s3
        !           191: .lp +4 3
        !           192: :      An attempt is made to print the given expression
        !           193: as a symbolic address.  If the expression is relocatable,
        !           194: that symbol is found whose value is nearest
        !           195: that of the expression, and the symbol is typed, followed by
        !           196: a sign and the appropriate offset.
        !           197: If the value of the expression is absolute, a symbol
        !           198: with exactly the indicated value is sought and
        !           199: printed if found; if no matching symbol is discovered, the
        !           200: octal value of the expression is given.
        !           201: .s3
        !           202: .in \n(inu
        !           203: The following command may be used to patch the file being debugged.
        !           204: .s3
        !           205: .lp +4 3
        !           206: !      This command must be preceded by an expression.
        !           207: The value of the expression is stored at the location
        !           208: addressed by the current value of ``\fB.\fR''.
        !           209: The opcodes do not appear in the symbol
        !           210: table, so the user must assemble them by hand.
        !           211: .s3
        !           212: .in \n(inu
        !           213: The following command is used after a fault has caused
        !           214: a core image file to be produced.
        !           215: .s3
        !           216: .lp +4 3
        !           217: $      causes the fault type and
        !           218: the contents of the general registers and
        !           219: several other registers to be printed both in octal and symbolic
        !           220: format.
        !           221: The values are as they were at the time of the fault.
        !           222: .s3
        !           223: .in \n(inu
        !           224: For some purposes, it is important to know how addresses
        !           225: typed by the user correspond with
        !           226: locations in the file being debugged.
        !           227: The mapping algorithm employed by
        !           228: .it db
        !           229: is non-trivial
        !           230: for two reasons:
        !           231: First, in an
        !           232: .bd a.out
        !           233: file, there is a 20(8) byte header
        !           234: which will not appear when the file is loaded into
        !           235: core for execution.
        !           236: Therefore, apparent location 0 should correspond
        !           237: with actual file offset 20.
        !           238: Second, addresses
        !           239: in core images do not correspond with the
        !           240: addresses used by the program because in a core image
        !           241: there is a 512-byte header containing the
        !           242: system's per-process
        !           243: data for the dumped process, and also because the
        !           244: stack is stored contiguously with the text and data
        !           245: part of the core image rather than at the highest possible
        !           246: locations.
        !           247: .it Db
        !           248: obeys the following rules:
        !           249: .s3
        !           250: If exactly one argument is given, and if it appears
        !           251: to be an
        !           252: .bd a.out
        !           253: file, the 20-byte header is skipped
        !           254: during addressing, i.e., 20 is added to all addresses typed.
        !           255: As a consequence, the header can be examined
        !           256: beginning at location \*-20.
        !           257: .s3
        !           258: If exactly one argument is given and if the file does
        !           259: not appear to be an
        !           260: .bd a.out
        !           261: file, no mapping is done.
        !           262: .s3
        !           263: If zero or two arguments are given,
        !           264: the mapping appropriate to a core image file is employed.
        !           265: This means that locations above the program break
        !           266: and below the stack
        !           267: effectively do not exist (and are not, in fact, recorded
        !           268: in the core file).
        !           269: Locations above the user's stack pointer are mapped,
        !           270: in looking at the core file, to
        !           271: the place where they are really stored.
        !           272: The per-process data kept by the
        !           273: system, which is stored in the first 512(10) bytes
        !           274: of the core file,
        !           275: cannot currently be examined (except by \fB$\fR).
        !           276: .s3
        !           277: If one wants to examine
        !           278: a file which has an associated name list,
        !           279: but is not a core image file, the last argument ``\fB\*-\fR''
        !           280: can be used (actually the only purpose of the
        !           281: last argument is to make the number of
        !           282: arguments not equal to two).
        !           283: This feature is used most frequently in
        !           284: examining the memory file /dev/mem.
        !           285: .sh "SEE ALSO"
        !           286: as(I), core(V), a.out(V), od(I)
        !           287: .sh DIAGNOSTICS
        !           288: ``File not found'' if the first argument
        !           289: cannot be read; otherwise ``\fB?\fR''.
        !           290: .sh BUGS
        !           291: There should be some way to examine the registers
        !           292: and other per-process data in a core image;
        !           293: also there should be some way of specifying
        !           294: double-precision addresses.
        !           295: It does not know yet about shared text segments.

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