1.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
1.2 +++ b/agent/doc/clhsdb.html Sat Dec 01 00:00:00 2007 +0000
1.3 @@ -0,0 +1,118 @@
1.4 +<html>
1.5 +<head>
1.6 +<title>
1.7 +Command line HSDB
1.8 +</title>
1.9 +</head>
1.10 +<body>
1.11 +
1.12 +<h1>Command line HSDB</h1>
1.13 +<p>
1.14 +When debugging remote core dumps it is easier to work with command line tools instead of
1.15 +GUI tools. Command line HSDB (CLHSDB) tool is alternative to SA GUI tool HSDB.
1.16 +</p>
1.17 +
1.18 +<p>
1.19 +There is also JavaScript based SA command line interface called <a href="jsdb.html">jsdb</a>.
1.20 +But, CLHSDB supports Unix shell-like (or dbx/gdb-like) command line interface with
1.21 +support for output redirection/appending (familiar >, >>), command history and so on.
1.22 +Each CLHSDB command can have zero or more arguments and optionally end with output redirection
1.23 +(or append) to a file. Commands may be stored in a file and run using <b>source</b> command.
1.24 +<b>help</b> command prints usage message for all supported commands (or a specific command)
1.25 +</p>
1.26 +
1.27 +<h3>Shell/batch scripts to run command line HSDB</h3>
1.28 +
1.29 +<ul>
1.30 +<li>clhsdbproc.sh
1.31 +<li>clhsdbproc64.sh
1.32 +<li>clhsdbwindbg.bat
1.33 +<li>clhsdbwindbg64.bat
1.34 +</ul>
1.35 +
1.36 +<h3>Annotated output of CLHSDB help command</h3>
1.37 +
1.38 +<pre>
1.39 +<code>
1.40 +Available commands:
1.41 + assert true | false <font color="red">turn on/off asserts in SA code</font>
1.42 + attach pid | exec core <font color="red">attach SA to a process or core</font>
1.43 + class name <font color="red">find a Java class from debuggee and print oop</font>
1.44 + classes <font color="red">print all loaded Java classes with klassOop</font>
1.45 + detach <font color="red">detach SA from current target</font>
1.46 + dis address [ length ] <font color="red">disassemble (sparc/x86) specified number of instructions from given address</font>
1.47 + dumpclass { address | name } [ directory ] <font color="red">dump .class file for given klassOop or class name</font>
1.48 + dumpheap [ file ] <font color="red">dump heap in hprof binary format</font>
1.49 + echo [ true | false ] <font color="red">turn on/off command echo mode</font>
1.50 + examine [ address/count ] | [ address,address] <font color="red">show contents of memory from given address</font>
1.51 + field [ type [ name fieldtype isStatic offset address ] ] <font color="red">print info about a field of HotSpot type</font>
1.52 + findpc address <font color="red">print info. about pointer location</font>
1.53 + flags [ flag ] <font color="red">show all -XX flag name value pairs. or just show given flag</font>
1.54 + help [ command ] <font color="red">print help message for all commands or just given command</font>
1.55 + history <font color="red">show command history. usual !command-number syntax works.</font>
1.56 + inspect expression <font color="red">inspect a given oop</font>
1.57 + jdis address <font color="red">show bytecode disassembly of a given methodOop</font>
1.58 + jhisto <font color="red">show Java heap histogram</font>
1.59 + jseval script <font color="red">evaluate a given string as JavaScript code</font>
1.60 + jsload file <font color="red">load and evaluate a JavaScript file</font>
1.61 + jstack [-v] <font color="red">show Java stack trace of all Java threads. -v is verbose mode</font>
1.62 + livenmethods <font color="red">show all live nmethods</font>
1.63 + mem address [ length ] <font color="red">show contents of memory -- also shows closest ELF/COFF symbol if found</font>
1.64 + pmap <font color="red">show Solaris pmap-like output</font>
1.65 + print expression <font color="red">print given klassOop, methodOop or arbitrary address</font>
1.66 + printas type expression <font color="red">print given address as given HotSpot type. eg. print JavaThread <address></font>
1.67 + printstatics [ type ] <font color="red">print static fields of given HotSpot type (or all types if none specified)</font>
1.68 + pstack [-v] <font color="red">show mixed mode stack trace for all Java, non-Java threads. -v is verbose mode</font>
1.69 + quit <font color="red">quit CLHSDB tool</font>
1.70 + reattach <font color="red">detach and re-attach SA to current target</font>
1.71 + scanoops start end [ type ] <font color="red">scan a Oop from given start to end address</font>
1.72 + search [ heap | codecache | threads ] value <font color="red">search a value in heap or codecache or threads</font>
1.73 + source filename <font color="red">load and execute CLHSDB commands from given file</font>
1.74 + symbol name <font color="red">show address of a given ELF/COFF symbol</font>
1.75 + sysprops <font color="red">show all Java System properties</font>
1.76 + threads <font color="red">show all Java threads</font>
1.77 + tokenize ...
1.78 + type [ type [ name super isOop isInteger isUnsigned size ] ] <font color="red">show info. on HotSpot type</font>
1.79 + universe <font color="red">print gc universe</font>
1.80 + verbose true | false <font color="red">turn on/off verbose mode</font>
1.81 + versioncheck [ true | false ] <font color="red">turn on/off debuggee VM version check</font>
1.82 + whatis address <font color="red">print info about any arbitrary address</font>
1.83 + where { -a | id } <font color="red">print Java stack trace of given Java thread or all Java threads (-a)</font>
1.84 +</code>
1.85 +</pre>
1.86 +
1.87 +<h3>JavaScript integration</h3>
1.88 +
1.89 +<p>Few CLHSDB commands are already implemented in JavaScript. It is possible to extend CLHSDB command set
1.90 +by implementing more commands in a JavaScript file and by loading it by <b>jsload</b> command. <b>jseval</b>
1.91 +command may be used to evaluate arbitrary JavaScript expression from a string. Any JavaScript function
1.92 +may be exposed as a CLHSDB command by registering it using JavaScript <b><code>registerCommand</code></b>
1.93 +function. This function accepts command name, usage and name of the JavaScript implementation function
1.94 +as arguments.
1.95 +</p>
1.96 +
1.97 +<h3>Simple CLHSDB command implemented in JavaScript</h3>
1.98 +
1.99 +<b>File: test.js</b>
1.100 +<pre>
1.101 +<code>
1.102 +function helloImpl(name) {
1.103 + println("hello, " + name);
1.104 +}
1.105 +
1.106 +// register the above JavaScript function as CLHSDB command
1.107 +registerCommand("hello", "hello name", "helloImpl");
1.108 +</code>
1.109 +</pre>
1.110 +---------<br>
1.111 +
1.112 +"test.js" can be loaded in CLHSDB prompt using <b>jsload</b> command using
1.113 +
1.114 +<pre>
1.115 +<code>
1.116 +hsdb> jsload test.js
1.117 +</code>
1.118 +</pre>
1.119 +
1.120 +</body>
1.121 +</html>
