Commands

Commands

The following is documentation detailing the various commands available in sdb and what each can do.


Connecting to a JVM

attach

Attaches to a JVM that is listening for a debugger on a TCP socket.

Argument NameTypeDescriptionDefaultRequired
portNumberThe port of the remote JVM to attach to.N/AYes
hostnameTextThe name/IP of the host to connect to.localhostNo
timeoutNumberThe amount of time to wait to connect in milliseconds, or -1 to wait forever.-1No

attachp

Attaches to a JVM using its PID to look up the TCP port that the JVM is listening on for connections.

Argument NameTypeDescriptionDefaultRequired
pidNumberThe pid of the remote JVM to attach to.N/AYes
timeoutNumberThe amount of time to wait to connect in milliseconds, or -1 to wait forever.-1No

listen

Listens on the specified port for remote JVMs to attach to the debugger.

Argument NameTypeDescriptionDefaultRequired
portNumberThe port to listen on for remote JVMs.N/AYes
hostnameTextThe name/IP to bind to when listening.localhostNo

launch

Launches a new JVM using the specified class and attaches to it.

Argument NameTypeDescriptionDefaultRequired
classTextThe fully-qualified class name to use as the entrypoint to the new JVM.N/AYes
suspendTruthWhether or not to suspend the JVM when started.trueNo

stop

Disconnects from all connected JVMs and stops the active debugger.

Breakpoints

bp

Creates a new breakpoint on the specified file's line.

Argument NameTypeDescriptionDefaultRequired
fileTextThe full path to the file starting at the package. E.g. "org/scaladebugger/file.scala".N/AYes
lineNumberThe line number within the file to set a breakpoint.N/AYes

bpclear

Removes all breakpoints if no arguments given. Removes a single breakpoint if the file and line arguments are provided.

Argument NameTypeDescriptionDefaultRequired
fileTextThe full path to the file starting at the package. E.g. "org/scaladebugger/file.scala".N/ANo
lineNumberThe line number within the file to remove a breakpoint.N/ANo

bplist

Lists all breakpoint requests.

Class/Method/Field Info

classes

Lists all classes on the connected JVM.

Argument NameTypeDescriptionDefaultRequired
filterTextThe filter to use to limit which classes are returned. Supports wildcards. E.g. "org.scaladebugger.".""No
filterNotTextThe filter to use to limit which classes are not returned. Supports wildcards. E.g. "java.".""No

methods

Lists all methods for the specified class.

Argument NameTypeDescriptionDefaultRequired
classTextThe fully-qualified class name whose methods to list.N/AYes
filterTextThe filter to use to limit which methods are returned. Supports wildcards. E.g. "get*"."*"No
filterNotTextThe filter to use to limit which methods are not returned. Supports wildcards. E.g. "set*"."*"No

fields

Lists all fields for the specified class.

Argument NameTypeDescriptionDefaultRequired
classTextThe fully-qualified class name whose fields to list.N/AYes
filterTextThe filter to use to limit which fields are returned. Supports wildcards. E.g. "field*"."*"No
filterNotTextThe filter to use to limit which fields are not returned. Supports wildcards. E.g. "other*"."*"No

Exceptions

catch

Creates a new request to suspend on exceptions. Handles exceptions that are caught in a try as well as exceptions that are uncaught.

Argument NameTypeDescriptionDefaultRequired
filterTextThe filter to use to limit which exceptions to handle. Supports wildcards. E.g. "my.exceptions.".""No

catchc

Creates a new request to suspend on exceptions. Handles exceptions that are caught in a try.

Argument NameTypeDescriptionDefaultRequired
filterTextThe filter to use to limit which exceptions to handle. Supports wildcards. E.g. "my.exceptions.".""No

catchu

Creates a new request to suspend on exceptions. Handles exceptions that are uncaught.

Argument NameTypeDescriptionDefaultRequired
filterTextThe filter to use to limit which exceptions to handle. Supports wildcards. E.g. "my.exceptions.".""No

catchlist

Lists all exception requests.

ignore

Removes a request targeting both caught and uncaught exceptions. If no argument provided, removes the global exception handler for caught and uncaught exceptions.

Argument NameTypeDescriptionDefaultRequired
filterTextThe filter to use to limit which exception requests to remove. Supports wildcards. E.g. "my.exceptions.".""No

ignorec

Removes a request targeting caught exceptions. If no argument provided, removes the global exception handler for caught exceptions.

Argument NameTypeDescriptionDefaultRequired
filterTextThe filter to use to limit which exception requests to remove. Supports wildcards. E.g. "my.exceptions.".""No

ignoreu

Removes a request targeting uncaught exceptions. If no argument provided, removes the global exception handler for uncaught exceptions.

Argument NameTypeDescriptionDefaultRequired
filterTextThe filter to use to limit which exception requests to remove. Supports wildcards. E.g. "my.exceptions.".""No

Expressions

examine

Prints information about the provided expression.

Requires an active thread to be set.

Currently, only variables and chained properties using dot notation are supported.

Argument NameTypeDescriptionDefaultRequired
expressionTextThe expression to examine. E.g. "obj.field"."*"No

set

Sets the value for a variable to the specified new value.

Requires an active thread to be set and suspended.

Argument NameTypeDescriptionDefaultRequired
lTextThe variable to set. E.g. "obj.field".N/AYes
rAnyThe new variable value.N/AYes

locals

Lists the names and values of all variables and fields locally available in the current thread's top stack frame.

Requires an active thread to be set.

dump

Not yet implemented.

eval

Not yet implemented.

