src/jdk.jdi/share/man/jdb.1

*** 1,7 ****
! '\" t
! .\" Copyright (c) 1995, 2013, Oracle and/or its affiliates. All rights reserved.
  .\" DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
  .\"
  .\" This code is free software; you can redistribute it and/or modify it
  .\" under the terms of the GNU General Public License version 2 only, as
  .\" published by the Free Software Foundation.
--- 1,6 ----
! .\" Copyright (c) 1994, 2019, Oracle and/or its affiliates. All rights reserved.
  .\" DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
  .\"
  .\" This code is free software; you can redistribute it and/or modify it
  .\" under the terms of the GNU General Public License version 2 only, as
  .\" published by the Free Software Foundation.
*** 18,267 ****
  .\"
  .\" Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
  .\" or visit www.oracle.com if you need additional information or have any
  .\" questions.
  .\"
! .\"     Arch: generic
! .\"     Software: JDK 8
! .\"     Date: 21 November 2013
! .\"     SectDesc: Basic Tools
! .\"     Title: jdb.1
  .\"
! .if n .pl 99999
! .TH jdb 1 "21 November 2013" "JDK 8" "Basic Tools"
! .\" -----------------------------------------------------------------
! .\" * Define some portability stuff
! .\" -----------------------------------------------------------------
! .\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
! .\" http://bugs.debian.org/507673
! .\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html
! .\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
! .ie \n(.g .ds Aq \(aq
! .el       .ds Aq '
! .\" -----------------------------------------------------------------
! .\" * set default formatting
! .\" -----------------------------------------------------------------
! .\" disable hyphenation
! .nh
! .\" disable justification (adjust text to left margin only)
! .ad l
! .\" -----------------------------------------------------------------
! .\" * MAIN CONTENT STARTS HERE *
! .\" -----------------------------------------------------------------
! 
  .SH NAME    
! jdb \- Finds and fixes bugs in Java platform programs\&.
  .SH SYNOPSIS    
! .sp     
! .nf     
! 
! \fBjdb\fR [\fIoptions\fR] [\fIclassname\fR]  [\fIarguments\fR]
! .fi     
! .sp     
  .TP     
! \fIoptions\fR
! Command-line options\&. See Options\&.
  .TP     
! \fIclass\fRname
! Name of the main class to debug\&.
  .TP     
! \fIarguments\fR
! Arguments passed to the \f3main()\fR method of the class\&.
  .SH DESCRIPTION    
! The Java Debugger (JDB) is a simple command-line debugger for Java classes\&. The \f3jdb\fR command and its options call the JDB\&. The \f3jdb\fR command demonstrates the Java Platform Debugger Architecture (JDBA) and provides inspection and debugging of a local or remote Java Virtual Machine (JVM)\&. See Java Platform Debugger Architecture (JDBA) at http://docs\&.oracle\&.com/javase/8/docs/technotes/guides/jpda/index\&.html
! .SS START\ A\ JDB\ SESSION    
! There are many ways to start a JDB session\&. The most frequently used way is to have JDB launch a new JVM with the main class of the application to be debugged\&. Do this by substituting the \f3jdb\fR command for the \f3java\fR command in the command line\&. For example, if your application\&'s main class is \f3MyClass\fR, then use the following command to debug it under JDB:
! .sp     
! .nf     
! \f3jdb MyClass\fP
! .fi     
! .nf     
! \f3\fP
! .fi     
! .sp     
! When started this way, the \f3jdb\fR command calls a second JVM with the specified parameters, loads the specified class, and stops the JVM before executing that class\&'s first instruction\&.
! .PP
! Another way to use the \f3jdb\fR command is by attaching it to a JVM that is already running\&. Syntax for starting a JVM to which the \f3jdb\fR command attaches when the JVM is running is as follows\&. This loads in-process debugging libraries and specifies the kind of connection to be made\&.
! .sp     
! .nf     
! \f3java \-agentlib:jdwp=transport=dt_socket,server=y,suspend=n MyClass\fP
! .fi     
! .nf     
! \f3\fP
! .fi     
! .sp     
! You can then attach the \f3jdb\fR command to the JVM with the following command:
! .sp     
! .nf     
! \f3jdb \-attach 8000\fP
! .fi     
! .nf     
! \f3\fP
! .fi     
! .sp     
! The \f3MyClass\fR argument is not specified in the \f3jdb\fR command line in this case because the \f3jdb\fR command is connecting to an existing JVM instead of launching a new JVM\&.
! .PP
! There are many other ways to connect the debugger to a JVM, and all of them are supported by the \f3jdb\fR command\&. The Java Platform Debugger Architecture has additional documentation on these connection options\&.
! .SS BASIC\ JDB\ COMMANDS    
! The following is a list of the basic \f3jdb\fR commands\&. The JDB supports other commands that you can list with the \f3-help\fR option\&.
! .TP     
! help or ?
! The \f3help\fR or \f3?\fR commands display the list of recognized commands with a brief description\&.
! .TP     
! run
! After you start JDB and set breakpoints, you can use the \f3run\fR command to execute the debugged application\&. The \f3run\fR command is available only when the \f3jdb\fR command starts the debugged application as opposed to attaching to an existing JVM\&.
! .TP     
! cont
! Continues execution of the debugged application after a breakpoint, exception, or step\&.
! .TP     
! print
! Displays Java objects and primitive values\&. For variables or fields of primitive types, the actual value is printed\&. For objects, a short description is printed\&. See the dump command to find out how to get more information about an object\&.
! 
! \fINote:\fR To display local variables, the containing class must have been compiled with the \f3javac -g\fR option\&.
! 
! The \f3print\fR command supports many simple Java expressions including those with method invocations, for example:
! .sp     
! .nf     
! \f3print MyClass\&.myStaticField\fP
! .fi     
! .nf     
! \f3print myObj\&.myInstanceField\fP
! .fi     
! .nf     
! \f3print i + j + k (i, j, k are primities and either fields or local variables)\fP
! .fi     
! .nf     
! \f3print myObj\&.myMethod() (if myMethod returns a non\-null)\fP
! .fi     
! .nf     
! \f3print new java\&.lang\&.String("Hello")\&.length()\fP
! .fi     
! .nf     
! \f3\fP
! .fi     
! .sp     
! 
! .TP     
! dump
! For primitive values, the \f3dump\fR command is identical to the \f3print\fR command\&. For objects, the \f3dump\fR command prints the current value of each field defined in the object\&. Static and instance fields are included\&. The \f3dump\fR command supports the same set of expressions as the \f3print\fR command\&.
! .TP     
! threads
! List the threads that are currently running\&. For each thread, its name and current status are printed and an index that can be used in other commands\&. In this example, the thread index is 4, the thread is an instance of \f3java\&.lang\&.Thread\fR, the thread name is \f3main\fR, and it is currently running\&.
! .sp     
! .nf     
! \f34\&. (java\&.lang\&.Thread)0x1 main      running\fP
! .fi     
! .nf     
! \f3\fP
! .fi     
! .sp     
! 
! .TP     
! thread
! Select a thread to be the current thread\&. Many \f3jdb\fR commands are based on the setting of the current thread\&. The thread is specified with the thread index described in the threads command\&.
! .TP     
! where
! The \f3where\fR command with no arguments dumps the stack of the current thread\&. The \f3where\fR\f3all\fR command dumps the stack of all threads in the current thread group\&. The \f3where\fR\f3threadindex\fR command dumps the stack of the specified thread\&.
! 
! If the current thread is suspended either through an event such as a breakpoint or through the \f3suspend\fR command, then local variables and fields can be displayed with the \f3print\fR and \f3dump\fR commands\&. The \f3up\fR and \f3down\fR commands select which stack frame is the current stack frame\&.
! .SS BREAKPOINTS    
! Breakpoints can be set in JDB at line numbers or at the first instruction of a method, for example:
! .TP 0.2i    
! \(bu
! The command \f3stop at MyClass:22\fR sets a breakpoint at the first instruction for line 22 of the source file containing \f3MyClass\fR\&.
! .TP 0.2i    
! \(bu
! The command \f3stop in java\&.lang\&.String\&.length\fR sets a breakpoint at the beginning of the method \f3java\&.lang\&.String\&.length\fR\&.
! .TP 0.2i    
! \(bu
! The command \f3stop in MyClass\&.<clinit>\fR uses \f3<clinit>\fR to identify the static initialization code for \f3MyClass\fR\&.
! .PP
! When a method is overloaded, you must also specify its argument types so that the proper method can be selected for a breakpoint\&. For example, \f3MyClass\&.myMethod(int,java\&.lang\&.String)\fR or \f3MyClass\&.myMethod()\fR\&.
! .PP
! The \f3clear\fR command removes breakpoints using the following syntax: \f3clear MyClass:45\fR\&. Using the \f3clear\fR or \f3stop\fR command with no argument displays a list of all breakpoints currently set\&. The \f3cont\fR command continues execution\&.
! .SS STEPPING    
! The \f3step\fR command advances execution to the next line whether it is in the current stack frame or a called method\&. The \f3next\fR command advances execution to the next line in the current stack frame\&.
! .SS EXCEPTIONS    
! When an exception occurs for which there is not a \f3catch\fR statement anywhere in the throwing thread\&'s call stack, the JVM typically prints an exception trace and exits\&. When running under JDB, however, control returns to JDB at the offending throw\&. You can then use the \f3jdb\fR command to diagnose the cause of the exception\&.
! .PP
! Use the \f3catch\fR command to cause the debugged application to stop at other thrown exceptions, for example: \f3catch java\&.io\&.FileNotFoundException\fR or \f3catch\fR\f3mypackage\&.BigTroubleException\fR\&. Any exception that is an instance of the specified class or subclass stops the application at the point where it is thrown\&.
! .PP
! The \f3ignore\fR command negates the effect of an earlier \f3catch\fR command\&. The \f3ignore\fR command does not cause the debugged JVM to ignore specific exceptions, but only to ignore the debugger\&.
! .SH OPTIONS    
! When you use the \f3jdb\fR command instead of the \f3java\fR command on the command line, the \f3jdb\fR command accepts many of the same options as the \f3java\fR command, including \f3-D\fR, \f3-classpath\fR, and \f3-X\fR options\&. The following list contains additional options that are accepted by the \f3jdb\fR command\&.
! .PP
! Other options are supported to provide alternate mechanisms for connecting the debugger to the JVM it is to debug\&. For additional documentation about these connection alternatives, see Java Platform Debugger Architecture (JPDA) at http://docs\&.oracle\&.com/javase/8/docs/technotes/guides/jpda/index\&.html
! .TP
! -help
! .br
! Displays a help message\&.
! .TP
! -sourcepath \fIdir1:dir2: \&. \&. \&.\fR
! .br
! Uses the specified path to search for source files in the specified path\&. If this option is not specified, then use the default path of dot (\&.)\&.
! .TP
! -attach \fIaddress\fR
! .br
! Attaches the debugger to a running JVM with the default connection mechanism\&.
! .TP
! -listen \fIaddress\fR
! .br
! Waits for a running JVM to connect to the specified address with a standard connector\&.
! .TP
! -launch
! .br
! Starts the debugged application immediately upon startup of JDB\&. The \f3-launch\fR option removes the need for the \f3run\fR command\&. The debugged application is launched and then stopped just before the initial application class is loaded\&. At that point, you can set any necessary breakpoints and use the \f3cont\fR command to continue execution\&.
! .TP
! -listconnectors
! .br
! List the connectors available in this JVM\&.
! .TP
! -connect connector-name:\fIname1=value1\fR
! .br
! Connects to the target JVM with the named connector and listed argument values\&.
! .TP
! -dbgtrace [\fIflags\fR]
! .br
! Prints information for debugging the \f3jdb\fR command\&.
! .TP
! -tclient
! .br
! Runs the application in the Java HotSpot VM client\&.
! .TP
! -tserver
! .br
! Runs the application in the Java HotSpot VM server\&.
! .TP
! -J\fIoption\fR
! .br
! Passes \f3option\fR to the JVM, where option is one of the options described on the reference page for the Java application launcher\&. For example, \f3-J-Xms48m\fR sets the startup memory to 48 MB\&. See java(1)\&.
! .SH OPTIONS\ FORWARDED\ TO\ THE\ DEBUGGER\ PROCESS    
! .TP
! -v -verbose[:\fIclass\fR|gc|jni]
! .br
! Turns on verbose mode\&.
! .TP
! -D\fIname\fR=\fIvalue\fR
! .br
! Sets a system property\&.
! .TP
! -classpath \fIdir\fR
! .br
! Lists directories separated by colons in which to look for classes\&.
! .TP
! -X\fIoption\fR
! .br
! Nonstandard target JVM option\&.
! .SH SEE\ ALSO    
! .TP 0.2i    
! \(bu
! javac(1)
! .TP 0.2i    
! \(bu
! java(1)
! .TP 0.2i    
! \(bu
! javap(1)
! .RE
! .br
! 'pl 8.5i
! 'bp
--- 17,263 ----
  .\"
  .\" Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
  .\" or visit www.oracle.com if you need additional information or have any
  .\" questions.
  .\"
! .\" Automatically generated by Pandoc 2.3.1
  .\"
! .TH "JDB" "1" "2018" "JDK 13" "JDK Commands"
! .hy
  .SH NAME
! .PP
! jdb \- find and fix bugs in Java platform programs
  .SH SYNOPSIS
! .PP
! \f[CB]jdb\f[R] [\f[I]options\f[R]] [\f[I]classname\f[R]]
! [\f[I]arguments\f[R]]
  .TP
! .B \f[I]options\f[R]
! This represents the \f[CB]jdb\f[R] command\-line options.
! See \f[B]Options for the jdb command\f[R].
! .RS
! .RE
  .TP
! .B \f[I]classname\f[R]
! This represents the name of the main class to debug.
! .RS
! .RE
  .TP
! .B \f[I]arguments\f[R]
! This represents the arguments that are passed to the \f[CB]main()\f[R]
! method of the class.
! .RS
! .RE
  .SH DESCRIPTION
! .PP
! The Java Debugger (JDB) is a simple command\-line debugger for Java
! classes.
! The \f[CB]jdb\f[R] command and its options call the JDB.
! The \f[CB]jdb\f[R] command demonstrates the Java Platform Debugger
! Architecture and provides inspection and debugging of a local or remote
! JVM.
! .SH START A JDB SESSION
! .PP
! There are many ways to start a JDB session.
! The most frequently used way is to have the JDB launch a new JVM with
! the main class of the application to be debugged.
! Do this by substituting the \f[CB]jdb\f[R] command for the \f[CB]java\f[R]
! command in the command line.
! For example, if your application\[aq]s main class is \f[CB]MyClass\f[R],
! then use the following command to debug it under the JDB:
! .RS
! .PP
! \f[CB]jdb\ MyClass\f[R]
! .RE
! .PP
! When started this way, the \f[CB]jdb\f[R] command calls a second JVM with
! the specified parameters, loads the specified class, and stops the JVM
! before executing that class\[aq]s first instruction.
! .PP
! Another way to use the \f[CB]jdb\f[R] command is by attaching it to a JVM
! that\[aq]s already running.
! Syntax for starting a JVM to which the \f[CB]jdb\f[R] command attaches
! when the JVM is running is as follows.
! This loads in\-process debugging libraries and specifies the kind of
! connection to be made.
! .RS
! .PP
! \f[CB]java\ \-agentlib:jdwp=transport=dt_socket,server=y,suspend=n\ MyClass\f[R]
! .RE
! .PP
! You can then attach the \f[CB]jdb\f[R] command to the JVM with the
! following command:
! .RS
! .PP
! \f[CB]jdb\ \-attach\ 8000\f[R]
! .RE
! .PP
! 8000 is the address of the running JVM.
! .PP
! The \f[CB]MyClass\f[R] argument isn\[aq]t specified in the \f[CB]jdb\f[R]
! command line in this case because the \f[CB]jdb\f[R] command is connecting
! to an existing JVM instead of launching a new JVM.
! .PP
! There are many other ways to connect the debugger to a JVM, and all of
! them are supported by the \f[CB]jdb\f[R] command.
! The Java Platform Debugger Architecture has additional documentation on
! these connection options.
! .SH BREAKPOINTS
! .PP
! Breakpoints can be set in the JDB at line numbers or at the first
! instruction of a method, for example:
! .IP \[bu] 2
! The command \f[CB]stop\ at\ MyClass:22\f[R] sets a breakpoint at the first
! instruction for line 22 of the source file containing \f[CB]MyClass\f[R].
! .IP \[bu] 2
! The command \f[CB]stop\ in\ java.lang.String.length\f[R] sets a breakpoint
! at the beginning of the method \f[CB]java.lang.String.length\f[R].
! .IP \[bu] 2
! The command \f[CB]stop\ in\ MyClass.<clinit>\f[R] uses \f[CB]<clinit>\f[R]
! to identify the static initialization code for \f[CB]MyClass\f[R].
! .PP
! When a method is overloaded, you must also specify its argument types so
! that the proper method can be selected for a breakpoint.
! For example, \f[CB]MyClass.myMethod(int,java.lang.String)\f[R] or
! \f[CB]MyClass.myMethod()\f[R].
! .PP
! The \f[CB]clear\f[R] command removes breakpoints using the following
! syntax: \f[CB]clear\ MyClass:45\f[R].
! Using the \f[CB]clear\f[R] or \f[CB]stop\f[R] command with no argument
! displays a list of all breakpoints currently set.
! The \f[CB]cont\f[R] command continues execution.
! .SH STEPPING
! .PP
! The \f[CB]step\f[R] command advances execution to the next line whether
! it\[aq]s in the current stack frame or a called method.
! The \f[CB]next\f[R] command advances execution to the next line in the
! current stack frame.
! .SH EXCEPTIONS
! .PP
! When an exception occurs for which there isn\[aq]t a \f[CB]catch\f[R]
! statement anywhere in the throwing thread\[aq]s call stack, the JVM
! typically prints an exception trace and exits.
! When running under the JDB, however, control returns to the JDB at the
! offending throw.
! You can then use the \f[CB]jdb\f[R] command to diagnose the cause of the
! exception.
! .PP
! Use the \f[CB]catch\f[R] command to cause the debugged application to stop
! at other thrown exceptions, for example:
! \f[CB]catch\ java.io.FileNotFoundException\f[R] or \f[CB]catch\f[R]
! \f[CB]mypackage.BigTroubleException\f[R].
! Any exception that\[aq]s an instance of the specified class or subclass
! stops the application at the point where the exception is thrown.
! .PP
! The \f[CB]ignore\f[R] command negates the effect of an earlier
! \f[CB]catch\f[R] command.
! The \f[CB]ignore\f[R] command doesn\[aq]t cause the debugged JVM to ignore
! specific exceptions, but only to ignore the debugger.
! .SH OPTIONS FOR THE JDB COMMAND
! .PP
! When you use the \f[CB]jdb\f[R] command instead of the \f[CB]java\f[R]
! command on the command line, the \f[CB]jdb\f[R] command accepts many of
! the same options as the \f[CB]java\f[R] command.
! .PP
! The following options are accepted by the \f[CB]jdb\f[R] command:
! .TP
! .B \f[CB]\-help\f[R]
! Displays a help message.
! .RS
! .RE
! .TP
! .B \f[CB]\-sourcepath\f[R] \f[I]dir1\f[R]\f[CB]:\f[R]\f[I]dir2\f[R]\f[CB]:\f[R]...
! Uses the specified path to search for source files in the specified
! path.
! If this option is not specified, then use the default path of dot
! (\f[CB]\&.\f[R]).
! .RS
! .RE
! .TP
! .B \f[CB]\-attach\f[R] \f[I]address\f[R]
! Attaches the debugger to a running JVM with the default connection
! mechanism.
! .RS
! .RE
! .TP
! .B \f[CB]\-listen\f[R] \f[I]address\f[R]
! Waits for a running JVM to connect to the specified address with a
! standard connector.
! .RS
! .RE
! .TP
! .B \f[CB]\-listenany\f[R]
! Waits for a running JVM to connect at any available address using a
! standard connector.
! .RS
! .RE
! .TP
! .B \f[CB]\-launch\f[R]
! Starts the debugged application immediately upon startup of the
! \f[CB]jdb\f[R] command.
! The \f[CB]\-launch\f[R] option removes the need for the \f[CB]run\f[R]
! command.
! The debugged application is launched and then stopped just before the
! initial application class is loaded.
! At that point, you can set any necessary breakpoints and use the
! \f[CB]cont\f[R] command to continue execution.
! .RS
! .RE
! .TP
! .B \f[CB]\-listconnectors\f[R]
! Lists the connectors available in this JVM.
! .RS
! .RE
! .TP
! .B \f[CB]\-connect\f[R] \f[I]connector\-name\f[R]\f[CB]:\f[R]\f[I]name1\f[R]\f[CB]=\f[R]\f[I]value1\f[R]....
! Connects to the target JVM with the named connector and listed argument
! values.
! .RS
! .RE
! .TP
! .B \f[CB]\-dbgtrace\f[R] [\f[I]flags\f[R]]
! Prints information for debugging the \f[CB]jdb\f[R] command.
! .RS
! .RE
! .TP
! .B \f[CB]\-tclient\f[R]
! Runs the application in the Java HotSpot VM client.
! .RS
! .RE
! .TP
! .B \f[CB]\-tserver\f[R]
! Runs the application in the Java HotSpot VM server.
! .RS
! .RE
! .TP
! .B \f[CB]\-J\f[R]\f[I]option\f[R]
! Passes \f[I]option\f[R] to the JVM, where option is one of the options
! described on the reference page for the Java application launcher.
! For example, \f[CB]\-J\-Xms48m\f[R] sets the startup memory to 48 MB.
! See \f[I]Overview of Java Options\f[R] in \f[B]java\f[R].
! .RS
! .RE
! .PP
! The following options are forwarded to the debuggee process:
! .TP
! .B \f[CB]\-v\f[R] or \f[CB]\-verbose\f[R][\f[CB]:\f[R]\f[I]class\f[R]|\f[CB]gc\f[R]|\f[CB]jni\f[R]]
! Turns on the verbose mode.
! .RS
! .RE
! .TP
! .B \f[CB]\-D\f[R]\f[I]name\f[R]\f[CB]=\f[R]\f[I]value\f[R]
! Sets a system property.
! .RS
! .RE
! .TP
! .B \f[CB]\-classpath\f[R] \f[I]dir\f[R]
! Lists directories separated by colons in which to look for classes.
! .RS
! .RE
! .TP
! .B \f[CB]\-X\f[R] \f[I]option\f[R]
! A nonstandard target JVM option.
! .RS
! .RE
! .PP
! Other options are supported to provide alternate mechanisms for
! connecting the debugger to the JVM that it\[aq]s to debug.