usr/src/cmd/sgs/librtld_db/demo/common/rdb.man

   1 .\"
   2 .\" CDDL HEADER START
   3 .\"
   4 .\" The contents of this file are subject to the terms of the
   5 .\" Common Development and Distribution License (the "License").
   6 .\" You may not use this file except in compliance with the License.
   7 .\"
   8 .\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE
   9 .\" or http://www.opensolaris.org/os/licensing.
  10 .\" See the License for the specific language governing permissions
  11 .\" and limitations under the License.
  12 .\"
  13 .\" When distributing Covered Code, include this CDDL HEADER in each
  14 .\" file and include the License file at usr/src/OPENSOLARIS.LICENSE.
  15 .\" If applicable, add the following below this CDDL HEADER, with the
  16 .\" fields enclosed by brackets "[]" replaced with your own identifying
  17 .\" information: Portions Copyright [yyyy] [name of copyright owner]
  18 .\"
  19 .\" CDDL HEADER END
  20 .\"
  21 .\"
  22 .\" Copyright (c) 1996, 2010, Oracle and/or its affiliates. All rights reserved.
  23 .\"
  24 .if n .tr \--
  25 .TH rdb 1 "24 April 2008"
  26 .SH NAME
  27 rdb \- run-time demo debugger
  28 .SH SYNOPSIS
  29 .B rdb
  30 [
  31 .B -f
  32 .I file
  33 ]
  34 executable [executable arguments ...]
  35 .SH AVAILABILITY
  36 .LP
  37 SUNWosdem
  38 .SH DESCRIPTION
  39 .B rdb
  40 is a simple general purpose debugger built on top of
  41 .I procfs
  42 and
  43 .I librtld_db.
  44 .B rdb
  45 is distributed is source code format and is a sample
  46 of how to use the
  47 .I rtld_db
  48 interface and is not meant to be used in a production environment.
  49 .LP
  50 Each invocation of
  51 .B rdb
  52 will debug a single process.  In order to start debugging the process
  53 again from the beginning
  54 .B rdb
  55 must be reinvoked.
  56 .SH OPTIONS
  57 .TP 15
  58 .BI \-f " file"
  59 file containing a list of commands to be executed by rdb.  This option
  60 can be used to run
  61 .B rdb
  62 in batch mode.
  63 .SH USAGE
  64 .B rdb
  65 by default reads commands from standard input and displays responses on the
  66 standard output.
  67 .B rdb
  68 is terminated when it reads an EOF on input.
  69 The commands that
  70 .B rdb
  71 accepts follow:
  72 .TP 15
  73 .BI break " [address]"
  74 Set a break point at address.  If no address is specified then list
  75 all currently set breakpoints.
  76 .TP
  77 .B cont
  78 Continue execution of the debugged process.  Note that when rdb
  79 is first invoked it halts the program before it starts to run.  To
  80 start executing it you must use cont.
  81 .TP
  82 .BI delete " address"
  83 delete the breakpoint at address.
  84 .TP
  85 .BI echo " string"
  86 Prints a string to standard output.  The string must be surrounded
  87 by double-quotes("").
  88 .TP
  89 .BI event " {on|off}"
  90 To enable or disable the printing of event information to standard output.
  91 If enabled then
  92 .B rdb
  93 will monitor
  94 .I rtld_db
  95 events and print a message to standard output as they occur.
  96 .TP
  97 .B getmaps
  98 Instructs
  99 .B rdb
 100 to load the current link-maps via the
 101 .I rtld_db
 102 interface.  No information is printed.
 103 .TP
 104 .B linkmaps
 105 display current link-map information.
 106 .TP
 107 .B maps
 108 display memory mapping information.
 109 .TP
 110 .BI objpad " size"
 111 Set object padding to
 112 .I size
 113 bytes for objects mmap()'ed in by
 114 .B ld.so.1.
 115 object padding will only effect the loading of new objects,
 116 those already loaded in memory are not effected.
 117 .TP
 118 .B pltskip
 119 enables and disables the skipping over of procedure linkage table entries
 120 when stepping through a function call.
 121 .TP
 122 .BI print " {address [count [format]]|varname}"
 123 displays data stored at
 124 .I address
 125 or register information.  Type 'help print' from within rdb for more
 126 details on usage.
 127 .TP
 128 .BI step " [count [silent]]"
 129 single step
 130 .I count
 131 instructions.  If count is not given then signle step 1 instruction.  If
 132 the keyword silent is specified then do not dis-assemble the instructions
 133 as they are stepped.
 134 .TP
 135 .BI value " symbol_name"
 136 display the value (address) associated with a symbol
 137 .TP
 138 .B where
 139 display a stack trace
 140 .SH EXAMPLES
 141 A simple example showing how to load a program, set a break point
 142 at main, and to then display the link-maps of all objects loaded:
 143 .LP
 144 .nf
 145 .ft 3
 146 polyslo 310% rdb /usr/bin/ls
 147 parent: 28300 child: 28301 child procname: /proc/28301
 148 <rdb> break main
 149 break point set at: 0x11110
 150 <rdb> cont
 151 break point reached at addr: 0x11110
 152 <rdb> linkmaps
 153 Link Maps
 154 ---------
 155 link-map: id: 0x0 name: /usr/bin/ls
 156        base: 0x00010000   padd_base: 0xeffffa7c
 157   data_base: 0x00000000
 158         end: 0x00010000    padd_end: 0x00023ad0
 159 link-map: id: 0x0 name: /usr/lib/libc.so.1(/usr/platform/$PLATFORM/lib/libc_psr.so.1)
 160        base: 0xef700000   padd_base: 0xef7f131c
 161   data_base: 0x00000000
 162         end: 0xef700000    padd_end: 0xef7991cc
 163 link-map: id: 0x0 name: /usr/lib/libdl.so.1(/usr/lib/ld.so.1)
 164        base: 0xef7c0000   padd_base: 0xef7f1478
 165   data_base: 0x00000000
 166         end: 0xef7c0000    padd_end: 0xef7c0074
 167 link-map: id: 0x0 name: /usr/platform/SUNW,Ultra-60/lib/libc_psr.so.1
 168        base: 0xef6f0000   padd_base: 0xef7f15bc
 169   data_base: 0x00000000
 170         end: 0xef6f0000    padd_end: 0xef6f0074
 171 link-map: id: 0x1 name: /usr/lib/ld.so.1
 172        base: 0xef7d0000   padd_base: 0xef7d1375
 173   data_base: 0x00000000
 174         end: 0xef7d0000    padd_end: 0xef7f01f8
 175 <rdb> cont
 176 Makefile    gram.h      m_utils.c   rdb         regs.c
 177 gram.c      lex.c       objs        rdb_mach.h
 178 process terminated.
 179 <rdb>
 180 .ft
 181 .fi
 182 .SH SEE ALSO
 183 .BR ld.so.1 (1)
 184 .br
 185 .TZ LLM