Methods

mentry

Creates a new request to suspend on entering a method.

Argument NameTypeDescriptionDefaultRequired
classTextThe fully-qualified name of the class whose method to suspend on entry.N/AYes
methodTextThe name of the method to suspend on entry.N/AYes

mentryclear

Clears a single method entry request for the specified method, or clears all method entry requests for a specific class if no method specified.

Argument NameTypeDescriptionDefaultRequired
classTextThe fully-qualified name of the class whose method entry request to remove.N/AYes
methodTextThe name of the method whose method entry request to remove.N/ANo

mentrylist

Lists all method entry requests.

mexit

Creates a new request to suspend on exiting a method.

Argument NameTypeDescriptionDefaultRequired
classTextThe fully-qualified name of the class whose method to suspend on exit.N/AYes
methodTextThe name of the method to suspend on exit.N/AYes

mexitclear

Clears a single method exit request for the specified method, or clears all method exit requests for a specific class if no method specified.

Argument NameTypeDescriptionDefaultRequired
classTextThe fully-qualified name of the class whose method exit request to remove.N/AYes
methodTextThe name of the method whose method exit request to remove.N/ANo

mexitlist

Lists all method exit requests.

Sources

list

Prints the source code around the current location of the active thread.

Requires an active thread to be set.

Argument NameTypeDescriptionDefaultRequired
sizeNumberThe number of lines to display above and below the current position.4No

sourcepath

Adds a new source path to the list used for source code printing, or displays the current source paths if no argument provided.

Argument NameTypeDescriptionDefaultRequired
sourcepathTextThe relative (to sdb) or absolute path to a source directory.N/ANo

sourcepathclear

Removes all source paths being used for source lookup.

Steps

stepin

From the current position in the active thread, steps into the next location on a different line. For function calls, this enters into the function. Otherwise, the position is moved to the next line.

stepinm

From the current position in the active thread, steps into the next available location, including any newly-pushed frames.

stepout

From the current position in the active thread, steps into the next location on a different line. This will finish evaluating the current function where the thread is positioned and land on the line where the function was called.

stepoutm

From the current position in the active thread, steps into the next available location, stepping out of the current frame.

stepover

From the current position in the active thread, steps into the next location on a different line. For function calls, this will evaluate the function and continue to the next line.

stepoverm

From the current position in the active thread, steps into the next available location, stepping over any newly-pushed frames.

Threads

threads

Lists current threads in the remote JVM.

Argument NameTypeDescriptionDefaultRequired
threadGroupTextThe specific thread group whose threads to list.N/ANo

thread

Sets the active thread whose name matches the specified name. If no thread is specified, clears the active thread.

Argument NameTypeDescriptionDefaultRequired
threadTextThe name of the thread.N/ANo

suspend

Suspends the specified thread, or suspends all threads in the JVM if no thread is specified.

Argument NameTypeDescriptionDefaultRequired
threadTextThe name of the thread.N/ANo

resume

Resumes the specified thread, or resumes all threads in the JVM if no thread is specified.

Argument NameTypeDescriptionDefaultRequired
threadTextThe name of the thread.N/ANo

where

Dumps the current stack of frames (the locations) for the position of the specified thread, or active thread if no thread is specified.

Argument NameTypeDescriptionDefaultRequired
threadTextThe name of the thread.N/ANo

Thread Groups

threadgroups

Lists current thread groups in the remote JVM.

threadgroup

Sets the active thread group whose name matches the specified name. If no thread group is specified, clears the active thread group.

Argument NameTypeDescriptionDefaultRequired
threadGroupTextThe name of the thread group.N/ANo

Watchpoints

watch

Creates requests to watch a variable for access and modification attempts.

Argument NameTypeDescriptionDefaultRequired
classTextThe fully-qualified name of the class whose field to watch.N/AYes
fieldTextThe name of the field to watch.N/AYes

watcha

Creates requests to watch a variable for access attempts.

Argument NameTypeDescriptionDefaultRequired
classTextThe fully-qualified name of the class whose field to watch.N/AYes
fieldTextThe name of the field to watch.N/AYes

watchm

Creates requests to watch a variable for modification attempts.

Argument NameTypeDescriptionDefaultRequired
classTextThe fully-qualified name of the class whose field to watch.N/AYes
fieldTextThe name of the field to watch.N/AYes

watchlist

Lists all watchpoint requests.

unwatch

Removes a request watching both access and modification of a field. If no class or field is specified, all watchpoint requests for access and modification are removed. If a class is specified without a field, all watchpoints for the specific class for access and modification are removed.

Argument NameTypeDescriptionDefaultRequired
classTextThe fully-qualified name of the class whose field to watch. Can include wildcards if no field specified.N/ANo
fieldTextThe name of the field to watch.N/ANo

unwatcha

Removes a request watching both access of a field. If no class or field is specified, all watchpoint requests for access are removed. If a class is specified without a field, all watchpoints for the specific class for access are removed.

Argument NameTypeDescriptionDefaultRequired
classTextThe fully-qualified name of the class whose field to watch. Can include wildcards if no field specified.N/ANo
fieldTextThe name of the field to watch.N/ANo

unwatchm

Removes a request watching both modification of a field. If no class or field is specified, all watchpoint requests for modification are removed. If a class is specified without a field, all watchpoints for the specific class for modification are removed.

Argument NameTypeDescriptionDefaultRequired
classTextThe fully-qualified name of the class whose field to watch. Can include wildcards if no field specified.N/ANo
fieldTextThe name of the field to watch.N/ANo